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.
"},{"location":"#social-media","title":"Social Media","text":"YouTube
BlogSpot
"},{"location":"#documentation","title":"Documentation","text":"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.
"},{"location":"#video-tutorials","title":"Video Tutorials","text":"You can watch many tutorial videos on the MeshCentral YouTube Channel. Two videos to get started involve installation and basic usages.
Installing MeshCentral on Windows, Linux and macOS. MeshCentral - Installation
Basic Usages including installing the agent and remote desktop, terminal and file access. MeshCentral - Basics
MeshCentral support for two-factor authentication. MeshCentral - Two Factor Authentication
How to setup MeshCentral with the NGINX reverse proxy. MeshCentral - NGINX Reverse Proxy
Installing and using the MeshCentral Android agent. MeshCentral - Android
Using MeshCentral Router to port map TCP connections. MeshCentral - Basics
"},{"location":"#feedback","title":"Feedback","text":"If you encounter a problem or have a suggestion to improve the product, you may file an issue report
If you are filing a problem report, you should include:
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.
"},{"location":"design/","title":"Design and Architecture","text":"Design and Architecture Guide as .pdf as .odt
"},{"location":"design/#video-walkthru","title":"Video Walkthru","text":""},{"location":"design/#abstract","title":"Abstract","text":"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. The software and added documentation and tutorial videos are available at: https://www.meshcommander.com/meshcentral2
"},{"location":"design/#introduction","title":"Introduction","text":"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.
"},{"location":"design/#goals-requirements","title":"Goals & Requirements","text":"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\u2019s important to have software that is as flexible as possible. Additionally, there are many other goals:
Basically, all the requirements you would expect from open source software that can go viral. Since this software is sponsored by Intel, it\u2019s going to support Intel\u00ae AMT really well, making it possible to manage a remote computer regardless of its OS or power state. Intel\u00ae AMT is not required to use this software, however it\u2019s a great fit.
"},{"location":"design/#design-overview","title":"Design Overview","text":"In this section, we do a very high level overview of MeshCentral\u2019s 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\u00ae AMT (Intel\u00ae 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\u2019s 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\u2019s behavior instantly.
Another interesting design decision is that MeshCentral makes almost no use of RESTful API\u2019s. 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.
"},{"location":"design/#meshcentral-server","title":"MeshCentral server","text":"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 \u201cnpm install meshcentral\u201d once NodeJS is installed. MeshCentral will work on Node 6.x and higher.
"},{"location":"design/#dependencies","title":"Dependencies","text":"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 \u201chard coded\u201d, there are a few more that are installed only when needed. These are:
"},{"location":"design/#node-windows","title":"node-windows","text":"greenlock, le-store-certbot, le-challenge-fs: Installed on all Windows install. Allows background service install:
le-acme-core: Installed only when Let\u2019s 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.
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.
"},{"location":"design/#folders","title":"Folders","text":"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.
package.json: Description of the MeshCentral package on NPM. sample-config.json: A sample \u201cconfig.json\u201d file to get started. readme.txt: Readme file published with the MeshCentral package.
amtevents.js | Used to decode Intel AMT WSMAN events.\n amtmanager.js | Used to handle Intel AMT/CIRA things.\n amtprovisioningserver.js | Used to Provision Intel AMT on a Local Network.\n amtscanner.js | Used to scan a local network for Intel AMT machines. \n amtscript.js | Used to run Intel AMT scripts from MeshCommander. \n certoperations.js | Used to generate and perform certificate operations. \n common.js | Various commonly used methods.\n crowdsec.js | Used to handle all crowdsec security features \n db.js | Used to access the MongoDB or NeDB database. \n exeHandler.js | Used to modify windows executables.\n firebase.js | Used to handle Google Firebase things.\n interceptor.js | Used to insert credentials in an HTTP stream. \n letsencrypt.js | Used to obtain and use a Let\u2019s Encrypt certificate.\n mcrec.js | Standalone Session Recording Indexer.\n meshaccelerator.js | Used to offload RSA sign to other CPU cores. \n meshagent.js | Used to communicate to agents.\n meshbot.js | Sample bot to connect to meshcentral and preform various tasks \n meshcentral.js | The is the main module, gets the server started.\n meshctrl.js | MeshCtrl performs command line actions on a MeshCentral server.\n meshcore.js | Main Agent Code that runs on your remote devices.\n meshdesktopmultiplex.js | Used to handle remote desktop multiplexing.\n meshdevicefile.js | Used to handle file download requests.\n meshipkvm.js | Used to handle IP KVM integration\n meshmail.js | Used to send SMTP mails.\n meshmessaging.js | Used to handle all users messaging methods like 2FA.\n meshrelay.js | Used to relay agent and browser web socket connections. \n meshscanner.js | MeshCentral server discovery when in LAN mode.\n meshsms.js | Used to handle all users sms methods.\n meshuser.js | Used to communicate with browsers. \n mpsserver.js | Used to communicate to Intel\u00ae AMT CIRA.\n mqttbroker.js | Used to create/handle an MQTT broker (beta) \n multiserver.js | Used for server-to-server communication. \n pass.js | Performs password hash + salt. \n redirserver.js | Used to handle HTTP traffic. \n swarmserver.js | Used to upgrade legacy MeshCentralv1 agents. \n webauthn.js | Handles all WebAuthN things.\n webrelayserver.js | Used for all HTTP/HTTPS web relaying from agents. \n webserver.js | Handles HTTPS traffic. \n winservice.js | Server background install on Windows.\nAt a high level, the MeshCentral.js file will get the server started. By default, it will start the 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.
"},{"location":"design/#server-database","title":"Server database","text":"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\u2019t want the added learning curve of MongoDB for people that don\u2019t 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 \u201cdb.js\u201d file handles both, almost the same way and the exact database in use is completely abstracted from the rest of the server code.
"},{"location":"design/#certificates","title":"Certificates","text":"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\u2019s critical security assets.
"},{"location":"design/#server-certificates","title":"Server Certificates","text":"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 \u201cmeshcentral-data\u201d folder. The four certificates are:
"},{"location":"design/#server-root","title":"Server root","text":"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\u2019s 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 \u201c--fastcert\" is used, in that case a RSA2048 certificate is generated.
"},{"location":"design/#mps-certificate","title":"MPS certificate","text":"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\u2019s 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.
"},{"location":"design/#web-certificate","title":"Web certificate","text":"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 \u201c--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:
agentserver-cert-public.crt
This certificate is used to authenticate the server to agents. It\u2019s 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 \u201c--fastcert\" is used, in that case a RSA2048 certificate is generated.
The \u201cmeshcentral-data\u201d folder contains critical server information including private keys therefore, it\u2019s important that it be well protected. It\u2019s important to backup the \u201cmeshcentral-data\u201d folder and keep the backup in a secure place. If, for example the \u201cagent certificate\u201d 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 \u201cmeshcentral-data\u201d folder back with these certificates should allow the server to resume normal operations and accept connections for Intel AMT and agents as before.
"},{"location":"design/#agent-certificates","title":"Agent Certificates","text":"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.
"},{"location":"design/#agent-root-certificate","title":"Agent root certificate","text":"This certificate is the root trust of the agent. The SHA384 hash of this certificates public key is the agent\u2019s 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\u2019s identifier after the agent sent a signed proof to the server. This certificate is also used to sign the secondary certificate below when it\u2019s needed.
"},{"location":"design/#secondary-certificate","title":"Secondary certificate","text":"This is a certificate signed by the agent root above. It\u2019s 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\u2019t 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 \u201cmeshagent.db\u201d file and to not give important information to untrusted agents.
"},{"location":"design/#tls-security","title":"TLS Security","text":"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.
"},{"location":"design/#meshcentral-https-port-443","title":"MeshCentral HTTPS port 443","text":"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) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA384 (0xc028) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA (0xc014) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_GCM\\_SHA256 (0xc02f) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA256 (0xc027) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA (0xc013) \nNote 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.
"},{"location":"design/#meshcentral-mps-port-4433","title":"MeshCentral MPS port 4433","text":"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\u2019t 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) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA384 (0xc028) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA (0xc014) \nTLS\\_RSA\\_WITH\\_AES\\_256\\_GCM\\_SHA384 (0x9d) \nTLS\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA256 (0x3d) \nTLS\\_RSA\\_WITH\\_AES\\_256\\_CBC\\_SHA (0x35) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_GCM\\_SHA256 (0xc02f) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA256 (0xc027) \nTLS\\_ECDHE\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA (0xc013) \nTLS\\_RSA\\_WITH\\_AES\\_128\\_GCM\\_SHA256 (0x9c) \nTLS\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA256 (0x3c) \nTLS\\_RSA\\_WITH\\_AES\\_128\\_CBC\\_SHA (0x2f) \nThe suites starting with \u201cTLS_RSA_\u201d don\u2019t 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.
"},{"location":"design/#agent-to-server-handshake","title":"Agent to server handshake","text":"One interesting aspect of MeshCentral\u2019s 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\u2019s 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\u2019s 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\u2019s Encrypt certificates are valid 90 days. Agents need to be able to validate a specific server for a long time and don\u2019t really need to trust anything else except one specific server. We also don\u2019t 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 \u201couter\u201d 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\u2019s 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 \u201cpins\u201d the outer web certificate. That is, the server both confirms it\u2019s 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 \u201cidentities\u201d 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\u2019t 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.
"},{"location":"design/#browser-to-agent-relay-and-webrtc","title":"Browser to agent relay and WebRTC","text":"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 \u201cpipe\u201d 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 \u201cc\u201d 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\u2019s 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\u2019s 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\u2019s 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\u2019s 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.
"},{"location":"design/#messenger","title":"Messenger","text":"MeshCentral includes its own messaging web application it can be used to chat, transfer files and optionally used for audio and video chat. It\u2019s 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 \u201cc\u201d 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.
"},{"location":"design/#additional-resources","title":"Additional Resources","text":"In addition to this document, there are a growing set of MeshCentral resources at: https://www.meshcommander.com/meshcentral2. This includes an Installer\u2019s documents, a User\u2019s Guide and plenty of YouTube tutorial videos. For developers, it\u2019s best to start on the MeshCentral GitHub repository at: https://github.com/Ylianst/MeshCentral. If any issues are found, it\u2019s best to create a new issue in GitHub or mail ylianst@gmail.com
"},{"location":"design/#conclusion","title":"Conclusion","text":"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\u2019s hoped that this document will encourage developers to take a look at MeshCentral for more usages and review its security in detail. MeshCentral\u2019s 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.
"},{"location":"design/#license","title":"License","text":"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
"},{"location":"how-to-contribute/","title":"Contribute to MeshCentral","text":""},{"location":"how-to-contribute/#contributing-to-meshcentral-via-github-pull-request","title":"Contributing to MeshCentral via GitHub Pull Request","text":"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
Review Your Changes: Before submitting your work, carefully review the changes you\u2019ve made. Check the \"Files Changed\" section on GitHub to ensure that all modifications are intended and correctly implemented.
Submit a Pull Request
master branch of the main MeshCentral repository.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\u2019s 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!
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.
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.
SET (F1).Repeat Translation: Continue translating by repeating steps 5 and 6 for other texts as desired.
Save and Apply Translations
SAVE TO SERVER (F3) to save your translations to meshcentral-data/translate.json locally in your MeshCentral server.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\u2019s crucial to restart MeshCentral to ensure that the translated files are picked up correctly.
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.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.
"},{"location":"install/","title":"Quick Start Guide","text":""},{"location":"install/#installation","title":"Installation","text":"Getting started is easy. If you don't have it already, install NodeJS. Then, create an empty folder and do this:
npm install meshcentral\nnode node_modules/meshcentral\nThat's it. MeshCentral will set itself up and start managing computers on your local network. By default it will be setup in LAN mode and agents you install will multicast on the local network to find the server. To setup the server so that agents use a well known DNS name and to start customizing your server, go in the \"meshcentral-data\" folder and edit the config.json file. The configuration file must be valid JSON, you can use this link to validate the file format.
For Windows users, you can download the MeshCentral Installer that will automate installation of NodeJS and provide basic configuration of the server. This option is not recommended for advanced users.
Win32 MeshCentral Installer
By default, MeshCentral will use NeDB as this is the built-in database. For more advanced users, it's recommended to switch to using MongoDB. MeshCentral can be installed on a very small server. A Raspberry Pi or AWS t3.nano running Amazon Linux 2 instance for 5$ a month will do just fine for managing up to a few hundred devices.
You can run the MeshCentral Server with --help to get options for background installation.
"},{"location":"install/#configuration","title":"Configuration","text":"Once you get MeshCentral installed, the first user account that is created will be the server administrator. So, don't delay and navigate to the login page and create a new account. You can then start using your server right away. A lot of the fun with MeshCentral is the 100's of configuration options that are available in the config.json file. You can put your own branding on the web pages, setup a SMTP email server, SMS services and much more.
You can look here for simple config.json, here for a more advanced configuration and here for all possible configuration options. You can also take a look at the tutorial videos for additional help.
"},{"location":"install/#video-walkthru","title":"Video Walkthru","text":""},{"location":"install/install2/","title":"Full Install Guide","text":""},{"location":"install/install2/#abstract","title":"Abstract","text":"This guide is specifically intended to help users install MeshCentral from start to finish. Once installed, you can take a look at the MeshCentral user\u2019s guide for information on how to configure MeshCentral for your specific use. In this document, we will look at installing MeshCentral on AWS Linux, Raspberry Pi and Ubuntu.
"},{"location":"install/install2/#docker","title":"Docker","text":"https://github.com/Ylianst/MeshCentral/pkgs/container/meshcentral
docker pull ghcr.io/ylianst/meshcentral:master\nWarning
Do not use the built in mesh update function. Update docker the docker way.
"},{"location":"install/install2/#docker-compose","title":"Docker Compose","text":"version: '3'\nservices:\n meshcentral:\n restart: unless-stopped # always restart the container unless you stop it\n image: ghcr.io/ylianst/meshcentral:1.1.27 # 1.1.27 is a version number OR use master for the master branch of bug fixes\n ports:\n - 80:80 # HTTP\n - 443:443 # HTTPS\n - 4433:4433 # AMT (Optional)\n volumes:\n - data:/opt/meshcentral/meshcentral-data # config.json and other important files live here\n - user_files:/opt/meshcentral/meshcentral-files # where file uploads for users live\n - backup:/opt/meshcentral/meshcentral-backups # location for the meshcentral backups - this should be mounted to an external storage\n - web:/opt/meshcentral/meshcentral-web # location for site customization files\nvolumes:\n data:\n driver: local\n user_files:\n driver: local\n backup:\n driver: local\n web:\n driver: local\nFor some who want to skip this document entirely, there are quick install scripts that will get a MeshCentral2 instance up and running on Linux in a few minutes. These scripts will pretty much do what this document explains very rapidly. Right now, there are two such scripts available:
"},{"location":"install/install2/#amazon-linux-2","title":"Amazon Linux 2","text":"For Amazon EC2 users, that want to manage 100 devices or less. Launch a t3.nano or t3.micro EC2 instance with Amazon Linux 2 with TCP ports 22 (SSH), 80 (HTTP), 443 (HTTPS) and 4433 (CIRA) open. Then login as ec2-user and enter the following commands:
wget https://meshcentral.com/scripts/mc-aws-linux2.sh\nchmod 755 mc-aws-linux2.sh\n./mc-aws-linux2.sh\nThis will download the fast install script and once run, will install nodejs, meshcentral, setup systemd and start the server. For a larger instance like a t3.small, t3.medium or larger you can run the following that does the same but also installs MongoDB.
wget https://meshcentral.com/scripts/mc-aws-linux2-mongo.sh\nchmod 755 mc-aws-linux2-mongo.sh\n./mc-aws-linux2-mongo.sh\nAfter these scripts are run, try accessing the server using a browser. MeshCentral will take a minute or two to create certificates after that, the server will be up. The first account to be created will be the site administrator \u2013 so don\u2019t delay and create an account right away. Once running, move on to the MeshCentral\u2019s user\u2019s guide to configure your new server.
"},{"location":"install/install2/#microsoft-azure","title":"Microsoft Azure","text":"For 100 devices or less, launch an instance of Ubuntu 18.04 using a small B1s instance. Set the username to default in all lower case and open ports 22, 80, 443 and 3389 using the basic network profile. Then start the instance and run the following lines.
wget https://meshcentral.com/scripts/mc-azure-ubuntu1804.sh\nchmod 755 mc-azure-ubuntu1804.sh\n./mc-azure-ubuntu1804.sh\nIn this situation, port 3389 will be used to receive Intel AMT CIRA connections instead of port 4433. After these scripts are run, try accessing the server using a browser. MeshCentral will take a minute or two to create certificates after that, the server will be up. The first account to be created will be the site administrator \u2013 so don\u2019t delay and create an account right away. Once running, move on to the MeshCentral\u2019s user\u2019s guide to configure your new server.
"},{"location":"install/install2/#server-security-adding-crowdsec","title":"Server Security - Adding Crowdsec","text":"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.
"},{"location":"install/install2/#video-walkthru","title":"Video Walkthru","text":""},{"location":"install/install2/#windows-installation","title":"Windows Installation","text":"MeshCentral is constructed entirely with NodeJS, an asynchronous event driven JavaScript runtime (https://nodejs.org/). A basic understanding on NodeJS may be preferable but not compulsory. MeshCentral server which heavily relies on NodeJS runtime will be able run on almost any computing platform with contemporary operating systems including Windows*, Linux* and macOS*.
There are two ways to get MeshCentral setup.
The MeshCentral installer tool for Microsoft Windows can be downloaded at https://www.meshcommander.com/meshcentral2 or by clicking this link. This tool will automatically detect and install NodeJS if needed. NodeJS will be downloaded from https://nodejs.org checked and installed. We recommend the installer be run on a modern version of Windows (.e.g. Win8.1, Win10, Win Server 2012* or better)
During installation, the installation tool will prompt for the following settings:
Note
If this option is disabled (unchecked), the server will run as a single-user server, no login screen will be presented and MeshCentral application will be limited to the server host machine only.
Note
Update check occurs at 0000 between 0100 hours (local time). During update, the server will not be accessible until update is completed.
Server Modes, LAN, WAN or Hybrid:
LAN mode: Recommended for small installation within a local network. Server host does not need a fixed IP address or DNS record to operate.
WAN or Hybrid modes: Server host will require a fixed IP address or DNS record to function correctly. If selected, user will need to enter server\u2019s DNS name or static IP address in the Server Name field. This name or IP address will be used by browsers and agents to connect back to the server, this name MUST be correct or the server will not work. If you do not have a fixed name, select LAN mode to get started.
Acquiring a static IP or DNS record is beyond the scope of this document. Please seek advice or consult your network administrator if unsure. If unsure, leave the settings as default (as-is) and proceed setup in LAN mode to manage computers that reside within the same network.
Once installed MeshCentral will run as a background Windows Service and can be accessed using a web browser with the link provided by the installer.
The installation tool can be run again to perform server update, re-installation or un-installation. When performing an update check, the tool will look at the currently installed version and compare it to the one present on NPM.
By default, MeshCentral will use TCP ports 80 (HTTP), 443 (HTTPS) and 4433 (Intel\u00ae AMT CIRA). The installer will add Windows Defender Firewall rules to allow incoming connections on these ports. In addition, if the server is in LAN or Hybrid mode, an addition rule on UDP port 16990 is added to allow for server discovery.
"},{"location":"install/install2/#npm-installation-for-advanced-users","title":"NPM Installation for Advanced Users","text":"For advanced users or administrators, MeshCentral can be installed with NPM, a NodeJS package manager that can be accessed via web browser (https://www.npmjs.com/) or command line tool, npm.
Note
As a prerequisite, NodeJS and NPM must be installed on host OS and HTTP/HTTPS proxy settings maybe required if server host resides behind a HTTP proxy server.
To begin, start a command line terminal (Windows Command Prompt or Linux Terminal) and type the following to verify if nodeJS and npm has been installed correctly as shown below a. To check on nodeJS installed version, type node \u2013v and hit enter key b. To check on npm installed version, type npm \u2013v and hit enter key
If MeshCentral installation is performed on a server host that resides behind a HTTP proxy, NPM\u2019s proxy settings must be updated with respective proxy settings associated with the network environment. Skip this step if not applicable.
.e.g. for http proxy `npm config set proxy http://proxy.com:88`\n.e.g. for https proxy `npm config set https-proxy http://proxy.com:88`\nMeshCentral and run the NPM install command as shown below: mkdir meshcentral\ncd meshcentral\nnpm install meshcentral\nsudo in front of npm install meshcentral.node node_modules/meshcentral [arguments]\nnode_modules/meshcentral folder as this may cause auto-install and self-update features to fail. Instead, go into the directory above node_modules and run node node_modules/meshcentral. Note: If MeshCentral is started without any arguments, default settings in LAN-only mode will be in effect and user/administrator will only be able to manage computers that reside within the local network.node node_modules/meshcentral --cert servername.domain.com\nnode node_modules/meshcentral --cert hostname.domain.com\nnode node_modules/meshcentral --cert 1.2.3.4\nNote
At this point, no user account will be created or available for the user hence 1st user account will be the most privileged user with Administrator rights
admin account immediately by navigating to https://127.0.0.1 with a web browser. Note: To run MeshCentral as a service, run it using --install argument. Once running, start a web browser and access MeshCentral application with respective URL.
On Windows, the built-in firewall will need to be configured to allow TCP ports 80, 443 and 4433 and sometimes UDP port 16990. The MeshCentral Windows Installer will add incoming rules for these ports automatically. If using the advanced NPM installation or when changing the default ports, it may be needed to add or edit these firewall rules. In this section we look at how to do this.
To get started, we need to go in the control panel, click System and Security then Windows Defender Firewall and Advanced Settings on the left side then click on Inbound rules. This will get us on the right place to add or edit firewall rules.
If the MeshCentral Windows Installer was used, the MeshCentral Server TCP ports and optionally MeshCentral Server UDP ports rules should already be present.
To edit an existing rule, simply double click on it. To change the allowed inbound ports, go to the Protocols and Ports tab and change the local ports.
To add a new firewall rule, click on the New Rule\u2026 then select Port and ok. TCP or UDP and enter the specific local ports needed and ok. Then click ok twice, enter the rule name and ok again.
Typically, inbound TCP ports 80, 443 and 4433 are used, but the rule can be added with different ports as needed.
"},{"location":"install/install2/#amazon-linux-2_1","title":"Amazon Linux 2","text":"In this section, we will look at installing MeshCentral on Amazon AWS with Amazon Linux 2. This is a low cost instance and a free tier is available so you can experiment or run a small instance of MeshCentral and it will work perfectly fine.
On AWS EC2, you can launch an instance and select Amazon Linux 2. In this case, it\u2019s the first option available.
When launching a new instance, you are asked to use or create a security group with the allowed inbound TCP and UDP ports. The security group should look like this:
All security group rules should have a source of 0.0.0.0/0 and ::/0. The last rule for port 8080 is only needed if migrating from a MeshCentral1 server, most people don\u2019t need it and should not be added.
If you are not going to be managing Intel AMT computers, you can remove port 4433. One can also remove port 80, however it\u2019s needed to get a Let\u2019s Encrypt certificate and useful to route users from the HTTP to the HTTPS web page.
For all the following sections, we assume that we are in the ec2-user home path. You can do:
cd ~\nThis will change the current path to the home folder.
"},{"location":"install/install2/#installing-nodejs","title":"Installing NodeJS","text":"To get started, launch an instance and start a SSH session to it. You can use SSH on Linux or Putty on Windows to login to the AWS instance.
The first thing to do is get NodeJS installed on the instance. We will be installing a long term support (LTS) version of NodeJS. Additional information on how to do this can be found here. We first install the node version manager then activate it and install the NodeJS LTS. It\u2019s done with 3 commands:
curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.8/install.sh | bash\n. ~/.nvm/nvm.sh\nnvm install --lts\nWe can test what version of NodeJS is installed using:
node -v\nIf we are going to run a large instance, it\u2019s best to use MongoDB as the database. If you are using a small instance, you can skip installing MongoDB and MeshCentral will use NeDB instead which is a light weight database that is probably great for managing less than 100 computers.
If you want to use MongoDB, we can install MongoDB Community Edition. More information on how to do this can be found here.
Using nano create the file /etc/yum.repos.d/mongodb-org-4.0.repo:
sudo nano /etc/yum.repos.d/mongodb-org-4.0.repo\nThen, put this in it:
[mongodb-org-4.0]\nname=MongoDB Repository\nbaseurl=https://repo.mongodb.org/yum/amazon/2/mongodb-org/4.0/x86_64/\ngpgcheck=1\nenabled=1\ngpgkey=https://www.mongodb.org/static/pgp/server-4.0.asc\nThis file will setup the repository that we will be using to bet MongoDB. Once done, you can install the package using yum and get it started like this:
sudo yum install -y mongodb-org\nsudo service mongod start\nTo verify that MongoDB is running, you can enter the MongoDB shell like this:
mongo --host 127.0.0.1:27017\nYou can leave the shell using Ctrl-C. The database and log files will be create at these locations:
/var/log/mongodb\n/var/lib/mongo\nThis is useful to know if you want to make a backup of the database file.
"},{"location":"install/install2/#port-permissions","title":"Port permissions","text":"On Linux, ports below 1024 are reserved for the root user. This is a security feature. In our case MeshCentral will need to listen to ports 80 and 443. To allow this, we need to allow node to listen to ports below 1024 like this:
whereis node\nnode: /home/ec2-user/.nvm/versions/node/v8.11.3/bin/node\n\nsudo setcap cap_net_bind_service=+ep /home/ec2-user/.nvm/versions/node/v8.11.3/bin/node\nWe first locate the node binary, using whereis node, we then use the setcap command to add permissions to node. Note that we take the path given by whereis and place it in the setcap command. The setcap command will set permissions allowing node to use ports 1024 and below. This permission may be lost when updating the Linux kernel, so this command may need to be applied again in some case.
It\u2019s almost time to install MeshCentral but first, we need to know the public name of our AWS instance, you can run the following command:
curl http://169.254.169.254/latest/meta-data/public-hostname\nIt will return the public name of the AWS instance, for example:
ec2-1-2-3-4.us-west-2.compute.amazonaws.com\nYou can use this name, or if you have another registered DNS name pointing to the server instance, you can also use that now. Note that you must setup any alternative name on your own, MeshCentral will not do this for you. This name must be correct and must resolve to this AWS instance as all mesh agents will use this name to connect back to this server.
Now, we can use the node package manager (NPM) to install MeshCentral.
npm install meshcentral\nWarning
Do not use sudo in front of npm install meshcentral.
After that, we can run MeshCentral for the first time. We want to run in WAN-only mode since we will not be managing any computers on the same local network at this server. We also want to create a server with a certificate name that is the same at the AWS instance name. So, we will use --wanonly and --cert [name] arguments to get the server started. For example:
node ./node_modules/meshcentral --wanonly --cert ec2-1-2-3-4.us-west-2.compute.amazonaws.com\nMeshCentral HTTP redirection web server running on port 80.\nGenerating certificates, may take a few minutes...\nGenerating root certificate...\nGenerating HTTPS certificate...\nGenerating MeshAgent certificate...\nGenerating Intel AMT MPS certificate...\nGenerating Intel AMT console certificate...\nMeshCentral Intel(R) AMT server running on ec2-54-245-141-130.us-west-2.compute.amazonaws.com:4433.\nMeshCentral HTTPS web server running on ec2-54-245-141-130.us-west-2.compute.amazonaws.com:443.\nServer has no users, next new account will be site administrator.\nYou can now open a browser to the name of the server, for example:
https://ec2-1-2-3-4.us-west-2.compute.amazonaws.com\nYou will see the server working as expected. You will get a certificate error since the server is used an untrusted certificate for now. Just ignore the error and see the MeshCentral User\u2019s Guide to fix this.
At this point, the server is usable but, there are two things that may still need to be done. First, if we opted to use MongoDB, we have to configure MeshCentral to use a MongoDB database. By default, NeDB will be used which should only be used for small deployments managing less than 100 computers. We also need to automatically start the server when the AWS instance starts.
To continue, stop the MeshCentral server with CTRL-C.
"},{"location":"install/install2/#configuring-for-mongodb","title":"Configuring for MongoDB","text":"By default, MeshCentral uses NeDB with a database file located in ~/meshcentral-data/meshcentral.db. This is great for small servers, but if we opted to install MongoDB, let\u2019s make use of it. We need to edit the config.json file located in the meshcentral-data folder.
nano ~/meshcentral-data/config.json\nThen, make the start of the file look like this:
{\n \"settings\": {\n \"MongoDb\": \"mongodb://127.0.0.1:27017/meshcentral\",\n \"WANonly\": true,\n \"_Port\": 443,\n \"_RedirPort\": 80,\n \"_AllowLoginToken\": true,\n \"_AllowFraming\": true,\n \"_WebRTC\": false,\n \"_ClickOnce\": false,\n \"_UserAllowedIP\" : \"127.0.0.1,::1,192.168.0.100\"\n },\n\u2026\n}\nIf you start with the default config.json created by MeshCentral, you will need to remove some _ characters in front of settings, mongodb and wanonly. You can also add a _ to other values.
You can then same the same and run MeshCentral again. This time, you don\u2019t need to specify the certificate name or --wanonly. You just need to run it like this:
node ./node_modules/meshcentral\nThe server should now run correctly and use MongoDB. You can even delete the file ~/meshcentral-data/meshcentral.db as it\u2019s not going to be used anymore. You can check that it runs correctly by browsing to the server\u2019s address again and creating a new account. The first account that is created will be administrator for the server, so don\u2019t delay and create the first account right away.
Once you are done, we can stop the server again using CTRL-C and in the next sections, we will look at starting the server in the background.
"},{"location":"install/install2/#manually-starting-the-server","title":"Manually starting the server","text":"We can manually start and stop the MeshCentral server in the background in different ways. In this section, we are going to create two commands mcstart and mcstop to take care of this. Type this to create the two commands:
echo \"node ./node_modules/meshcentral > stdout.txt 2> stderr.txt &\" > mcstart\nchmod 755 mcstart\n\necho \"pkill \u2013f node_modules/meshcentral\" > mcstop\nchmod 755 mcstop\nYou can now run the ./mcstart command to launch the server in the background and stop it using the ./mcstop to stop it. This should work pretty well, but if the AWS instance is ever stopped and started again, the server will not automatically launch.
Since Amazon Linux 2 supports systemd, we are going to use that to auto-start MeshCentral in the background. First, we need to know our own username and group. If we do ls -l in our home folder we get for example:
drwxr-xr-x 2 default default 4096 Jul 20 00:03 Desktop\ndrwxr-xr-x 2 default default 4096 Jul 20 00:03 Documents\ndrwxr-xr-x 2 default default 4096 Jul 20 00:03 Downloads\n\u2026\nNote the username and group name, in this example it\u2019s default for both. We need this information to create the system service description file. To create this file type:
sudo pico /etc/systemd/system/meshcentral.service\nThen enter the following lines:
[Unit]\nDescription=MeshCentral Server\n\n[Service]\nType=simple\nLimitNOFILE=1000000\nExecStart=/usr/bin/node /home/default/node_modules/meshcentral\nWorkingDirectory=/home/default\nEnvironment=NODE_ENV=production\nUser=default\nGroup=default\nRestart=always\n# Restart service after 10 seconds if node service crashes\n\nRestartSec=10\n# Set port permissions capability\nAmbientCapabilities=cap_net_bind_service\n\n[Install]\nWantedBy=multi-user.target\nNote that the user and group values have to be set correctly for your specific situation. Also, the ExecStart and WorkingDirectory lines includes the path to the user\u2019s home folder which includes the username in it. Make sure that is set correctly.
Once this is done, you can now start, enable, stop and disable using the following commands:
sudo systemctl enable meshcentral.service\nsudo systemctl start meshcentral.service\nsudo systemctl stop meshcentral.service\nsudo systemctl disable meshcentral.service\nType in the first two commands to start and enable the service. Enabling the service will make it automatically start when the computer restarts.
Once the server is launched, you can access it using a web browser as before. From this point on, refer to the MeshCentral User\u2019s Guide for information on how to configure and use MeshCentral.
"},{"location":"install/install2/#raspberry-pi","title":"Raspberry Pi","text":"In this section, we will look at installing MeshCentral on the famous Raspberry Pi. This computer\u2019s low price makes it a perfect always-on system for managing computers on a home or small business network. This installation will work on any version of the Raspberry Pi, but version 3 certainly much faster.
For this installation, we are going to use the Raspbian operating system. You can use the NOOBS version to install this operating system on your Raspberry Pi and install Raspbian. For best performance you can use the Raspbian Stretch Lite image which is much smaller and does not have the X desktop interface. To keep things even smaller, we are not going to be installing MongoDB, instead we are just going to be using NeBD as a database that comes by default with MeshCentral.
Start by opening a terminal. For all of the installation, we will assume we are the default pi user and we are in the home (~) folder. Let\u2019s get started by installing NodeJS.
sudo apt-get update\nsudo apt-get dist-upgrade\ncurl -sL https://deb.nodesource.com/setup_8.x | sudo -E bash\nsudo apt-get -y install nodejs\nWe can now check what version of Node was installed by typing:
node -v\nIf all goes well, we can now move on to port permissions and installing MeshCentral itself.
"},{"location":"install/install2/#port-permissions_1","title":"Port permissions","text":"On Linux, ports below 1024 are reserved for the root user. This is a security feature. In our case MeshCentral will need to listen to ports 80 and 443. To allow this, we need to allow node to listen to ports below 1024 like this:
whereis node\nnode: /usr/bin/node /usr/include/node /usr/share/man/man1/node.1.gz\n\nsudo setcap cap_net_bind_service=+ep /usr/bin/node\nWe first locate the node binary, using whereis node, we then use the setcap command to add permissions to node. Note that we take the path given by whereis and place it in the setcap command. The setcap command will set permissions allowing node to use ports 1024 and below. This permission may be lost when updating the Linux kernel, so this command may need to be applied again in some case.
Now, we can use the Node Package Manager (NPM) to install MeshCentral.
npm install meshcentral\nWarning
Do not use sudo in front of npm install meshcentral.
After that, we can run MeshCentral for the first time. We want to run in WAN-only mode since we will not be managing any computers on the same local network at this server. We also want to create a server with a certificate name that is the same at the AWS instance name. So, we will use --wanonly and --cert [name] arguments to get the server started. For example:
node node_modules/meshcentral --lanonly --fastcert\nAt this point, the server will create its certificates and start running.
MeshCentral HTTP redirection web server running on port 80.\nGenerating certificates, may take a few minutes...\nGenerating root certificate...\nGenerating HTTPS certificate...\nGenerating MeshAgent certificate...\nGenerating Intel AMT MPS certificate...\nGenerating Intel AMT console certificate...\nServer name not configured, running in LAN-only mode.\nMeshCentral HTTPS web server running on port 443.\nServer has no users, next new account will be site administrator.\nThe next step is to get the IP address of the Raspberry Pi. Use ipconfig:
eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500\n inet 192.168.2.162 netmask 255.255.255.0 broadcast 192.168.2.255\n inet6 fe80::8841:34b7:685:14a7 prefixlen 64 scopeid 0x20<link>\n ether b8:27:eb:01:13:3f txqueuelen 1000 (Ethernet)\n RX packets 58325 bytes 72302196 (68.9 MiB)\n RX errors 0 dropped 271 overruns 0 frame 0\n TX packets 28457 bytes 3576126 (3.4 MiB)\n TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0\nYou can now open a browser to the name of the server, for example:
https://192.168.2.162\nYou will see the server working as expected. You will get a certificate error since the server is used an untrusted certificate for now. Just ignore the error and see the MeshCentral User\u2019s Guide to fix this.
"},{"location":"install/install2/#configuring-for-lan-only-mode","title":"Configuring for LAN-only mode","text":"By default, MeshCentral will assume that you are managing devices both on a local network and on the internet. In the case of this Raspberry Pi installation, we only want to manage device on the local network and so, we can configure MeshCentral to do this. It will adapt the server for this usages. To do this, edit the config.json file:
pico ~/meshcentral-data/config.json\nThen, make the start of the file look like this:
{\n \"settings\": {\n \"LANonly\": true,\n \"FastCert\": true,\n \"_Port\": 443,\n \"_RedirPort\": 80,\n \"_AllowLoginToken\": true,\n \"_AllowFraming\": true,\n \"_WebRTC\": false,\n \"_ClickOnce\": false,\n \"_UserAllowedIP\" : \"127.0.0.1,::1,192.168.0.100\"\n },\n\u2026\n}\nWhile we are at it, we can put FastCert to true so that RSA2048 certificates are created instead of RSA3072. This is less secure but runs much faster on small processors like the Raspberry Pi. This is the same as specifying `--fastcert\" in the prior section.
We can manually start and stop the MeshCentral server in the background in different ways. In this section, we are going to create two commands mcstart and mcstop to take care of this. Type this to create the two commands:
echo \"node ./node_modules/meshcentral > stdout.txt 2> stderr.txt &\" > mcstart\nchmod 755 mcstart\n\necho \"pkill -f node_modules/meshcentral\" > mcstop\nchmod 755 mcstop\nYou can now run the ./mcstart command to launch the server in the background and stop it using the ./mcstop to stop it. This should work pretty well, but if the AWS instance is ever stopped and started again, the server will not automatically launch.
Since Raspbian OS supports systemd, we are going to use that to auto-start MeshCentral in the background. First, we need to know our own username and group. If we do ls -l in our home folder we
drwxr-xr-x 2 pi pi 4096 Jul 19 21:23 Desktop\ndrwxr-xr-x 2 pi pi 4096 Jun 26 18:23 Documents\ndrwxr-xr-x 2 pi pi 4096 Jun 26 18:23 Downloads\n\u2026\nNote the username and group name, in this example it\u2019s pi for both. We need this information to create the system service description file. To create this file type:
sudo nano /etc/systemd/system/meshcentral.service\n[Unit]\nDescription=MeshCentral Server\n\n[Service]\nType=simple\nLimitNOFILE=1000000\nExecStart=/usr/bin/node /home/pi/node_modules/meshcentral\nWorkingDirectory=/home/pi\nEnvironment=NODE_ENV=production\nUser=pi\nGroup=pi\nRestart=always\n# Restart service after 10 seconds if node service crashes\nRestartSec=10\n# Set port permissions capability\nAmbientCapabilities=cap_net_bind_service\n\n[Install]\nWantedBy=multi-user.target\nNote that the user and group values have to be set correctly for your specific situation. Also, the ExecStart and WorkingDirectory lines includes the path to the user\u2019s home folder which includes the username in it. Make sure that is set correctly.
Once this is done, you can now enable, start, stop and disable using the following commands:
sudo systemctl enable meshcentral.service\nsudo systemctl start meshcentral.service\nsudo systemctl stop meshcentral.service\nsudo systemctl disable meshcentral.service\nType in the first two commands to start and enable the service. Enabling the service will make it automatically start when the computer restarts.
Once the server is launched, you can access it using a web browser as before. From this point on, refer to the MeshCentral User\u2019s Guide for information on how to configure and use MeshCentral.
"},{"location":"install/install2/#ubuntu-1804","title":"Ubuntu 18.04","text":"In this section, we will look at installing MeshCentral on Ubuntu 18.04 LTS. This is a long term support of Ubuntu freely available for download at https://www.ubuntu.com. Both the desktop and server versions of Ubuntu will work. If this is a remote server and the desktop will not be needed, the server version of Ubuntu can be used. This section will describe a way to install MeshCentral in a user\u2019s home folder, however there is a more secure way to do it, see Increased Security Installation at the end of this section.
In all cases, MeshCentral must not be installed as root user. It\u2019s not secure and the instructions below will not work correctly.
"},{"location":"install/install2/#installing-nodejs_2","title":"Installing NodeJS","text":"The first thing to do is get NodeJS installed on the computer. We first install the node version manager then activate it and install the NodeJS LTS. It\u2019s done with 4 commands:
sudo add-apt-repository universe\nsudo apt update\nsudo apt install nodejs -y\nsudo apt install npm -y\nWe can test what version of Node and NPM are installed using:
node \u2013v\nnpm -v\nIf we are going to run a large instance, it\u2019s best to use MongoDB as the database. If you are using a small instance, you can skip installing MongoDB and MeshCentral will use NeDB instead which is a light weight database that is probably great for managing less than 100 computers.
If you want to use MongoDB, we can install MongoDB Community Edition. More information on how to do this for Ubuntu can be found here.
You can install the package using apt and get it started like this:
sudo apt install mongodb -y\nThen start the Mongodb service in the background and enable it for auto-restart.
sudo systemctl start mongodb\nsudo systemctl enable mongodb\nTo verify that MongoDB is running, you can enter the MongoDB shell like this:
mongo --host 127.0.0.1:27017\nYou can leave the shell using Ctrl-C. The database and log files will be create at these locations:
/var/log/mongodb\n/var/lib/mongo\nThis is useful to know if you want to make a backup of the database file.
"},{"location":"install/install2/#port-permissions_2","title":"Port permissions","text":"On Linux, ports below 1024 are reserved for the root user. This is a security feature. In our case MeshCentral will need to listen to ports 80 and 443. To allow this, we need to allow node to listen to ports below 1024 like this:
whereis node\nnode: /usr/bin/node /usr/include/node /usr/share/man/man1/node.1.gz\n\nsudo setcap cap_net_bind_service=+ep /usr/bin/node\nWe first locate the node binary, using whereis node, we then use the setcap command to add permissions to node. Note that we take the path given by whereis and place it in the setcap command. The setcap command will set permissions allowing node to use ports 1024 and below. This permission may be lost when updating the Linux kernel, so this command may need to be applied again in some case.
Now, we can use the node package manager (NPM) to install MeshCentral.
npm install meshcentral\nWarning
Do not use sudo in front of npm install meshcentral.
After that, we can run MeshCentral for the first time. For example:
node ./node_modules/meshcentral\nIf the computer has a well-known DNS name that users and agents will use to connect to this server, run MeshCentral like this:
node ./node_modules/meshcentral --cert example.servername.com\nAt this point, the server will create its certificates and start running.
MeshCentral HTTP redirection web server running on port 80.\nGenerating certificates, may take a few minutes...\nGenerating root certificate...\nGenerating HTTPS certificate...\nGenerating MeshAgent certificate...\nGenerating Intel AMT MPS certificate...\nGenerating Intel AMT console certificate...\nMeshCentral Intel(R) AMT server running on ec2-54-245-141-130.us-west-2.compute.amazonaws.com:4433.\nMeshCentral HTTPS web server running on ec2-54-245-141-130.us-west-2.compute.amazonaws.com:443.\nServer has no users, next new account will be site administrator.\nYou can now open a browser and try the server. If you can on the same computer, you navigate to this URL:
http://localhost\nIf installing on a server that does not have a desktop GUI, use a different computer and enter http:// followed by the IP address or name of the server you installed.
You should see the server working as expected. You will get a certificate error since the server is used an untrusted certificate for now. Just ignore the error and see the MeshCentral User\u2019s Guide to fix this.
At this point, the server is usable but, there are two things that may still need to be done. First, if we opted to use MongoDB, we have to configure MeshCentral to use a MongoDB database. By default, NeDB will be used which should only be used for small deployments managing less than 100 computers. We also need to automatically start the server when the computer starts.
To continue, stop the MeshCentral server with CTRL-C.
"},{"location":"install/install2/#configuring-for-mongodb_1","title":"Configuring for MongoDB","text":"By default, MeshCentral uses NeDB with a database file located in ~/meshcentral-data/meshcentral.db. This is great for small servers, but if we opted to install MongoDB, let\u2019s make use of it. We need to edit the config.json file located in the meshcentral-data folder.
pico ~/meshcentral-data/config.json\nThen, make the start of the file look like this:
{\n \"settings\": {\n \"MongoDb\": \"mongodb://127.0.0.1:27017/meshcentral\",\n \"WANonly\": true,\n \"_Port\": 443,\n \"_RedirPort\": 80,\n \"_AllowLoginToken\": true,\n \"_AllowFraming\": true,\n \"_WebRTC\": false,\n \"_ClickOnce\": false,\n \"_UserAllowedIP\" : \"127.0.0.1,::1,192.168.0.100\"\n },\n\u2026\n}\nIf you start with the default config.json created by MeshCentral, you will need to remove some _ characters in front of settings, mongodb and wanonly. You can also add a _ to other values. For details on all of the config.json options, including the WANonly option, refer to the MeshCentral User\u2019s Guide.
You can then save the config.json file and run MeshCentral again. This time, you don\u2019t need to specify the certificate name. You just need to run it like this:
node ./node_modules/meshcentral\nThe server should now run correctly and use MongoDB. You can even delete the file ~/meshcentral-data/meshcentral.db as it\u2019s not going to be used anymore. You can check that it runs correctly by browsing to the server\u2019s address again and creating a new account. The first account that is created will be administrator for the server, so don\u2019t delay and create the first account right away.
Once you are done, we can stop the server again using CTRL-C and in the next sections, we will look at starting the server in the background.
"},{"location":"install/install2/#manually-starting-the-server_2","title":"Manually starting the server","text":"We can manually start and stop the MeshCentral server in the background in different ways. In this section, we are going to create two commands mcstart and mcstop to take care of this. Type this to create the two commands:
echo \"node ./node_modules/meshcentral > stdout.txt 2> stderr.txt &\" > mcstart\nchmod 755 mcstart\n\necho \"pkill \u2013f node_modules/meshcentral\" > mcstop\nchmod 755 mcstop\nYou can now run the ./mcstart command to launch the server in the background and stop it using the ./mcstop to stop it. This should work pretty well, but if the AWS instance is ever stopped and started again, the server will not automatically launch.
Since Ubuntu 18.04 supports systemd, we are going to use that to auto-start MeshCentral in the background. First, we need to know our own username and group. If we do ls -l in our home folder we get for example:
drwxr-xr-x 2 default default 4096 Jul 20 00:03 Desktop\ndrwxr-xr-x 2 default default 4096 Jul 20 00:03 Documents\ndrwxr-xr-x 2 default default 4096 Jul 20 00:03 Downloads\n\u2026\nNote the username and group name, in this example it\u2019s default for both. We need this information to create the system service description file. To create this file type:
sudo pico /etc/systemd/system/meshcentral.service\nThen enter the following lines:
[Unit]\nDescription=MeshCentral Server\n\n[Service]\nType=simple\nLimitNOFILE=1000000\nExecStart=/usr/bin/node /home/default/node_modules/meshcentral\nWorkingDirectory=/home/default\nEnvironment=NODE_ENV=production\nUser=default\nGroup=default\nRestart=always\n# Restart service after 10 seconds if node service crashes\nRestartSec=10\n# Set port permissions capability\nAmbientCapabilities=cap_net_bind_service\n\n[Install]\nWantedBy=multi-user.target\nNote that the user and group values have to be set correctly for your specific situation. Also, the ExecStart and WorkingDirectory lines includes the path to the user\u2019s home folder which includes the username in it. Make sure that is set correctly. Lastly the path to node may need to be changed. Type whereis node to find the correct path.
Once this is done, you can now start, enable, stop and disable using the following commands:
sudo systemctl enable meshcentral.service\nsudo systemctl start meshcentral.service\nsudo systemctl stop meshcentral.service\nsudo systemctl disable meshcentral.service\nType in the first two commands to start and enable the service. Enabling the service will make it automatically start when the computer restarts.
Once the server is launched, you can access it using a web browser as before. From this point on, refer to the MeshCentral User\u2019s Guide for information on how to configure and use MeshCentral.
"},{"location":"install/install2/#increased-security-installation","title":"Increased Security Installation","text":"On Debian based Linux distributions like Ubuntu, a better and more secure way to install MeshCentral is to have it run within a user account this restricted privileges. When installed like this, the self-update capability of MeshCentral will not work. Instead of installing MeshCentral in the user\u2019s home folder, we install it in /opt/meshcentral and we create a meshcentral user that does not have rights to login or change any of the MeshCentral files. To do this, start by creating a new user called meshcentral
sudo useradd -r -d /opt/meshcentral -s /sbin/nologin meshcentral\nWe can then create the installation folder, install and change permissions of the files so that the meshcentral account gets read-only access to the files.
sudo mkdir /opt/meshcentral\ncd /opt/meshcentral\nsudo npm install meshcentral\nsudo -u meshcentral node ./node_modules/meshcentral\nThe last line will run MeshCentral manually and allow it to install any missing modules and create the MeshCentral data folders. Once it\u2019s running, press CTRL-C and continue. The following two lines will change the ownership of files to the meshcentral user and restrict access to the files.
sudo chown -R meshcentral:meshcentral /opt/meshcentral\nsudo chmod -R 755 /opt/meshcentral/meshcentral-*\nTo make this work, you will need to make MeshCentral work with MongoDB because the /meshcentral-data folder will be read-only. In addition, MeshCentral will not be able to update itself since the account does not have write access to the /node_modules files, so the update will have to be manual. First used systemctl to stop the MeshCentral server process, than use this:
cd /opt/meshcentral\nsudo npm install meshcentral\nsudo -u meshcentral node ./node_modules/meshcentral\nsudo chown -R meshcentral:meshcentral /opt/meshcentral\nThis will perform the update to the latest server on NPM and re-set the permissions so that the meshcentral user account has read-only access again. You can then use systemctl to make the server run again.
MeshCentral allows users to upload and download files stores in the server\u2019s meshcentral-files folder. In an increased security setup, we still want the server to be able to read and write files to this folder and we can allow this with:
sudo chmod -R 755 /opt/meshcentral/meshcentral-files\nIf you plan on using the increased security installation along with MeshCentral built-in Let\u2019s Encrypt support you will need to type the following commands to make the letsencrypt folder in meshcentral-data writable.
sudo mkdir /opt/meshcentral/meshcentral-data\nsudo mkdir /opt/meshcentral/meshcentral-data/letsencrypt\nsudo chmod -R 755 /opt/meshcentral/meshcentral-data/letsencrypt\nThis will allow the server to get and periodically update its Let\u2019s Encrypt certificate. If this is not done, the server will generate an ACCES: permission denied exception.
sudo systemctl stop meshcentral.servicesudo systemctl start meshcentral.serviceIn this section, we will look installing MeshCentral on Microsoft Azure. Microsoft Azure offers many operating system options and we will be selecting Ubuntu Server as our choice. From the Azure portal, we select Virtual machines on the left and Add.
Once you click on Ubuntu Server, you will see a list of available versions. In this example, we selected Ubuntu 18.04 LTS (Long Term Support). We then have to create an instance name and a way to authenticate to the instance.
Next is the type of instance to launch. Any instance will do including the B1s which is the smallest possible instance. Of course, as you manage more computers, using an instance that is a bit more powerful is a good idea.
After selecting the instance type, you can configure storage. 30 gigabytes is plenty. Then the Network Security Group. This is where it\u2019s important to open at least TCP ports 22, 80 and 443.
Optionally if you wish to use the instance with Intel AMT, open port 4433. In addition port 8080 must be open if you are migrating from MeshCentral1 (not typical).
Lastly we launch the instance, it will take a few minutes to setup.
You can then find the public IP address and use a SSH client like PUTTY on Windows to connect to the instance and start getting MeshCentral setup. From this point on, just use the Ubuntu section above to complete the installation.
"},{"location":"install/install2/#google-cloud","title":"Google Cloud","text":"In this section, we will look installing MeshCentral on Google Cloud. You can sign up easily at https://cloud.google.com/ and you can run a small instance for less than 5$ a month.
Once you have create an account, you can go to the main console and on the left side, go to Compute Engine and create a new VM instance. For our demonstration, we are going to create the smallest instance possible which is a single shared CPU and only 0.6 gigs of RAM.
We select the proper settings and select Ubuntu 18.04 LTS Minimal as the boot operating system. This is convenient as we already covered how to install MeshCentral on this operating system.
Make sure to allow HTTP and HTTPS traffic. Setup like this, we will not be able to manage Intel AMT unless we also open TCP port 4433. Once done with all these options, we can launch the VM instance.
The new instance will take a few minutes to start up. An interesting feature of Google Cloud is that you can access the VM instance shell directly from the web browser. No need for a separate SSH client. This is exactly what we need and we opt to go ahead and option the web console.
If will log you in automatically, no additional credentials needed. We can then follow the Ubuntu 18.04 LTS section above to complete the installation. If you opt for a very small instance, it\u2019s probably a good idea to skip installing MongoDB. Just to get started quickly, we can use the following commands:
sudo apt update\nsudo apt install nodejs -y\nsudo apt install npm -y\nsudo setcap cap_net_bind_service=+ep /usr/bin/node\nnpm install meshcentral\nnode ./node_modules/meshcentral --fastcert \u2013wanonly --cert 35.227.45.84\nWarning
Do not use sudo in front of npm install meshcentral.
This will install node and npm. Will allow non-root access to ports 80 and 443 and install and start MeshCentral. Because this example uses a very small server instance, we opted to use the fastcert option to create RSA 2048 certificates (the default is RSA 3072 which is more secure).
We use the wantonly option because MeshCentral will not be managing computers on a local network, and for this demonstration just used the external IP address of the instance as the server name.
If you plan on using an instance without the Intel AMT CIRA port being open (TCP 4433), it\u2019s recommended to add --mpsport 0 so to inform MeshCentral that this port is not open and to not offer Intel AMT CIRA features.
Of course, this set of commands is just to get the server started quickly. Follow the Ubuntu 18.04 instructions to setup the server to automatically start using system.
"},{"location":"install/install2/#ubuntu-1604","title":"Ubuntu 16.04","text":"In this section, we will look at installing MeshCentral on Ubuntu 16.04 LTS. This is the same installation at Ubuntu 18.04 LTS, however you need to install NodeJS in a special way. If you use apt install node, you will get an older version 4.x of NodeJS that will not work with MeshCentral.
The first thing to do is get NodeJS installed on the computer. We first install the node version manager then activate it and install the NodeJS LTS. It\u2019s done with 3 commands:
cd ~\nwget https://deb.nodesource.com/setup_8.x\nsudo bash setup_8.x\nsudo apt-get \u2013y install nodejs\nWe can test what version of Node and NPM are installed using:
node \u2013v\nnpm -v\nYou should see Node version 8 and NPM version 5. At this point, you can continue installing MeshCentral using the Ubuntu 18.04 installation instructions.
"},{"location":"install/install2/#openbsd-64","title":"OpenBSD 6.4","text":"In this section, we will look at installing MeshCentral on OpenBSD 6.4. This section was originally written by Daulton and placed here with this permission. The original instructions are located at: https://daulton.ca/meshcentral-server-on-openbsd/. The section will setup MeshCentral on non-standard ports HTTPS/3000 and HTTP/3001. Thank you to Daulton for his contribution.
"},{"location":"install/install2/#installing-mongodb_2","title":"Installing MongoDB","text":"Install the Mongodb package.
pkg_add mongodb\nStart and enable Mongodb at boot.
rcctl start mongod\nrcctl enable mongod\nTemporary remount /usr with wxallowed while we compile the port. For Cloud VPS they usually only have a root partition instead of how OpenBSD splits it up by default, you will need to edit /etc/fstab and add wxallowed to the options for the root partition and then reboot. Assure to remove this from the fstab options after you are done.
mount -r -o wxallowed /usr/\nInstall NodeJS from ports as it is not available by a package.
$ cd /tmp\n$ ftp https://cdn.openbsd.org/pub/OpenBSD/$(uname -r)/{ports.tar.gz,SHA256.sig}\n# cd /usr\n# tar xzf /tmp/ports.tar.gz\n# cd /usr/ports/lang/node\n# make install\n# make clean\nCreate the MeshCentral user. The parameters used here are important as we will not let this user login, it has no home directory, and its class is set to daemon. In line with the OpenBSD daemon user naming scheme, we preface the username with an underscore _ to make it easily identifiable as a daemon user.
useradd -s /sbin/nologin -d /nonexistent -L daemon -u 446 _meshcentral\nLet\u2019s install MeshCentral and adjust the permissions.
mkdir -p /usr/local/meshcentral\ncd /usr/local/meshcentral\nnpm install meshcentral\nchown -R _meshcentral:_meshcentral /usr/local/meshcentral\nConfiguring for MongoDB and adjusting some other settings such as the network port. Open up the following config in an editor then, make the start of the file look like below. If the setting does not exist yet, just add it below one of the ones we are adjusting in the main settings block.
If you start with the default config.json created by MeshCentral, you will need to remove some underscore character in front of settings to enable the setting, such as mongodb and wanonly. You can also add an underscore to other values. For details on all of the config.json options, including the WANonly option, refer to the MeshCentral User\u2019s Guide.
Before you can edit the configuration, start the Meshcentral briefly so it generates the default configurations and certificates. Once you see that it says \"MeshCentral HTTPS server running...\", Ctrl-C to exit then edit the configuration file next.
cd /usr/local/meshcentral/node_modules/meshcentral/ && doas -u _meshcentral /usr/local/bin/node /usr/local/meshcentral/node_modules/meshcentral/meshcentral.js --launch\nEdit the MeshCentral config.json. For example using vi:
vi /usr/local/meshcentral/meshcentral-data/config.json\nIn the settings section, set the following key value pairs:
{\n\"settings\": {\n\"Cert\": \"meshcentral.example.com\",\n\"MongoDb\": \"mongodb://127.0.0.1:27017/meshcentral\",\n\"WANonly\": true,\n\"Port\": 3000,\n\"ExactPorts\": true,\n\"RedirPort\": 3001,\n\"allowLoginToken\": true,\n\"allowFraming\": true,\n\"NewAccounts\": 0,\n},\n\u2026\n}\nAdd the following to the root crontab to start MeshCentral at boot. Edit the root crontab by doing the following command as root: crontab -e
@reboot cd /usr/local/meshcentral/node_modules/meshcentral/ && doas -u _meshcentral /usr/local/bin/node /usr/local/meshcentral/node_modules/meshcentral/meshcentral.js --launch\nAs root launch Meshcentral while it installs mongojs, once that finishes and Meshcentral launches close it by doing Ctrl-C. Adjust the permissions again as we ran Meshcentral and it generated new files we need to change the ownership of.
/usr/local/bin/node /usr/local/meshcentral/node_modules/meshcentral
chown -R _meshcentral:_meshcentral /usr/local/meshcentral\nWarning
Do not keep this running or use this command in the future to start the Meshcentral server as it starts the server as root!
This is a reference /etc/pf.conf for you to keep your server secure. Add any locally connected networks which should have access and any public IP address of a network which will have client PCs connect from to target_whitelist table. Add your own home and/or business IP to my_own_IPs table.
ext_if = vio0\nset reassemble yes\nset block-policy return\nset loginterface egress\nset ruleset-optimization basic\nset skip on lo\n\nicmp_types = \"{ 0, 8, 3, 4, 11, 30 }\"\n\ntable <target_whitelist> const { 45.63.15.84, 10.18.5.0/24 }\ntable <my_own_IPs> const { 45.63.15.84 }\ntable <bruteforce>\n\nmatch in all scrub (no-df max-mss 1440)\nmatch out all scrub (no-df max-mss 1440)\n\nblock in quick log from urpf-failed label uRPF\nblock quick log from <fail2ban>\n\nblock in from no-route to any\nblock in from urpf-failed to any\nblock in quick on $ext_if from any to 255.255.255.255\nblock in log quick on $ext_if from { 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 255.255.255.255/32 } to any antispoof for $ext_if\nblock log all\n\npass in quick inet proto icmp icmp-type $icmp_types\npass in quick inet6 proto icmp6\n\npass in quick proto tcp from <my_own_IPs> \\\nto (egress) port { 22 } \\\nflags S/SA modulate state \\\n(max-src-conn 5, max-src-conn-rate 5/5, overload <bruteforce> flush global)\n\npass in quick inet proto tcp from <target_whitelist> to port 3000\npass in quick inet6 proto tcp from <target_whitelist> to port 3000\n\nblock in quick log on egress all\n\npass out quick on egress proto tcp from any to any modulate state\npass out quick on egress proto udp from any to any keep state\npass out quick on egress proto icmp from any to any keep state\npass out quick on egress proto icmp6 from any to any keep state\nAfter saving the configuration in /etc/pf.conf, reload the pf rules with:
pfctl -f /etc/pf.conf\nTo save rebooting and have MeshCentral launch then, launch it so you can begin using it. This time it is running as _meshcentral, now it is safe to keep running and you can use this command in the future.
cd /usr/local/meshcentral/node_modules/meshcentral/ && doas -u _meshcentral /usr/local/bin/node /usr/local/meshcentral/node_modules/meshcentral/meshcentral.js --launch\nYou can now access MeshCentral at https://youraddress:3000 or https://meshcentral.example.com:3000 if you named the machine meshcentral or create an A record named meshcentral. The first user you create will be the Administrator, there is no default user.
"},{"location":"intelamt/","title":"Intel AMT","text":"Intel AMT Guide as .odt
"},{"location":"intelamt/#video-walkthru","title":"Video Walkthru","text":""},{"location":"intelamt/#abstract","title":"Abstract","text":"This user guide contains all essential information for activating and using Intel\u00ae Active Management Technology (Intel\u00ae 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\u00ae AMT works.
"},{"location":"intelamt/#history-of-amt","title":"History of AMT","text":""},{"location":"intelamt/#introduction","title":"Introduction","text":"MeshCentral is a free open source web-based remote computer management software and it fully supports Intel\u00ae Active Management Technology (Intel\u00ae 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\u2019s. 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\u2019s 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 \u201cin-band management\u201d and when management is done using a hardware based agent like Intel AMT, we call this \u201cout-of-band management\u201d
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 \u201cagent-less\u201d as there will be no operating system software required to remotely manage the computer.
The Mesh Agent and Intel\u00ae AMT have very different and complementary capabilities and so, it\u2019s often beneficial to use both and one will offer features the other can\u2019t provide. Here are some of the benefits each has to offer:
Mesh Agent
Intel\u00ae AMT
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.
"},{"location":"intelamt/#bare-metal-activation-server","title":"Bare-Metal Activation Server","text":"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 \u201chello\u201d 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.
"},{"location":"intelamt/#meshcentral-group-types","title":"MeshCentral Group Types","text":"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\u2019t have the Mesh Agent installed.
The main benefit of \u201cIntel AMT only\u201d 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 \u201cMy Devices\u201d page, next to the group name.
If the MeshCentral server is setup in \u201cLAN mode\u201d or \u201cHybrid mode\u201d, 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 \u201cAdd Local\u201d or \u201cScan Network\u201d options in the \u201cIntel AMT only\u201d group type and start adding local network computers this way. If MeshCentral is in \u201cWAN mode\u201d, you will need to setup Intel AMT to connect back to MeshCentral using a feature called \u201cClient Initiated Remote Access\u201d or CIRA for short. We will cover that in a later section.
"},{"location":"intelamt/#client-initiated-remote-access-mps-server","title":"Client Initiated Remote Access & MPS server","text":"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\u2019s 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 \u201cManagement Presence Server\u201d 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.\nIntel\u00ae AMT computers should connect here.\nThis 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.
"},{"location":"intelamt/#activation-certificate-setup","title":"Activation Certificate Setup","text":"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\u2019s) 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 \u201cmeshcentral-data\u201d folder and add the \u201cAmtAcmActivation\u201d section in the domain section like so:
{\n \"settings\": {\n \"Cert\": \"devbox.mesh.meshcentral.com\",\n },\n \"domains\": {\n \"\": {\n \"title\": \"My Server\",\n \"AmtAcmActivation\": {\n \"log\": \"amtactivation.log\",\n \"certs\": {\n \"myamtcert\": {\n \"certpfx\": \"amtcert.pfx\",\n \"certpfxpass\": \"pfxpassword\"\n }\n }\n }\n }\n}\nIf 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 \u201cmeshcentral-data\u201d folder and setup the certificate chain like this:
{\n \"settings\": {\n \"Cert\": \"devbox.mesh.meshcentral.com\",\n },\n \"domains\": {\n \"\": {\n \"title\": \"My Server\",\n \"AmtAcmActivation\": {\n \"log\": \"amtactivation.log\",\n \"certs\": {\n \"myvprocert\": {\n \"certfiles\": [ \"amtacm-vprodemo.crt\",\n \"amtacm-intermediate1.crt\",\n \"amtacm-intermediate2.crt\",\n \"amtacm-root.crt\" ],\n \"keyfile\": \"amtacm-vprodemo.key\"\n }\n }\n }\n }\n}\nIt\u2019s important that the leaf certificate file be the first file in the \u201ccertfiles\u201d array. The order of the other certificates is not important as MeshCentral will figure out and re-order them correctly.
Within the new \u201cAmtAcmActivation\u201d section, there is a \u201clog\u201d 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\u2019s also important to have this file as a backup so that Intel AMT credentials are not lost after activation. If MeshCentral can\u2019t 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 \u201cIntel AMT only\u201d groups, a new \u201cActivation\u201d 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 \u201cSimple Admin Control Mode\u201d 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 \u201cmeshcentral.com\u201d. Intel AMT must be in a situation where this domain can be accepted. One of the following must be true:
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 \u201cIntel AMT only\u201d 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.
"},{"location":"intelamt/#intel-amt-mei-and-lms","title":"Intel AMT MEI and LMS","text":"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
"},{"location":"intelamt/#intel-amt-system-defense","title":"Intel AMT System Defense","text":"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.
"},{"location":"meshcentral/","title":"Meshcentral2 Guide","text":"MeshCentral2 Guide
MeshCmd Guide as .pdf as .odt
"},{"location":"meshcentral/#video-walkthru","title":"Video Walkthru","text":""},{"location":"meshcentral/#abstract","title":"Abstract","text":"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.
"},{"location":"meshcentral/#introduction","title":"Introduction","text":"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.
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\u2019s Guide available at https://www.meshcommander.com/meshcentral2 for information on how to install the server.
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\u2019s 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.
"},{"location":"meshcentral/#basic-usage","title":"Basic Usage","text":"In this section we will cover the basics of MeshCentral in your newly setup server.
"},{"location":"meshcentral/#launch","title":"Launch","text":"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 \u201ctrusted\u201d or \u201ctrustworthy\u201d certificate. To prevent this warning from recurring, the following chapter will provide useful steps that can be considered.
To proceed on Firefox browser,
To proceed on Chrome Browser,
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\u2019s 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 an account by clicking \u201cCreate One\u201d and click \u201cCreate Account\u201d once the text fields had been populated correctly.
"},{"location":"meshcentral/#new-device-group","title":"New device group","text":"Once logged in, create a new device group. This is a group of computers that we want to manage. To proceed,
Note
There are two types of groups: Software Agent Group: Commonly used to manage computers. Administrator must install a \u201cremote management agent\u201d on the remote computers. Intel\u00ae AMT Agent-less Group: Exclusive for remote computers that has Intel\u00ae AMT activated and needs to be managed independent of a \u201cremote management agent\u201d.
"},{"location":"meshcentral/#add-device","title":"Add device","text":"To add devices into new mesh
Note
Mesh Agent is available for Windows* and Linux*. For Windows*, the mesh agent doesn\u2019t 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.
"},{"location":"meshcentral/#after-agent-install","title":"After agent install","text":"Once the agents are installed, it will take up to a minute before the computer shows up on the user\u2019s account automatically. Click on each computer to access it and user can rename the each computer with a unique name and icons.
"},{"location":"meshcentral/#manage-computer","title":"Manage Computer","text":"Click on any computer and go into the \u201cDesktop\u201d and \u201cFiles\u201d tabs to remotely manage the computer or perform file transfer.
For advance users with console/command line interface experience, go into \u201cTerminal\u201d to perform scripting or quick tasks with CLI tools.
"},{"location":"meshcentral/#desktop-control","title":"Desktop Control","text":"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.
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:
Important
Before adding/importing the certificate, user must check the validity of the certificate presented by the website and compare with \u201croot-cert-public.crt\u201d file in the \u201cmeshcentral-data\u201d 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.
Note: If you are using TLS offloading, see the section on \u201cTLS Offloading\u201d cover in the latter parts of this document.
"},{"location":"meshcentral/#files-and-folder-structure","title":"Files and Folder Structure","text":"It\u2019s important to know the basic file and folder structure from which MeshCentral was installed as shown below
Right after running the \u201cnpm install meshcentral\u201d 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\u2019s data.
The \u201cmeshcentral-data\u201d folder will contain:
meshcentral.db file: The server\u2019s 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\u2019s 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\u2019s 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 \u201cmeshcentral-files\u201d 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 \u201cmeshcentral-data\u201d 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.
"},{"location":"meshcentral/#server-configuration-file","title":"Server Configuration File","text":"In the \u201cmeshcentral-data\u201d folder, there is a file called config.json that contains the main configuration of the server. A sample configuration file could look like this:
{\n \"settings\": {\n \"cert\": \"mesh.myserver.com\",\n \"port\": 8080,\n \"redirport\": 81\n },\n \"domains\": {\n \"\": {\n \"title\": \"MyServer\",\n \"title2\": \"Servername\",\n \"userQuota\": 1048576,\n \"meshQuota\": 248576,\n \"newAccounts\" : 1\n },\n \"Customer1\": {\n \"title\": \"Customer1\",\n \"title2\": \"Extra String\",\n \"newAccounts\" : 0\n }\n },\n \"peers\": {\n \"serverId\" : \"Server1\",\n \"servers\": {\n \"Server1\": { \"url\": \"wss://192.168.1.100:443/\" },\n \"Server2\": { \"url\": \"wss://192.168.1.101:443/\" }\n }\n }\n }\nFirst, we will look at each of the top levels of the configuration file. The tops levels are \u201csettings\u201d, \u201cdomains\u201d, \u201cpeers\u201d, and \u201csmtp\u201d as shown in the table below.
"},{"location":"meshcentral/#settings","title":"Settings","text":"As indicated before, the settings section of the config.json is equivalent to passing arguments to the server at runtime. Below is a list of settings that are available for the user.
Settings Option 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.
"},{"location":"meshcentral/#domains","title":"Domains","text":"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 \u201cMeshCentral\u201d and title2 is set to a version number UserQuota This is the maximum amount of data in kilobytes that can be placed in the \u201cMy Files\u201d tab for a user account. MeshQuota This is the maximum amount of data in kilobytes that can be placed in the \u201cMy Files\u201d 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 \u201csspi\u201d, domain control authentication to the website is performed. In this mode, no login screen is displayed and browser will authenticate using the user\u2019s domain credentials. Dns The DNS record for this domain. If specified, the domain is accessed using a DNS record like \u201ccustomer1.servername.com\u201d instead of \u201cservername/customer1\u201d. 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 \u201chttps://127.0.0.1:123\u201d. This option is useful when used along with the \u201cTlsOffload\u201d 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\u00ae AMT are defined by Intel and so, Intel\u00ae AMT passwords will always be verified using a separate set of requirements. Note: When the DNS value is set for a domain, user can\u2019t access the domain using \u201cservername/customer1\u201d 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 \u201cdns\u201d value, the second domain is only shown when the right name is used. We use \u201cmeshcentral\u201d and \u201cdevbox\u201d for DNS names, but in practice the user will use fully qualified domain names (FQDN) like \u201cmeshcentral.com\u201d or \u201cdevbox.meshcentral.com\u201d.
"},{"location":"meshcentral/#server-peering","title":"Server Peering","text":"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\u00a0applications 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 \u201cmeshcentral-data\u201d directory on each server and configure the \u201cpeers\u201d section of the config.json file as shown below.
{\n \"peers\": {\n \"serverId\" : \"Server1\",\n \"servers\": {\n \"Server1\": { \"url\": \"wss://192.168.1.100:443/\" },\n \"Server2\": { \"url\": \"wss://192.168.1.101:443/\" }\n }\n }\n }\nThe configuration above assumes that server1 has an IP address of \u2018192.168.1.100\u2019 and server2 has \u2018192.168.1.101\u2019 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 \u201cservers\u201d 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 \u201c--tlsoffload\u201d, then use \u201cws://\u201d for the URL instead of \u201cwss://\u201d.
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.
"},{"location":"meshcentral/#email-setup","title":"Email Setup","text":"We highly recommend the use of an email server (SMTP) because we could allow MeshCentral to verify user account\u2019s 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 \u201cMy Account\u201d tab.
The password recovery flow when \u201cReset Account\u201d 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.
"},{"location":"meshcentral/#smtp-userpass","title":"SMTP: User/Pass","text":""},{"location":"meshcentral/#normal-server","title":"Normal Server","text":"Update the config.json with \u201csmtp\u201d section as shown below and restart the server.
{\n \"smtp\": {\n \"host\": \"smtp.server.com\",\n \"port\": 25,\n \"from\": \"myaddress@server.com\",\n \"user\": \"myaddress@server.com\", # Optional\n \"pass\": \"mypassword\", # Optional\n \"tls\": false # Optional, default false\n }\n}\nPlease map the host, port values to connect to the right host that provides this SMTP service. For \u201cfrom\u201d 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 \u2018true\u2019 if the SMTP server requires TLS.
"},{"location":"meshcentral/#gmail","title":"Gmail","text":"One option is to configure MeshCentral work with Google Gmail by setting \u201chost\u201d with smtp.gmail.com, and \u201cport\u201d with 587. In the config.json file, use user\u2019s Gmail address for both \u201cfrom\u201d and \u201cuser\u201d and Gmail password in the \u201cpass\u201d value. You will also need to enable \u201cLess secure app access\u201d in for this Google account. It\u2019s 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\u2019t be used, it\u2019s preferable to use a dedicated Google account for MeshCentral email.
"},{"location":"meshcentral/#smtp-oauth-authentication","title":"SMTP: OAuth Authentication","text":""},{"location":"meshcentral/#gmail_1","title":"Gmail","text":"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:
https://console.developers.google.com/
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 \u2018User support email\u2019 and \u2018Developer contact information\u2019 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\": {\n \"host\": \"smtp.gmail.com\",\n \"port\": 587,\n \"from\": \"my@googleaccount.com\",\n \"auth\": {\n \"clientId\": \"<YOUR-CLIENT-ID>\",\n \"clientSecret\": \"<YOUR-CLIENT-SECRET>\",\n \"refreshToken\": \"<YOUR-REFRESH-TOKEN>\"\n },\n \"user\": \"noreply@authorizedgooglealias.com\",\n \"emailDelaySeconds\": 10,\n \"tls\": false,\n \"verifyEmail\": true\n }\nRegardless 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.
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 (https://github.com/louischatriot/nedb) that is written entirely in NodeJS and is setup automatically when MeshCentral is installed with the npm tool. The file \u201cmeshcentral.db\u201d will be created in the \u201cmeshcentral-data\u201d 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.
"},{"location":"meshcentral/#database-export","title":"Database Export","text":"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 \u201c--dbexport\u201d and a JSON file called \u201cmeshcentral.db.json\u201d will be created in the \u201cmeshcentral-data\u201d folder as shown below.
Alternatively, user can also specify the full export path for the JSON file as shown below.
"},{"location":"meshcentral/#database-import","title":"Database Import","text":"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 \u201c--dbimport\" as shown below. If path is not specified, the application will default to use \u201cmeshcentral.db.json\u201d that is in \u201cmeshcentral-data\u201d folder.
Alternatively, user can specify the full path of the import JSON as shown below.
"},{"location":"meshcentral/#viewing-the-database","title":"Viewing the Database","text":"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 \u201c--showusers\"
"},{"location":"meshcentral/#mongodb-setup","title":"MongoDB Setup","text":"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,
Go to the MongoDB bin folder and run \u201cmongod --bind 127.0.0.1\u201d.
This execute the database engine and store the database data in the default location \u201c/data/db\u201d path and bind a loopback on the local port \u201c127.0.0.1\u201d.
Note: Refer to MongoDB documentation to allow database to run in the background or experiment with alternate configurations.
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 \u201cmeshcentral\u201d DB. MongoDB will create this DB if it does not exist.
node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral\nAlternatively, to transition an existing meshcentral DB from NeDB and to MongoDB, just run the command below:
node meshcentral --dbexport \nnode meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral --dbimport\nnode meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral\nWe recommend the user to include MongoDB configuration into the server\u2019s configuration \u201cconfig.json\u201d to avoid specifying the \u201c--mongodb\" each time MeshCentral is executed as shown below
{\n \"settings\": {\n \"mongodb\": \"mongodb://127.0.0.1:27017/meshcentral\",\n \"mongodbcol\": \"meshcentral\"\n }\n}\nNote: By default, MeshCentral will create a single collections called \u201cmeshcentral\u201d in the specified database. If user want to specify a different collection name, use \u201c--mongodbcol\" or \u201cmongodbcol\u201d 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\nYou can also provide extra connection parameters like this:
mongodb://username:password@127.0.0.1:27017/meshcentral?authMechanism=MONGODB-CR&authSource=db\nBy default, MeshCentral will read its configuration information from the \u201cmeshcentral-data\u201d folder. The most important file in that folder being the \u201cconfig.json\u201d 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\u2019s this is a perfectly acceptable way to setup the server. However, in some cases, it\u2019s advantageous to setup the server \u201cstate-less\u201d. 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\u2019t want the container to have any state or for compliance with security specifications where the database is \u201cencrypted at rest\u201d. 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 \u201cmeshcentral-data\u201d 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 \u201cmeshcentral-data\u201d 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\n\nnode ./node_modules/meshcentral --loadconfigfromdb mypassword --mongodb \"mongodb://127.0.0.1:27017/meshcentral\"\nThis first line will load many of the \u201cmeshcentral-data\u201d files into the database. At this point, we can back up the \u201cmeshcentral-data\u201d folder and remove it. Then run the second line to start the server. Here we use MongoDB, but if one uses NeDB, the \u201cmeshcentral.db\u201d file in the \u201cmeshcentral-data\u201d folder will still be needed.
Note that MeshCentral does not currently support placing a Let\u2019s Encrypt certificate in the database. Generally, one would use a reverse proxy with Let\u2019s Encrypt support and TLS offload in the reverse proxy and then run MeshCentral in state-less mode in a Docket container.
"},{"location":"meshcentral/#commandline-options","title":"Commandline Options","text":"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\n --install/uninstall Install MeshCentral as a background service.\n --start/stop/restart Control MeshCentral background service.\n\nRun standalone, console application\n --user [username] Always login as [username] if account exists.\n --port [number] Web server port number.\n --redirport [number] Creates an additional HTTP server to redirect users to the HTTPS server.\n --exactports Server must run with correct ports or exit.\n --noagentupdate Server will not update mesh agent native binaries.\n --nedbtodb Transfer all NeDB records into current database.\n --listuserids Show a list of a user identifiers in the database.\n --cert [name], (country), (org) Create a web server certificate with [name] server name.\n country and organization can optionally be set.\n\nServer recovery commands, use only when MeshCentral is offline.\n --createaccount [userid] Create a new user account.\n --resetaccount [userid] Unlock an account, disable 2FA and set a new account password.\n --adminaccount [userid] Promote account to site administrator.\nA 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 \u201c--tlsoffload\u201d. 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\u00ae 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\u2019s 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 4433If possible, port 443 should be configured with a legitimate trusted certificate and the public part of the certificate named as \u201cwebserver-cert-public.crt\u201d must be placed inside of \u201cmeshcentral-data\u201d 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\u00ae AMT MPS port 4433, the certificate files \u201cmpsserver-cert-public.crt\u201d and \u201cmpsserver-cert-public.key\u201d must be copied from the \u201cmeshcentral-data\u201d 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.
"},{"location":"meshcentral/#lets-encrypt-support","title":"Let\u2019s Encrypt support","text":"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\u2019s Encrypt (https://letsencrypt.org/). There are some limitations and so, it\u2019s 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\u2019s HTTP port 80 server will be used in the process to prove to Let\u2019s Encrypt that we have control over the domain. At any point, you may try to use https://letsdebug.net/ to see if your domain is setup correctly and/or debug any issues. When ready, add the \u201cletsencrypt\u201d section to the config.json file like this:
{\n \"settings\": {\n \"RedirPort\": 80,\n },\n \"letsencrypt\": {\n \"email\": \"myemail@myserver.com\",\n \"names\": \"domain1.com,domain2.com\",\n \"rsaKeySize\": 3072,\n \"production\": false\n },\n}\nThe 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\u2019s important to understand you are not requesting these DNS names, rather, Let\u2019s 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\u2019t specify names, the default MeshCentral certificate name is used, that is the configured \u201c--cert [name]\u201d.
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\u2019s Encrypt staging server for a certificate. It\u2019s 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\u2019s Encrypt certificate authority.
The Let\u2019s Encrypt certificates and files will be created in the \u201cmeshcentral-data\u201d folder. Make sure to keep regular backups of the \u201cmeshcentral-data\u201d folder and all sub-folders.
Once you placed the \u201cletsencrypt\u201d section in config.json, restart the server. The request to the Let\u2019s Encrypt server may take a few minutes to a few hours. It\u2019s 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\u2019s Encrypt certificate using the Let\u2019s Encrypt staging server (\u201cproduction\u201d: false) and everything looks good, stop the server, remove the \u201cletsencrypt\u201d folder in \u201cmeshcentral-data\u201d, change production to \u201ctrue\u201d 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 \u201cmeshcentral-data\u201d folder, this is normal and there is no need to manually copy the Let\u2019s Encrypt certificate to the \u201cmeshcentral-data\u201d folder. If something goes wrong with the Let\u2019s Encrypt certificate, the server will fall back to using the self-signed one.
Note
Please be patient with Let\u2019s Encrypt certificate requests and make sure you correctly get a staging certificate before setting production to true.
If Let\u2019s Encrypt works for you, please consider donating to them as they provide a critical service to the Internet community.
"},{"location":"meshcentral/#server-ip-filtering","title":"Server IP filtering","text":"For improved security, it\u2019s 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.
{\n \"domains\": {\n \"\": {\n \"userallowedip\" : \"1.2.3.4,1.2.3.5\",\n }\n }\n }\nIP addresses are separated by a comma. As a result, only users coming these IP addresses will be able to see the server\u2019s 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\",\n\"userBlockedIp\": \"file:userblockedips.txt\",\n\"agentAllowedIp\": \"file:agentallowedips.txt\"\nPlace 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\n185.101.70.0/24\n185.46.85.0/24\n37.9.44.0/24\n37.9.45.0/24\n5.189.205.0/24\n5.189.206.0/24\n5.189.207.0/24\n5.62.153.0/24\n5.62.156.0/24\n5.62.158.0/24\n\n# One more list\n5.8.44.0/24\n5.8.45.0/24\n5.8.46.0/24\n79.110.28.0/24\n79.110.31.0/24\n91.204.14.0/24\n95.181.218.0/24\n95.85.81.0/24\nOne 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: 1. 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. 2. 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. 3. 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.
"},{"location":"meshcentral/#login-token","title":"Login Token","text":"With MeshCentral, it\u2019s possible to login to the main web page without even seeing the login screen. Of course, you can do this by specifying \u201c--nousers\" or \u201c--user admin\u201d 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.
{\n \"settings\": {\n \"allowLoginToken\": true,\n \"allowFraming\": true\n }\n}\nSet both allowLoginToken and allowFraming to \u2018true\u2019 to use login tokens along with framing MeshCentral within another web page.
Next, create a token. Execute MeshCentral with the \u201c--logintoken [userid]\u201d switch and userid value with the example below:
The \u201cuserid\u201d is actually a combination of three values - user, domain, and username in a single string \u201cuser/domain/username\u201d. The example above is using a default domain which is empty hence, the userid will be just \u201cuser//admin\u201d 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 \u201c?login=\u201d 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 \u201c--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\u2019s 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.
"},{"location":"meshcentral/#embedding-options","title":"Embedding Options","text":"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 \"ValuesNote: For values 10 and above, a node identifier must be specified.\" viewmode \"Indicates the information to show. This is an integer value, possible values are:\" \"1 = Devices tab2 = Account tab3 = Events tab4 = Users tab (Site admins only)5 = Server files tab10 = Device general information11 = Device remote desktop12 = Device terminal14 = Device Intel AMT console.15 = Device Mesh Agent console hide \"Indicates which portion of the web page to hide. This is a bitmask integer hence it will need the sum of values. For .e.g.: To hide all of the values, add 1+2+4+8 and use 15 as the value. 1 = Hide the page header2 = Hide the page tab4 = Hide the page footer8 = Hide the page title16 = Hide the left tool bar32 = Hide back buttons node Optional unless Viewmode is set to value of 10 or greater. 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 valueNote: Typically, the URL for the website is followed by \u201c?\u201d then a set of name=value pairs separated by \u201c&\u201d.
Based on the URL https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15 , the nodeID starts with \u201cUkSNlz7t\u201d. We shortened the value in this example, but it\u2019s 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 \u201callowFraming\u201d 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.
"},{"location":"meshcentral/#server-port-aliasing","title":"Server port aliasing","text":"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\u2019s 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\nHere, 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\nWe 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\n--port 443 --mpsport 4433 --mpsaliasport 443\nIn 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 \u201cServer2\u201d on it. The server will also configure Intel AMT CIRA to connect to \u201cServer2:443\u201d.
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\nServer2:443 -> 4433 on MeshCentral\nThe 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.
"},{"location":"meshcentral/#web-relay-using-dns-names-and-multiple-web-relays","title":"Web relay using DNS names and multiple web relays","text":"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.
"},{"location":"meshcentral/#video-walkthrus","title":"Video Walkthrus","text":""},{"location":"meshcentral/#device-groups-with-relay-agent","title":"Device Groups with Relay Agent","text":"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\nVideo Walkthru
"},{"location":"meshcentral/#raritan-and-webpowerswitch-with-relay","title":"Raritan and WebPowerSwitch with Relay","text":"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.
"},{"location":"meshcentral/#nginx-reverse-proxy-setup","title":"NGINX Reverse-Proxy Setup","text":""},{"location":"meshcentral/#video-walkthru_1","title":"Video Walkthru","text":"Sometimes it\u2019s 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: https://www.nginx.com/
In this example, we will:
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\u2019s get started by configuring MeshCentral with the following values in config.json:
{\n \"settings\": {\n \"Cert\": \"myservername.domain.com\",\n \"Port\": 4430,\n \"AliasPort\": 443,\n \"RedirPort\": 800,\n \"AgentPong\": 300,\n \"TlsOffload\": \"127.0.0.1\"\n },\n \"domains\": {\n \"\": {\n \"certUrl\": \"https://127.0.0.1:443/\"\n }\n }\n}\nWith this configuration, MeshCentral will be using port 4430 instead of port 443, but because \u201cTlsOffload\u201d is set, TLS will not be performed on port 4430. The server name is set to \u201cmyservername.domain.com\u201d, 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 \u201cmyservername.domain.com:443\u201d.
The \u201cAgentPong\u201d 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, \u201ccertUrl\u201d 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 \u201cTlsOffload\u201d to \u201c127.0.0.1\u201d, MeshCentral is told to trust these headers when requests come from \u201c127.0.0.1\u201d.
In this example, make sure to change \u201c127.0.0.1\u201d to the IP address of NGINX and \u201cCert\u201d 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;\n\nevents {\n worker_connections 1024;\n}\n\nhttp {\n # HTTP server. In this example, we use a wildcard as server name.\n server {\n listen 80;\n server_name _;\n\n location / {\n proxy_pass http://127.0.0.1:800/;\n proxy_http_version 1.1;\n\n # Inform MeshCentral about the real host, port and protocol\n proxy_set_header X-Forwarded-Host $host:$server_port;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n }\n\n # HTTPS server. In this example, we use a wildcard as server name.\n server {\n listen 443 ssl;\n server_name _;\n\n # MeshCentral uses long standing web socket connections, set longer timeouts.\n proxy_send_timeout 330s;\n proxy_read_timeout 330s;\n\n # We can use the MeshCentral generated certificate & key\n ssl_certificate webserver-cert-public.crt;\n ssl_certificate_key webserver-cert-private.key;\n ssl_session_cache shared:WEBSSL:10m;\n ssl_ciphers HIGH:!aNULL:!MD5;\n ssl_prefer_server_ciphers on;\n\n location / {\n proxy_pass http://127.0.0.1:4430/;\n proxy_http_version 1.1;\n\n # Allows websockets over HTTPS.\n proxy_set_header Upgrade $http_upgrade;\n proxy_set_header Connection \"upgrade\";\n proxy_set_header Host $host;\n\n # Inform MeshCentral about the real host, port and protocol\n proxy_set_header X-Forwarded-Host $host:$server_port;\n proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n proxy_set_header X-Forwarded-Proto $scheme;\n }\n }\n}\nAs 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 \u201cX-Forward\u201d headers, this tells MeshCentral information that would normally be hidden by NGINX, like the client\u2019s 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.\nLoaded RSA web certificate at https://127.0.0.1:443/, SHA384: d9de9e27a229b5355708a3672fb23237cc994a680b3570d242a91e36b4ae5bc96539e59746e2b71eef3dbdabbf2ae138.\nMeshCentral Intel(R) AMT server running on myservername.domain.com:4433.\nMeshCentral HTTP web server running on port 4430, alias port 443.\nNotice 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.
"},{"location":"meshcentral/#cira-setup-with-nginx","title":"CIRA Setup with NGINX","text":"We can add on the section above and support reverse proxy for Intel\u00ae 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 {\n # Internal MPS servers, in this case we use one MeshCentral MPS server is on our own computer.\n upstream mpsservers {\n server 127.0.0.1:44330 max_fails=3 fail_timeout=30s;\n }\n\n # We can use the MeshCentral generated MPS certificate & key\n ssl_certificate mpsserver-cert-public.crt;\n ssl_certificate_key mpsserver-cert-private.key;\n ssl_session_cache shared:MPSSSL:10m;\n ssl_ciphers HIGH:!aNULL:!MD5;\n ssl_prefer_server_ciphers on;\n\n # MPS server.\n server {\n listen 4433 ssl;\n proxy_pass mpsservers;\n proxy_next_upstream on;\n }\n}\n\nNGINX will listen on port 4433, decrypt the connection and forward it to 44330 on the loopback interface. We are going to be used the \u201cmpsserver\u201d 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.\n\n{\n \"settings\": {\n \"Cert\": \"myservername.domain.com\"\n \"Port\": 4430,\n \"AliasPort\": 443,\n \"RedirPort\": 800,\n \"TlsOffload\": \"127.0.0.1\"\n \"MpsPort\": 44330,\n \"MpsAliasPort\": 4433,\n \"MpsTlsOffload\": true\n },\n \"domains\": {\n \"\": {\n \"certUrl\": \"https://127.0.0.1:443/\"\n }\n }\n}\nIn 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 \u201cMpsTlsOffload\u201d to true.
With this configuration, Intel AMT CIRA connections will come in and TLS will be handled by NGINX. With this setup, it\u2019s not possible to configure Intel AMT CIRA to connect using mutual-TLS authentication, only username/password authentication is used.
"},{"location":"meshcentral/#traefik-reverse-proxy-setup","title":"Traefik Reverse-Proxy Setup","text":"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:
First we will start with the MeshCentral configuration, here is a minimal configuration that will work:
{\n \"settings\": {\n \"Cert\": \"myservername.domain.com\",\n \"Port\": 4430,\n \"AliasPort\": 443,\n \"RedirPort\": 800,\n \"TlsOffload\": \"127.0.0.1\"\n },\n \"domains\": {\n \"\": {\n \"certUrl\": \"https://127.0.0.1:443/\"\n }\n }\n}\nNote the \u201cagentConfig\u201d line: Because Traefik does not support web socket connections that are not \u201cmasked\u201d, 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 \u201cAliasPort\u201d line.
The \u201cTlsOffload\u201d line indicates that MeshCentral should not perform TLS on port 4430. And the \u201ccertUrl\u201d 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\u2019s 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]\n checkNewVersion = false\n sendAnonymousUsage = false\n\n[entryPoints]\n [entryPoints.http]\n address = \":80\"\n [entryPoints.http.redirect]\n entryPoint = \"https\"\n [entryPoints.https]\n address = \":443\"\n [entryPoints.https.tls]\n [[entryPoints.https.tls.certificates]]\n certFile = \"webserver-cert-public.crt\"\n keyFile = \"webserver-cert-private.key\"\n\n[file]\n\n[backends]\n [backends.backend1]\n [backends.backend1.healthcheck]\n path = \"/health.ashx\"\n interval = \"30s\"\n\n [backends.backend1.servers.server1]\n url = \"http://127.0.0.1:4430\"\n weight = 1\n\n[frontends]\n [frontends.frontend1]\n entryPoints = [\"https\"]\n backend = \"backend1\"\n passHostHeader = true\n [frontends.frontend1.routes]\n [frontends.frontend1.routes.main]\n rule = \"Host:myserver.domain.com,localhost\"\n\n[api]\n entryPoint = \"traefik\"\n dashboard = true\nThe 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 \u201cmeshcentral-data\u201d folder. You can use the two certificate files as-is.
The backends section configures one MeshCentral server on port \u201c4430\u201d. 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 \u201cmyserver.domain.com\u201d or \u201clocalhost\u201d.
Finally, the API section creates a web portal on port 8080 for monitoring of Traefik.
"},{"location":"meshcentral/#haproxy-reverse-proxy-setup","title":"HAProxy Reverse-Proxy Setup","text":"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: https://www.haproxy.org/
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 \u201cX-Forwarded-Host\u201d 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\u2019s Encrypt cert bot for getting a real TLS certificate and \u201cmesh.sample.com\u201d being redirected to 127.0.0.1:444.
global\n log /dev/log local0\n log /dev/log local1 notice\n chroot /var/lib/haproxy\n stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners\n stats timeout 30s\n user haproxy\n group haproxy\n daemon\n\ndefaults\n log global\n mode http\n option httplog\n option dontlognull\n option forwardfor\n option http-server-close\n\nfrontend http\n bind *:80\n redirect scheme https code 301 if !{ ssl_fc }\n\nfrontend https\n bind *:443 ssl crt /etc/haproxy/cert.pem\n http-request add-header X-Forwarded-Proto https\n acl acmepath path_beg /.well-known/acme-challenge/\n acl meshcentralhost hdr(host) -i mesh.sample.com\n acl meshcentralhost hdr(host) -i mesh.sample.com:443\n use_backend acme if acmepath\n use_backend meshcentral if meshcentralhost\n\nbackend acme\n server certbot localhost:54321\n\nbackend meshcentral\n http-request add-header X-Forwarded-Host %[req.hdr(Host)]\n server meshcentral 127.0.0.1:444\nOn 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.
{\n \"settings\": {\n \"Cert\": \"myservername.domain.com\",\n \"Port\": 444,\n \"AliasPort\": 443,\n \"RedirPort\": 0,\n \"TlsOffload\": \"127.0.0.1\"\n },\n \"domains\": {\n \"\": {\n \"certUrl\": \"https://127.0.0.1:443/\"\n }\n }\n}\nWe also specify \u201c127.0.0.1\u201d in TLS offload since we want MeshCentral to make use of the X-Forwarded-Host header that is set by HAProxy.
"},{"location":"meshcentral/#running-in-a-production-environment","title":"Running in a Production Environment","text":"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 \u201cNODE_ENV\u201d must be set to \u201cproduction\u201d. On Linux, this is done like this:
export NODE_ENV=production\nOn Windows, it\u2019s done like this:
SET NODE_ENV=production\nSpecial 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.\nMeshCentral v0.2.2-u, Hybrid (LAN + WAN) mode, Production mode.\nMeshCentral Intel(R) AMT server running on devbox.mesh.meshcentral.com:4433.\nMeshCentral HTTPS web server running on devbox.mesh.meshcentral.com:443.\nIn 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.
"},{"location":"meshcentral/#two-step-authentication","title":"Two step authentication","text":"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 \u201cMy Account\u201d tab or the \u201cMy Account\u201d menu in the mobile application. They then select, \u201cAdd 2-stop login\u201d 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\u2019s 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.
"},{"location":"meshcentral/#server-backup-restore","title":"Server Backup & Restore","text":"It\u2019s 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\nmeshcentral-files\nIf 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\nThen, keep the backup.archive file in a safe place. It\u2019s 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 \u201cmeshcentral-data\u201d could impersonate the server.
To restore back backup, just install a MeshCentral server, make sure it works correctly. Stop it, wipe the old \u201cmeshcentral-data\u201d and \u201cmeshcentral-files\u201d and put the backup version instead. If using MongoDB, copy the backup.archive back, make sure to clean up any existing \u201cmeshcentral\u201d database, run \u201cmongo\u201d and type:
use meshcentral\ndb.dropDatabase()\nThen exit with Ctrl-C and run:
mongorestore --archive=backup.archive\nThis 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
sudo systemctl stop meshcentral.service\nnano /opt/meshcentral/meshcentral-data/config.json\nRemove underscored items
sudo systemctl start meshcentral.service\nsudo systemctl status meshcentral.service\nLog into your MC:
Create desktop app
Enter the Client ID and Client Secret into MC
"},{"location":"meshcentral/#hashicorp-vault-support","title":"HashiCorp Vault support","text":"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: https://www.vaultproject.io/
Once you got a MeshCentral server working correctly, you can start a simple demonstration Vault server by typing:
vault server -dev\nWhen 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 \u201cmeshcentral-data\u201d into Vault by typing this:
node node_modules/meshcentral --vaultpushconfigfiles --vault http://127.0.0.1:8200 --token s.cO4\u2026 --unsealkey 7g4w\u2026 --name meshcentral\nOnce 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 \u201csecret/meshcentral\u201d:
The \u201cconfig.json\u201d and \u201cterms.txt\u201d files and files in \u201cmeshcentral-data\u201d that end with \u201c.key\u201d, \u201c.crt\u201d, \u201c.jpg\u201d and \u201c.png\u201d 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\u2026 --unsealkey 7g4w\u2026 --name meshcentral\nMeshCentral 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 \u201cmeshcentral-data\u201d that contains only the Vault configuration like this:
{\n \"settings\": {\n \"vault\": {\n \"endpoint\": \"http://127.0.0.1:8200\",\n \"token\": \"s.cO4Q\u2026\",\n \"unsealkey\": \"7g4wFC\u2026\",\n \"name\": \"meshcentral\"\n }\n }\n}\nOnce the config.json file is setup, you can just run MeshCentral without any arguments.
node node_modules/meshcentral\nLastly 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\u2026 --unsealkey 7g4w\u2026 --name meshcentral\nAnd delete the Vault secrets using this:
node node_modules/meshcentral --vaultdeleteconfigfiles --vault http://127.0.0.1:8200 --token s.cO4\u2026 --unsealkey 7g4w\u2026 --name meshcentral\nRegardless 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 \u201c_CRYPT\u201d field.
Only some data fields are encrypted and the \u201c_CRYPT\u201d entry will only be present when one or more fields are present that need to be secured. To enable this feature, add the \u201cDbRecordsEncryptKey\u201d with a password string to the \u201csettings\u201d section of the config.json like this:
{\n \"settings\": {\n \"Port\": 4430,\n \"RedirPort\": 800,\n \"DbRecordsEncryptKey\": \"MyReallySecretPassword\"\n }\n}\nThe 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\nThis 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:
{\n \"settings\": {\n \"Port\": 4430,\n \"RedirPort\": 800,\n \"DbRecordsDecryptKey\": \"MyReallySecretPassword\"\n }\n}\nWhen 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\nIt\u2019s 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.
Also note that database record encryption can and should be used along with other data protection systems.
"},{"location":"meshcentral/#mongodb-free-server-monitoring","title":"MongoDB free server monitoring","text":"If running with MongoDB version 4.x, there is a free database monitoring service that is provided. Just run \u201cmongo\u201d and you may see the following:
Type \u201cdb.enableFreemonitoring()\u201d 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.
"},{"location":"meshcentral/#meshcentral-single-sign-on-sso","title":"MeshCentral Single Sign-On (SSO)","text":"As with any web application deployed in organization, it\u2019s 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\u2019s Encrypt. After the web site is working correctly user the steps below.
"},{"location":"meshcentral/#ldap","title":"LDAP","text":"You can integrate LDAP using these configuration options
"},{"location":"meshcentral/#twitter-authentication","title":"Twitter Authentication","text":"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 https://developer.twitter.com/en/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 \u201cEnable Sign in with Twitter\u201d and set the callback URL to \u201chttps://(server.domain.com)/auth-twitter-callback\u201d. 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 \u201cKeys and tokens\u201d tab. You will need the \u201cAPI Key\u201d and \u201cAPI secret key\u201d values. In the MeshCentral config.json, place these two values as \u201cclientid\u201d and \u201cclientsecret\u201d of the Twitter section of the \u201cAuthStrategies\u201d.
Once done, your config.json should look a bit like this:
{\n \"settings\": {\n \"Cert\": \"myserver.mydomain.com\",\n \"Port\": 443,\n \"RedirPort\": 80\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"NewAccounts\": true,\n \"authStrategies\": {\n \"twitter\": {\n \"clientid\": \"xxxxxxxxxxxxxxxxxxxxxxx\",\n \"clientsecret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n }\n }\n }\n }\n}\nNote 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.
"},{"location":"meshcentral/#google-github-reddit-authentication","title":"Google, GitHub, Reddit Authentication","text":"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 \u201cClientID\u201d and \u201cClientSecret\u201d 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.
{\n \"settings\": {\n \"Cert\": \"myserver.mydomain.com\",\n \"Port\": 443,\n \"RedirPort\": 80\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"NewAccounts\": true,\n \"authStrategies\": {\n \"twitter\": {\n \"__callbackurl\": \"https://server/auth-twitter-callback\",\n \"clientid\": \"xxxxxxxxxxxxxxxxxxxxxxx\",\n \"clientsecret\": \" xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \"\n },\n \"google\": {\n \"__callbackurl\": \"https://server/auth-google-callback\",\n \"clientid\": \"xxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\",\n \"clientsecret\": \"xxxxxxxxxxxxxxxxxxxxxxx\"\n },\n \"github\": {\n \"__callbackurl\": \"https://server/auth-github-callback\",\n \"clientid\": \"xxxxxxxxxxxxxxxxxxxxxxx\",\n \"clientsecret\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n },\n \"reddit\": {\n \"__callbackurl\": \"https://server/auth-reddit-callback\",\n \"clientid\": \"xxxxxxxxxxxxxxxxxxxxxxx\",\n \"clientsecret\": \" xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \"\n }\n }\n }\n }\n}\nIt\u2019s 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.
"},{"location":"meshcentral/#microsoft-azure-active-directory","title":"Microsoft Azure Active Directory","text":"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 \u201cCertificates & secrets\u201d section and click \u201cNew client secret\u201d. 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:
{\n \"settings\": {\n \"Cert\": \"myserver.mydomain.com\",\n \"Port\": 443,\n \"RedirPort\": 80\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"NewAccounts\": false,\n \"authStrategies\": {\n \"azure\": {\n \"newAccounts\": true,\n \"clientid\": \"be4aadd3-77b8-4e55-af8a-4b8e2d994cb5\",\n \"clientsecret\": \"NP0XXXXXXXXXXXXXXXXXXX\",\n \"tenantid\": \"18910a48-e492-4c49-8043-3449f7964bd6\"\n }\n }\n }\n }\n}\nThe \u201cApplication ID\u201d value is placed as \u201cClient ID\u201d in the configuration file. You can also see that in the example above, we have \u201cNewAccounts\u201d 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\u2019s 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.
"},{"location":"meshcentral/#jumpcloud-authentication-using-saml","title":"JumpCloud Authentication using SAML","text":"While using OAuth may be interesting, it\u2019s 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\u2019s Encrypt to get a valid TLS certificate. Then, start by going to https://jumpcloud.com and creating an administrator account. Once setup, go to \u201cApplications\u201d and click on the big plug sign to create a new application.
You will need to create a custom SAML application by clicking the \u201cCustom SAML App\u201d.
Then, you can fill in the form with an application name and logo.
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 \u201cAll Users\u201d 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 \u201cApplications\u201d tab, click on your new application and select \u201cDownload Certificate\u201d as shown here.
Save the certificate as \u201cjumpcloud-saml.pem\u201d and place it in the \u201cmeshcentral-data\u201d folder. You are now ready to configure MeshCentral. Edit the config.json and make it look like this:
{\n \"settings\": {\n \"Cert\": \"myserver.mydomain.com\",\n \"Port\": 443,\n \"RedirPort\": 80\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"NewAccounts\": false,\n \"authStrategies\": {\n \"jumpcloud\": {\n \"__callbackurl\": \"https://server/auth-jumpcloud-callback\",\n \"NewAccounts\": true,\n \"entityid\": \"meshcentral\",\n \"idpurl\": \"https://sso.jumpcloud.com/saml2/saml2\",\n \"cert\": \"jumpcloud-saml.pem\"\n }\n }\n }\n }\n}\nTake note that the \u201centityid\u201d, \u201cidpurl\u201d and \u201ccert\u201d 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 \u201cNewAccounts\u201d 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\u2019s 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.
"},{"location":"meshcentral/#generic-saml-setup","title":"Generic SAML setup","text":"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:
{\n \"settings\": {\n \"Cert\": \"myserver.mydomain.com\",\n \"Port\": 443,\n \"RedirPort\": 80\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"NewAccounts\": 1,\n \"authStrategies\": {\n \"saml\": {\n \"__callbackurl\": \"https://server/auth-saml-callback\",\n \"entityid\": \"meshcentral\",\n \"idpurl\": \"https://server/saml2\",\n \"cert\": \"saml.pem\"\n }\n }\n }\n }\n}\nThe callback URL will be of the form \u201chttps://(servername)/auth-saml-callback\u201d. You should set the entityid, idpurl as given by the identity provider. Lastly, place the identity provider certificate file in the \u201cmeshcentral-data\u201d folder and indicate the name of the file in \u201ccert\u201d. 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\".
"},{"location":"meshcentral/#generic-openid-connect-setup","title":"Generic OpenID Connect Setup","text":"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.
{\n \"settings\": {\n \"cert\": \"mesh.your.domain\",\n \"port\": 443,\n \"sqlite3\": true\n },\n \"domains\": {\n \"\": {\n \"title\": \"Mesh\",\n \"title2\": \".Your.Domain\",\n \"authStrategies\": {\n \"oidc\": {\n \"issuer\": \"https://sso.your.domain\",\n \"clientid\": \"XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX\",\n \"clientsecret\": \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\",\n \"newAccounts\": true\n }\n }\n }\n }\n}\nAs 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.
In 2007, the first version of MeshCentral was built. We will refer to it as \u201cMeshCentral1\u201d. 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:
It\u2019s 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.
"},{"location":"meshcentral/#additional-resources","title":"Additional Resources","text":"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.
"},{"location":"meshcentral/#conclusion","title":"Conclusion","text":"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.
"},{"location":"meshcentral/#license","title":"License","text":"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.
"},{"location":"meshcentral/#annex-1-sample-configuration-file","title":"Annex 1: Sample Configuration File","text":"In this annex, we present a complete sample config.json file. You would put this file in the \u201cmeshcentral-data\u201d 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.
{\n \"settings\": {\n \"MongoDb\": \"mongodb://127.0.0.1:27017/meshcentral\",\n \"MongoDbCol\": \"meshcentral\",\n \"Port\": 4430,\n \"AliasPort\": 443,\n \"RedirPort\": 800,\n \"TlsOffload\": \"127.0.0.1\",\n \"MpsPort\": 44330,\n \"MpsAliasPort\": 4433,\n \"MpsTlsOffload\": true,\n \"SessionTime\": 30,\n \"SessionKey\": \"MyReallySecretPassword\",\n \"AllowLoginToken\": true,\n \"AllowFraming\": true,\n \"WebRTC\": true,\n \"ClickOnce\": true\n },\n \"domains\": {\n \"\": {\n \"Title\": \"MyServer\",\n \"Title2\": \"Servername\",\n \"TitlePicture\": \"title-sample.png\",\n \"UserQuota\": 1048576,\n \"MeshQuota\": 248576,\n \"NewAccounts\": true,\n \"Footer\": \"<a href='https://twitter.com/mytwitter'>Twitter</a>\",\n \"PasswordRequirements\": { \"min\": 8, \"max\": 128, \"upper\": 1, \"lower\": 1, \"numeric\": 1, \"nonalpha\": 1 }\n },\n \"customer1\": {\n \"Dns\": \"customer1.myserver.com\",\n \"Title\": \"Customer1\",\n \"Title2\": \"TestServer\",\n \"NewAccounts\": 1,\n \"Auth\": \"sspi\",\n \"Footer\": \"Test\"\n },\n \"info\": {\n \"share\": \"C:\\\\ExtraWebSite\"\n }\n },\n \"letsencrypt\": {\n \"email\": \"myemail@myserver.com \",\n \"names\": \"myserver.com,customer1.myserver.com\",\n \"rsaKeySize\": 3072,\n \"production\": false\n },\n \"peers\": {\n \"serverId\": \"server1\",\n \"servers\": {\n \"server1\": { \"url\": \"wss://192.168.2.133:443/\" },\n \"server2\": { \"url\": \"wss://192.168.1.106:443/\" }\n }\n },\n \"smtp\": {\n \"host\": \"smtp.myserver.com\",\n \"port\": 25,\n \"from\": \"myemail@myserver.com\",\n \"tls\": false\n }\n}\nAll these values are examples only, this config.json should just be used as an example and none of the values here are real.
"},{"location":"meshcentral/#annex-2-tips-tricks","title":"Annex 2: Tips & Tricks","text":"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
"},{"location":"meshcentral/#remote-terminal","title":"Remote Terminal","text":"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\nHowever, 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\nThis will run bash in interactive mode and work correctly.
"},{"location":"meshcentral/#ssh-and-sftp-integration-to-the-terminal","title":"SSH and SFTP integration to the Terminal","text":"MeshCentral has built-in web-based integration of SSH in the \"Terminal\" tab and SFTP in the \"Files\" tab.
"},{"location":"meshcentral/SSLnletsencrypt/","title":"SSL/Letsencrypt","text":""},{"location":"meshcentral/SSLnletsencrypt/#meshcentral-supports-ssl-using-self-generated-certs-your-own-certs-or-letsencrypt","title":"MeshCentral supports SSL using self generated certs, your own certs or Letsencrypt","text":""},{"location":"meshcentral/SSLnletsencrypt/#enabling-letsencrypt","title":"Enabling letsencrypt","text":"Make sure you match and/or adjust all the following settings appropriately in your config.json file:
{\n \"settings\": {\n \"redirPort\"\n \"cert\": \"yourdomain.com\"\n },\n \"domains\": {\n \"letsencrypt\": {\n \"__comment__\": \"Requires NodeJS 8.x or better, Go to https://letsdebug.net/ first before trying Let's Encrypt.\",\n \"email\": \"myemail@myserver.com\",\n \"names\": \"myserver.com,customer1.myserver.com\",\n \"skipChallengeVerification\": false,\n \"production\": true\n },\n }\n}\nIf 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.
"},{"location":"meshcentral/SSLnletsencrypt/#useful-resourcestroubleshooting","title":"Useful resources/troubleshooting","text":"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.
"},{"location":"meshcentral/agents/","title":"Mesh Agents","text":""},{"location":"meshcentral/agents/#windows","title":"Windows","text":"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
net start \"mesh agent\"net stop \"mesh agent\"net restart \"mesh agent\"Troubleshooting steps: Needs info
"},{"location":"meshcentral/agents/#linux-bsd","title":"Linux / BSD","text":"Uninstall: sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall
Default Install Path: /usr/local/mesh_services/meshagent/meshagent
Launches from /Library/LaunchAgents/meshagent.plist
Controlling agent
launchctl stop meshagent\nlaunchctl start meshagent\nInstall:
Uninstall: sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall
For OSx 11+ including Big Sur, Monterey and later
"},{"location":"meshcentral/agents/#apple-macos","title":"Apple macOS","text":"For macOS 10.x including Catalina, Mojave, High Sierra, Sierra, El Capitan, Yosemite, Mavericks, Mountain Lion and earlier.
"},{"location":"meshcentral/agents/#mobile-device-android","title":"Mobile Device (Android)","text":""},{"location":"meshcentral/agents/#meshcentral-assistant","title":"MeshCentral Assistant","text":"See Assistant
"},{"location":"meshcentral/agents/#apple-macos-binary-installer_1","title":"Apple MacOS Binary Installer","text":""},{"location":"meshcentral/agents/#agent-commands","title":"Agent Commands","text":"agentmsg : Add/Remove badged messages to the device's web ui
agentmsg add \"[message]\" [iconIndex]\n agentmsg remove [index]\n agentmsg list\nagentupdate : Manually trigger an agent self-update
alert : Display an alert dialog on the logged in session
alert TITLE, CAPTION [, TIMEOUT]\namt
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]\nfdcount : 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]\nkvmmode : Displays the KVM Message Format
location : Displays saves location information about the connected agent
lock
log : Writes a message to the logfile
log [message]\nls : 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]\nmsh : 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]\nplugin : Invokes a plugin
plugin [pluginName] [args]\npower : Performs the specified power action
power [action]\n LOGOFF = 1\n SHUTDOWN = 2\n REBOOT = 3\n SLEEP = 4\n HIBERNATE = 5\n DISPLAYON = 6\n KEEPAWAKE = 7\n BEEP = 8\n CTRLALTDEL = 9\n VIBRATE = 13\n FLASH = 14\nprivacybar : Sets/Gets the default pinned state of the Privacy Bar on windows
privacybar [PINNED|UNPINNED]\nps : 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)\nscanwifi : 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\nsetclip : Sets clipboard data to the agent
setclip [text]\nsetdebug : Sets the location target for debug messages
setdebug [target]\n0 = Disabled\n1 = StdOut\n2 = This Console\n* = All Consoles\n4 = WebLog\n8 = Logfile\nsmbios : 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]\ntimerinfo : Displays metadata about any configured timers on the event loop
toast : Displays a toast message on the logged in user's session
toast [message]\ntranslations : Shows the currently configured translations
type
type (filepath) [maxlength]\nuac : Get/Sets the Windows UAC mode
uac [get|interactive|secure]\nunzip
unzip input, destination\nusers : 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]\nwallpaper : Gets/Toggles the logged in user's desktop background image
wallpaper (GET|TOGGLE)\nwpfhwacceleration : Enable/Disable WPF HW Acceleration on Windows
wpfhwacceleration (ON|OFF|STATUS)\nwsclose
wsconnect
wslist
wssend
zip
zip (output file name), input1 [, input n]\nYou 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
"},{"location":"meshcentral/assistant/","title":"MeshCentral Assistant","text":""},{"location":"meshcentral/assistant/#initial-setup","title":"Initial Setup","text":""},{"location":"meshcentral/assistant/#agent-invite-code","title":"Agent Invite Code","text":"\"domains\": {\n \"\": {\n \"agentInviteCodes\": true\n }\n}\nClick on the 'Invite' button next to the device group name to access it.
"},{"location":"meshcentral/assistant/#link-invitation","title":"Link Invitation","text":"For link invitation web page customization:
meshcentral-data create a folder called meshcentral-webviews folder in it and copy the file node_modules/meshcentral/views/invite.handlebars into it.This option will show up if you have an SMTP email server set up with MeshCentral.
For invitation email customization:
meshcentral-data create a folder called meshcentral-webemails folder in it and copy the files node_modules/meshcentral/emails/mesh-invite.txt and node_modules/meshcentral/emails/mesh-invite.html into it.You can also get an email notification when someone clicks the \"Request Help\" button in the Assistant agent.
"},{"location":"meshcentral/codesigning/","title":"Code Signing","text":""},{"location":"meshcentral/codesigning/#authenticode-js-video","title":"Authenticode-JS Video","text":"Nodejs Code Signing module
MeshCentral comes with authenticode.js, you can run it like this:
node node_modules/meshcentral/authenticode-js\nand you will get
MeshCentral Authenticode Tool.\nUsage:\n node authenticode.js [command] [options]\nCommands:\n info: Show information about an executable.\n --exe [file] Required executable to view information.\n --json Show information in JSON format.\n sign: Sign an executable.\n --exe [file] Required executable to sign.\n --out [file] Resulting signed executable.\n --pem [pemfile] Certificate & private key to sign the executable with.\n --desc [description] Description string to embbed into signature.\n --url [url] URL to embbed into signature.\n --hash [method] Default is SHA384, possible value: MD5, SHA224, SHA256, SHA384 or SHA512.\n --time [url] The time signing server URL.\n --proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://\n unsign: Remove the signature from the executable.\n --exe [file] Required executable to un-sign.\n --out [file] Resulting executable with signature removed.\n createcert: Create a code signging self-signed certificate and key.\n --out [pemfile] Required certificate file to create.\n --cn [value] Required certificate common name.\n --country [value] Certificate country name.\n --state [value] Certificate state name.\n --locality [value] Certificate locality name.\n --org [value] Certificate organization name.\n --ou [value] Certificate organization unit name.\n --serial [value] Certificate serial number.\n timestamp: Add a signed timestamp to an already signed executable.\n --exe [file] Required executable to sign.\n --out [file] Resulting signed executable.\n --time [url] The time signing server URL.\n --proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://\n icons: Show the icon resources in the executable.\n --exe [file] Input executable.\n saveicons: Save an icon group to a .ico file.\n --exe [file] Input executable.\n --out [file] Resulting .ico file.\n --icongroup [groupNumber] Icon groupnumber to save to file.\n --removeicongroup [number]\n --icon [groupNumber],[filename.ico]\n\nNote that certificate PEM files must first have the signing certificate,\nfollowed by all certificates that form the trust chain.\n\nWhen doing sign/unsign, you can also change resource properties of the generated file.\n\n --filedescription [value]\n --fileversion [value]\n --internalname [value]\n --legalcopyright [value]\n --originalfilename [value]\n --productname [value]\n --productversion [value]\nIf 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
Now that MeshCentral customizes and signs the agent, you can set that value to anything you like.
\"domains\": {\n \"agentFileInfo\": {\n \"filedescription\": \"sample_filedescription\",\n \"fileversion\": \"0.1.2.3\",\n \"internalname\": \"sample_internalname\",\n \"legalcopyright\": \"sample_legalcopyright\",\n \"originalfilename\": \"sample_originalfilename\",\n \"productname\": \"sample_productname\",\n \"productversion\": \"v0.1.2.3\"\n }\n}\nThere 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:
and more!
"},{"location":"meshcentral/customization/","title":"Customization","text":"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.
"},{"location":"meshcentral/customization/#web-branding","title":"Web Branding","text":"You can put your own logo on the top of the web page. To get started, get the file \u201clogoback.png\u201d from the folder \u201cnode_modules/meshcentral/public/images\u201d and copy it to your \u201cmeshcentral-data\u201d folder. In this example, we will change the name of the file \u201clogoback.png\u201d to \u201ctitle-mycompany.png\u201d. 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\": {\n \"\": {\n \"Title\": \"\",\n \"Title2\": \"\",\n \"TitlePicture\": \"title-sample.png\",\n \"loginPicture\": \"logintitle-sample.png\",\n \"welcomeText\": \"This is sample text\",\n \"welcomePicture\": \"mainwelcome-04.jpg\",\n \"welcomePictureFullScreen\": true,\n \"siteStyle\": \"1\",\n \"nightMode\": \"1\",\n \"meshMessengerTitle\": \"Mesh Chat\",\n \"meshMessengerPicture\": \"chatimage.png\",\n \"footer\": \"This is a HTML string displayed at the bottom of the web page when a user is logged in.\",\n \"loginfooter\": \"This is a HTML string displayed at the bottom of the web page when a user is not logged in.\"\n },\nThis 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 \u201cMy Server\u201d tab. By default, it\u2019s 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 \u201cserver.jpg\u201d file that is 200 x 200 pixels in the \u201cmeshcentral-data\u201d 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.
"},{"location":"meshcentral/customization/#customizing-web-icons","title":"Customizing Web Icons","text":"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.
Agents can be invited by public link or via email. Click Here to see details.
"},{"location":"meshcentral/customization/#agent-branding","title":"Agent Branding","text":"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\": {\n \"\": {\n \"agentCustomization\": {\n \"displayName\": \"MeshCentral Agent\",\n \"description\": \"Mesh Agent background service\",\n \"companyName\": \"Mesh Agent Company\",\n \"serviceName\": \"Mesh Agent Service\",\n \"installText\": \"Text string to show in the agent installation dialog box\",\n \"image\": \"mylogo.png\",\n \"fileName\": \"meshagent\",\n \"foregroundColor\": \"#FFA500\",\n \"backgroundColor\": \"#EE82EE\"\n }\n }\n}\nYou can change the terms of use of the web site by adding a \u201cterms.txt\u201d file in the \u201cmeshcentral-data\u201d 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\u2019s requested.
For example, placing this in \u201cterms.txt\u201d
<br />\nThis is a <b>test file</b>.\nWill show this on the terms of use web page.
"},{"location":"meshcentral/debugging/","title":"Debugging","text":""},{"location":"meshcentral/debugging/#websockets-video","title":"Websockets Video","text":"Make sure you understand how MeshCentral works with your browser using chrome developer tools.
"},{"location":"meshcentral/debugging/#meshcentral-server","title":"MeshCentral Server","text":""},{"location":"meshcentral/debugging/#useful-configjs-settings","title":"Useful config.js settings","text":"https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json
\"AgentsInRAM\": false,\n\"AgentUpdateBlockSize\": 2048,\n\"agentUpdateSystem\": 1,\n\"noAgentUpdate\": 1,\n\"WsCompression\": false,\n\"AgentWsCompression\": false,\nNote 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\nnode node_modules\\meshcentral\nYou do NOT do this:
cd C:\\Program Files\\Open Source\\MeshCentral\\node_modules\\meshcentral\nnode meshcentral\nThe 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\ncd c:\\meshcentral\nnpm install meshcentral\nnode node_modules\\meshcentral\n(ctrl-c when done installing optional modules)\nnode node_modules\\meshcentral --install\nThis 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.
"},{"location":"meshcentral/debugging/#unable-to-update-server","title":"Unable to update server","text":"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:
{\n \"settings\": {\n \"npmPath\": \"c:\\\\npm.exe\",\n \"npmProxy\": \"http://1.2.3.4:80\"\n }\n}\nThe 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\nnpm install meshcentral\nnode node_modules/meshcentral\nThen 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\nnode node_modules/meshcentral --uninstall\nnode node_modules/meshcentral --start\nnode node_modules/meshcentral --stop\nIf 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.
"},{"location":"meshcentral/debugging/#running-meshcentral-server-in-debug-mode","title":"Running Meshcentral server in debug mode","text":"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\nA 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\nHere is the list of all debug options:
cookie - Cookie encoder\ndispatch - Message Dispatcher\nmain - Main Server Messages\npeer - MeshCentral Server Peering\nagent - MeshAgent traffic\nagentupdate - MeshAgent update\ncert - Server Certificate\ndb - Server Database\nemail - Email/SMS/Push Traffic\nweb - Web Server\nwebrequest - Web Server Requests\nrelay - Web Socket Relay\nhttpheaders - Web Server HTTP Headers\nauthlog - User Authentication Log\namt - Intel AMT\nwebrelay - Connection Relay\nmps - CIRA Server\nmpscmd - CIRA Server Commands\nYou can also specify the debug option in the config.json file in the settings section. For example:
\"settings\": {\n \"debug\": \"web,amt,mps\"\n}\nYou 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\nlog_statement = 'all' # none, ddl, mod, all\nThe 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*\nIf you want to change node to meshcentral in journalctl, add this to /etc/systemd/system/meshcentral.service.
SyslogIdentifier=meshcentral\nUsing the servers My Server > console
agentstatus - Gives you summary counts of problemsagentissues - Gives IP:port and what errordupagents - Gives duplicateAgent IP's, counts and namesTo log everything that's possible, prepare the log directory.
mkdir /meshcentral/meshcentral-logs/\nchown tactical:tactical logs\nln -s ../meshcentral-logs/log.txt /meshcentral/meshcentral-data/log.txt\nAnd then add this to your config.
\"meshErrorLogPath\": \"/meshcentral/meshcentral-logs/\",\n \"authLog\": \"/meshcentral/meshcentral-logs/auth.log\",\n \"log\": [\n \"cookie\",\n \"dispatch\",\n \"main\",\n \"peer\",\n \"web\",\n \"webrequest\",\n \"relay\",\n \"webrelaydata\",\n \"webrelay\",\n \"mps\",\n \"mpscmd\",\n \"swarm\",\n \"swarmcmd\",\n \"agentupdate\",\n \"agent\",\n \"cert\",\n \"db\",\n \"email\",\n \"amt\",\n \"httpheaders\",\n \"websocket\"\n ],\nYou'll then have 3 files:
-rw-rw-r-- 1 tactical tactical 2593 Feb 2 12:22 auth.log\n-rw-r--r-- 1 tactical tactical 147593 Feb 2 12:31 log.txt\n-rw-rw-r-- 1 tactical tactical 381 Feb 2 12:02 mesherrors.txt\nlog.txt will now log everything in the Trace tab
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\" ],\nOf course, this is just for debugging.
"},{"location":"meshcentral/debugging/#finding-system-id-types","title":"Finding system ID types","text":"https://serverurl/meshagents aka trying figure out what this is
"},{"location":"meshcentral/debugging/#pull-down-cert-crt-file-from-internet","title":"Pull down cert .crt file from internet","text":"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\nservice meshcentral restart\nTroubleshooting agent
./meshagent -state\nThis automatically downloads all agent error logs into meshcentral-data/agenterrorlogs.txt
Set in config.json
\"agentLogDump\": true\nOn the server goto the agents console tab. Type:
info\nhttps://github.com/Ylianst/MeshAgent/blob/master/meshcore/agentcore.h#L190
controlChannelDebug=1\nlogUpdate=1\nIf 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.
"},{"location":"meshcentral/debugging/#meshagent-commands","title":"MeshAgent Commands","text":"MeshAgent run\nMeshAgent dbTool.js list\nForcing Core version from Cmdline
MeshAgent.exe dbTool.js import CoreModuleMeshAgent#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();\"\nif 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();\"\nThis 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.
"},{"location":"meshcentral/debugging/#agent-debugging-using-meshcore-js-debugger","title":"Agent Debugging using MeshCore JS Debugger","text":"(#119) How to test changes to the meshagent and recompile them.
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.
"},{"location":"meshcentral/debugging/#troubleshooting-agent-connectivity","title":"Troubleshooting Agent connectivity","text":"If an agent keeps disconnecting and reconnecting, add this line to the \"settings\" section of the config.json:
\"agentping\": 30\nThis 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\nThis 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\nThis 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\n\"browserpong\": 30\nSame idea, browser side instead of agent side.
"},{"location":"meshcentral/debugging/#intel-amt","title":"Intel AMT","text":"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.
"},{"location":"meshcentral/devicetabs/","title":"Device Tabs","text":""},{"location":"meshcentral/devicetabs/#search-or-filter","title":"Search or Filter","text":"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
"},{"location":"meshcentral/devicetabs/#general","title":"General","text":"For viewing general information about the agent
Actions Notes Log Event Message PDU On/Off/Control Chat
"},{"location":"meshcentral/devicetabs/#7-day-power-state","title":"7 Day Power State","text":"Legend
You can set alternate port in the link if it's not default by right-clicking.
For connecting to the machines KVM interface.
"},{"location":"meshcentral/devicetabs/#connect-button","title":"Connect Button","text":"Right-clicking on Connect button will give you additional options:
Right-clicking on RDP Connect button allows you to specify Alternate Port.
"},{"location":"meshcentral/devicetabs/#intel-amt-connect-button","title":"Intel AMT Connect Button","text":"Uses Intel AMT to control video output of the hardware video card.
"},{"location":"meshcentral/devicetabs/#during-a-desktop-session","title":"During a desktop session","text":"Bottom left include:
Top Right include:
Actions
Settings
Bottom right include:
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:
For transferring files to and from the agent.
"},{"location":"meshcentral/devicetabs/#events","title":"Events","text":"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.
"},{"location":"meshcentral/devicetabs/#details","title":"Details","text":"Agent information that includes:
Note you can show CPU and Memory usage info by clicking the icon in the top right corner
"},{"location":"meshcentral/devicetabs/#intel-amt","title":"Intel AMT","text":""},{"location":"meshcentral/devicetabs/#console","title":"Console","text":"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
Any item in the config.json file starting with an underscore character are ignored.
Ignored
\"_title\": \"MyServer\"\nValid setting
\"title\": \"MyServer\"\njson 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
"},{"location":"meshcentral/faq/#help-ive-been-hacked-there-are-weird-agents-appearing-in-my-meshcentral-console","title":"Help! I've been hacked there are weird agents appearing in my MeshCentral Console","text":"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)! :)
"},{"location":"meshcentral/faq/#branding-and-customization","title":"Branding and Customization","text":"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.
"},{"location":"meshcentral/faq/#mac-clients","title":"Mac Clients","text":"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
"},{"location":"meshcentral/faq/#im-using-cloudflare-and-im-getting-a-black-screen-but-the-mouse-moves","title":"I'm using CloudFlare and I'm getting a black screen but the mouse moves?","text":"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
"},{"location":"meshcentral/openidConnectStrategy/","title":"Using the OpenID Connect Strategy on MeshCentral","text":""},{"location":"meshcentral/openidConnectStrategy/#overview","title":"Overview","text":""},{"location":"meshcentral/openidConnectStrategy/#introduction","title":"Introduction","text":"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.
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 \u201cAuthorization Server\u201d, 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.
"},{"location":"meshcentral/openidConnectStrategy/#annotations","title":"Annotations","text":""},{"location":"meshcentral/openidConnectStrategy/#own-idp-ca-and-docker","title":"Own IDP, CA and Docker","text":"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 \u201cenvironment\u201d section:
environment:\n - NODE_EXTRA_CA_CERTS=/opt/meshcentral/meshcentral-data/chain.pem\nGenerally, 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.
"},{"location":"meshcentral/openidConnectStrategy/#basic-config-file-example","title":"Basic Config File Example","text":"{\n \"settings\": {\n \"cert\": \"mesh.your.domain\",\n \"port\": 443,\n \"sqlite3\": true\n },\n \"domains\": {\n \"\": {\n \"title\": \"MeshCentral\",\n \"title2\": \"Your sub-title\",\n \"authStrategies\": {\n \"oidc\": {\n \"issuer\": \"https://sso.your.domain\",\n \"clientid\": \"2d5685c5-0f32-4c1f-9f09-c60e0dbc948a\",\n \"clientsecret\": \"7PiGSLSLL4e7NGi67KM229tfK7Z7TqzQ\",\n \"newAccounts\": true\n }\n }\n }\n }\n}\nAs 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.
"},{"location":"meshcentral/openidConnectStrategy/#advanced-options","title":"Advanced Options","text":""},{"location":"meshcentral/openidConnectStrategy/#overview_1","title":"Overview","text":"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\u2019s take a look at an example of what your config file could look with a slightly more complicated configuration, including multiple manually defined endpoints.
"},{"location":"meshcentral/openidConnectStrategy/#advanced-config-file-example","title":"Advanced Config File Example","text":"{\n \"settings\": {\n \"cert\": \"mesh.your.domain\",\n \"port\": 443,\n \"redirPort\": 80,\n \"AgentPong\": 300,\n \"TLSOffload\": \"192.168.1.50\",\n \"SelfUpdate\": false,\n \"AllowFraming\": false,\n \"sqlite3\": true,\n \"WebRTC\": true\n },\n \"domains\": {\n \"\": {\n \"title\": \"Mesh\",\n \"title2\": \".Your.Domain\",\n \"orphanAgentUser\": \"~oidc:e48f8ef3-a9cb-4c84-b6d1-fb7d294e963c\",\n \"authStrategies\": {\n \"oidc\": {\n \"issuer\": {\n \"issuer\": \"https://sso.your.domain\",\n \"authorization_endpoint\": \"https://auth.your.domain/auth-endpoint\",\n \"token_endpoint\": \"https://tokens.sso.your.domain/token-endpoint\",\n \"end_session_endpoint\": \"https://sso.your.domain/logout\",\n \"jwks_uri\": \"https://sso.your.domain/jwks-uri\"\n },\n \"client\": {\n \"client_id\": \"110d5612-0822-4449-a057-8a0dbe26eca5\",\n \"client_secret\": \"4TqST46K53o3Z2Q88p39YwR6YwJb7Cka\",\n \"redirect_uri\": \"https://mesh.your.domain/auth-oidc-callback\",\n \"post_logout_redirect_uri\": \"https://mesh.your.domain/login\",\n \"token_endpoint_auth_method\": \"client_secret_post\",\n \"response_types\": \"authorization_code\"\n },\n \"custom\": {\n \"scope\": [ \"openid\", \"profile\", \"read.EmailAlias\", \"read.UserProfile\" ],\n \"preset\": null\n },\n \"groups\": {\n \"recursive\": true,\n \"required\": [\"Group1\", \"Group2\"],\n \"siteadmin\": [\"GroupA\", \"GroupB\"],\n \"revokeAdmin\": true,\n \"sync\": { \n \"filter\": [\"Group1\", \"GroupB\", \"OtherGroup\"]\n },\n \"claim\": \"GroupClaim\",\n \"scope\": \"read.GroupMemberships\"\n },\n \"logouturl\": \"https://sso.your.domain/logout?r=https://mesh.your.domain/login\",\n \"newAccounts\": true\n },\n {...}\n }\n }\n }\n}\nIn 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.
"},{"location":"meshcentral/openidConnectStrategy/#common-config-chart","title":"Common Config Chart","text":"Name Description Default Example Requiredissuer 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."},{"location":"meshcentral/openidConnectStrategy/#advanced-config-example","title":"Advanced Config Example","text":"\"issuer\": {\n \"issuer\": \"https://sso.your.domain\",\n \"authorization_endpoint\": \"https://auth.your.domain/auth-endpoint\",\n \"token_endpoint\": \"https://tokens.sso.your.domain/token-endpoint\",\n \"end_session_endpoint\": \"https://sso.your.domain/logout\",\n \"jwks_uri\": \"https://sso.your.domain/jwks-uri\"\n},\nThe 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.
\"issuer\": { \n \"type\": [\"string\",\"object\"],\n \"format\": \"uri\",\n \"description\": \"Issuer options. Requires issuer URI (issuer.issuer) to discover missing information unless using preset\",\n \"properties\": {\n \"issuer\": { \"type\": \"string\", \"format\": \"uri\", \"description\": \"URI of the issuer.\" },\n \"authorization_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"token_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"jwks_uri\": { \"type\": \"string\", \"format\": \"uri\" },\n \"userinfo_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"revocation_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"introspection_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"end_session_endpoint\": {\n \"type\": \"string\",\n \"format\": \"uri\",\n \"description\": \"URI to direct users to when logging out of MeshCentral.\",\n \"default\": \"this.issuer/logout\"\n },\n \"registration_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"token_endpoint_auth_methods_supported\": { \"type\": \"string\" },\n \"token_endpoint_auth_signing_alg_values_supported\": { \"type\": \"string\" },\n \"introspection_endpoint_auth_methods_supported\": { \"type\": \"string\" },\n \"introspection_endpoint_auth_signing_alg_values_supported\": { \"type\": \"string\" },\n \"revocation_endpoint_auth_methods_supported\": { \"type\": \"string\" },\n \"revocation_endpoint_auth_signing_alg_values_supported\": { \"type\": \"string\" },\n \"request_object_signing_alg_values_supported\": { \"type\": \"string\" },\n \"mtls_endpoint_aliases\": {\n \"type\":\"object\",\n \"properties\": {\n \"token_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"userinfo_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"revocation_endpoint\": { \"type\": \"string\", \"format\": \"uri\" },\n \"introspection_endpoint\": { \"type\": \"string\", \"format\": \"uri\" }\n }\n }\n },\n \"additionalProperties\": false\n},\nThere 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.
"},{"location":"meshcentral/openidConnectStrategy/#common-configs","title":"Common Configs","text":"Name Description Default Example Requiredclient_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"},{"location":"meshcentral/openidConnectStrategy/#advanced-config-example_1","title":"Advanced Config Example","text":"\"client\": {\n \"client_id\": \"00b3875c-8d82-4238-a8ef-25303fa7f9f2\",\n \"client_secret\": \"7PP453H577xbFDCqG8nYEJg8M3u8GT8F\",\n \"redirect_uri\": \"https://mesh.your.domain/auth-oidc-callback\",\n \"post_logout_redirect_uri\": \"https://mesh.your.domain/login\",\n \"token_endpoint_auth_method\": \"client_secret_post\",\n \"response_types\": \"authorization_code\"\n},\nThere 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.
\"client\": { \n \"type\": \"object\",\n \"description\": \"OIDC Client Options\",\n \"properties\": {\n \"client_id\": { \n \"type\": \"string\",\n \"description\": \"REQUIRED: The client ID provided by your Identity Provider (IdP)\"\n },\n \"client_secret\": {\n \"type\": \"string\",\n \"description\": \"REQUIRED: The client secret provided by your Identity Provider (IdP)\"\n },\n \"redirect_uri\": {\n \"type\": \"string\",\n \"format\": \"uri\",\n \"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)\"\n },\n \"post_logout_redirect_uri\": {\n \"type\": \"string\",\n \"format\": \"uri\",\n \"description\": \"URI for your IdP to send you after logging out of IdP via MeshCentral.\",\n \"default\": \"https:[currentHost][currentPath]/login\"\n },\n \"id_token_signed_response_alg\": { \"type\": \"string\", \"default\": \"RS256\" },\n \"id_token_encrypted_response_alg\": { \"type\": \"string\" },\n \"id_token_encrypted_response_enc\": { \"type\": \"string\" },\n \"userinfo_signed_response_alg\": { \"type\": \"string\" },\n \"userinfo_encrypted_response_alg\": { \"type\": \"string\" },\n \"userinfo_encrypted_response_enc\": { \"type\": \"string\" },\n \"response_types\": { \"type\": [\"string\", \"array\"], \"default\": [\"code\"] },\n \"default_max_age\": { \"type\": \"number\" },\n \"require_auth_time\": { \"type\": \"boolean\", \"default\": false }, \n \"request_object_signing_alg\": { \"type\": \"string\" },\n \"request_object_encryption_alg\": { \"type\": \"string\" },\n \"request_object_encryption_enc\": { \"type\": \"string\" },\n \"token_endpoint_auth_method\": {\n \"type\": \"string\",\n \"default\": \"client_secret_basic\",\n \"enum\": [ \"none\", \"client_secret_basic\", \"client_secret_post\", \"client_secret_jwt\", \"private_key_jwt\" ]\n }, \n \"introspection_endpoint_auth_method\": {\n \"type\": \"string\",\n \"default\": \"client_secret_basic\",\n \"enum\": [ \"none\", \"client_secret_basic\", \"client_secret_post\", \"client_secret_jwt\", \"private_key_jwt\" ]\n }, \n \"revocation_endpoint_auth_method\": {\n \"type\": \"string\",\n \"default\": \"client_secret_basic\",\n \"enum\": [ \"none\", \"client_secret_basic\", \"client_secret_post\", \"client_secret_jwt\", \"private_key_jwt\" ]\n }, \n \"token_endpoint_auth_signing_alg\": { \"type\": \"string\" },\n \"introspection_endpoint_auth_signing_alg\": { \"type\": \"string\" },\n \"revocation_endpoint_auth_signing_alg\": { \"type\": \"string\" },\n \"tls_client_certificate_bound_access_tokens\": { \"type\": \"boolean\" }\n },\n \"required\": [ \"client_id\", \"client_secret\" ],\n \"additionalProperties\": false\n},\nThese 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.
"},{"location":"meshcentral/openidConnectStrategy/#common-config-chart_1","title":"Common Config Chart","text":"Name Description Default Example Requiredscope 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"},{"location":"meshcentral/openidConnectStrategy/#advanced-config-example_2","title":"Advanced Config Example","text":"\"custom\": {\n \"scope\": [ \"openid\", \"profile\", \"read.EmailAlias\", \"read.UserProfile\" ],\n \"preset\": null,\n \"claims\": {\n \"name\": \"nameOfUser\",\n \"email\": \"publicEmail\"\n }\n},\nNOTE: You can preset to null if you want to explicitly disable presets.
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.
\"custom\": {\n \"type\": \"object\",\n \"properties\": {\n \"scope\": {\n \"type\": [\"string\", \"array\"],\n \"description\": \"A list of scopes to request from the issuer.\",\n \"default\": \"openid profile email\",\n \"examples\": [\"openid\", [\"openid\", \"profile\"], \"openid profile email\", \"openid profile email groups\"]\n },\n \"claims\": {\n \"type\": \"object\",\n \"properties\": {\n \"email\": { \"type\": \"string\" },\n \"name\": { \"type\": \"string\" },\n \"uuid\": { \"type\": \"string\" }\n }\n },\n \"preset\": { \"type\": \"string\", \"enum\": [\"azure\", \"google\"]},\n \"tenant_id\": { \"type\": \"string\", \"description\": \"REQUIRED FOR AZURE PRESET: Tenantid for Azure\"},\n \"customer_id\": { \"type\": \"string\", \"description\": \"REQUIRED FOR GOOGLE PRESET IF USING GROUPS: Customer ID from Google, should start with 'C'.\"}\n },\n \"additionalProperties\": false\n},\nThe 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.
"},{"location":"meshcentral/openidConnectStrategy/#common-config-chart_2","title":"Common Config Chart","text":"Name Description Default Example Requiredsync 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 memberof at least one of the listed required groups. undefined \"required\": [\"Group1\", \"Group2\"] false siteadmin Full site admin priviledges will be granted to userswho 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 userswho arent a member of at least one of the listed admin groups. true \"revokeAdmin\": false false"},{"location":"meshcentral/openidConnectStrategy/#advanced-config-example_3","title":"Advanced Config Example","text":"\"groups\": {\n \"recursive\": true,\n \"required\": [\"Group1\", \"Group2\"],\n \"siteadmin\": [\"GroupA\", \"GroupB\"],\n \"revokeAdmin\": false,\n \"sync\": { \n \"filter\": [\"Group1\", \"GroupB\", \"OtherGroup\"]\n },\n \"claim\": \"GroupClaim\",\n \"scope\": \"read.GroupMemberships\"\n},\nAs 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.
"},{"location":"meshcentral/openidConnectStrategy/#schema_3","title":"Schema","text":"\"groups\": {\n \"type\": \"object\",\n \"properties\": {\n \"recursive\": {\n \"type\": \"boolean\",\n \"default\": false,\n \"description\": \"When true, the group memberships will be scanned recursively.\"\n },\n \"required\": {\n \"type\": [ \"string\", \"array\" ],\n \"description\": \"Access is only granted to users who are a member of at least one of the listed required groups.\"\n },\n \"siteadmin\": {\n \"type\": [ \"string\", \"array\" ],\n \"description\": \"Full site admin priviledges will be granted to users who are a member of at least one of the listed admin groups.\"\n },\n \"revokeAdmin\": {\n \"type\": \"boolean\",\n \"default\": false,\n \"description\": \"If true, admin privileges will be revoked from users who are NOT a member of at least one of the listed admin groups.\"\n },\n \"sync\": {\n \"type\": [ \"boolean\", \"object\" ],\n \"default\": false,\n \"description\": \"If true, all groups found during user login are mirrored into MeshCentral user groups.\",\n \"properties\": {\n \"filter\": {\n \"type\": [ \"string\", \"array\" ],\n \"description\": \"Only groups listed here are mirrored into MeshCentral user groups.\"\n }\n }\n },\n \"scope\": { \"type\": \"string\", \"default\": \"groups\", \"description\": \"Custom scope to use.\" },\n \"claim\": { \"type\": \"string\", \"default\": \"groups\", \"description\": \"Custom claim to use.\" }\n },\n \"additionalProperties\": false\n}\nGoogle is a blah and is used by tons of blahs as its so great. Lets move on.
"},{"location":"meshcentral/openidConnectStrategy/#common-config-chart_3","title":"Common Config Chart","text":"NOTE: All settings directly related to presets are in the custom section of the config.
Name Description Example Requiredpreset Manually enable the use of a preset. \"preset\": \"google\"\"preset\": \"azure\" false customer_id Customer ID of the Google Workspaces instace youplan 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 usethe azure preset as it is part of the issuer url. \"siteadmin\": [\"Group1\", \"Group2\"] false"},{"location":"meshcentral/openidConnectStrategy/#google-preset","title":"Google Preset","text":""},{"location":"meshcentral/openidConnectStrategy/#prerequisites","title":"Prerequisites","text":"Check out this documentation to get ready before we start.
"},{"location":"meshcentral/openidConnectStrategy/#basic-config-example","title":"Basic Config Example","text":"\"oidc\": {\n \"client\": {\n \"client_id\": \"268438852161-r8xa7qxwf3rr0shp1xnpgmm70bnag21p.apps.googleusercontent.com\",\n \"client_secret\": \"ETFWBX-gFEaxfPXs1tWmAOkuWDFTgoL3nwh\"\n }\n}\nIf 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.
"},{"location":"meshcentral/openidConnectStrategy/#advanced-example-with-groups","title":"Advanced Example with Groups","text":"\"oidc\": {\n \"client\": {\n \"client_id\": \"424555768625-k7ub3ovqs0yp7mfo0usvyyx51nfii61c.apps.googleusercontent.com\",\n \"client_secret\": \"QLBCQY-nRYmjnFWv3nKyHGmwQEGLokP6ldk\"\n },\n \"custom\": {\n \"preset\": \"google\",\n \"customer_id\": \"C46kyhmps\"\n },\n \"groups\": {\n \"siteadmin\": [\"GroupA\", \"GroupB\"],\n \"revokeAdmin\": true,\n \"sync\": true\n },\n \"callbackURL\": \"https://mesh.your.domain/auth-oidc-google-callback\"\n},\nAs 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.
"},{"location":"meshcentral/openidConnectStrategy/#schema_4","title":"Schema","text":"\"custom\": {\n \"type\": \"object\",\n \"properties\": {\n \"preset\": { \"type\": \"string\", \"enum\": [\"azure\", \"google\"]},\n \"customer_id\": { \"type\": \"string\", \"description\": \"Customer ID from Google, should start with 'C'.\"}\n },\n \"additionalProperties\": false\n},\nTo 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.
"},{"location":"meshcentral/openidConnectStrategy/#basic-config-example_1","title":"Basic Config Example","text":"\"oidc\": {\n \"client\": {\n \"client_id\": \"a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r\",\n \"client_secret\": \"AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O\"\n },\n \"custom\": {\n \"preset\": \"azure\",\n \"tenant_id\": \"46a6022g-4h33-1451-h1rc-08102ga3b5e4\"\n }\n}\nAs 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\"
\"oidc\": {\n \"client\": {\n \"client_id\": \"a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r\",\n \"client_secret\": \"AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O\"\n },\n \"custom\": {\n \"preset\": \"azure\",\n \"tenant_id\": \"46a6022g-4h33-1451-h1rc-08102ga3b5e4\"\n },\n \"groups\": {\n \"recursive\": true,\n \"siteadmin\": [\"GroupA\", \"GroupB\"],\n \"revokeAdmin\": true,\n \"sync\": true\n },\n \"callbackURL\": \"https://mesh.your.domain/auth-oidc-azure-callback\"\n},\n\"custom\": {\n \"type\": \"object\",\n \"properties\": {\n \"preset\": { \"type\": \"string\", \"enum\": [\"azure\", \"google\"]},\n \"tenant_id\": { \"type\": \"string\", \"description\": \"Tenant ID from Azure AD.\"}\n },\n \"additionalProperties\": false\n},\nAs 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.
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.
\"oidc\": {\n \"newAccounts\": true,\n \"clientid\": \"421326444155-i1tt4bsmk3jm7dri6jldekl86rfpg07r.apps.googleusercontent.com\",\n \"clientsecret\": \"GNLXOL-kEDjufOCk6pIcTHtaHFOCgbT4hoi\"\n}\nThis 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.
\"oidc\": {\n \"authorizationURL\": \"https://sso.your.domain/api/oidc/authorization\",\n \"callbackURL\": \"https://mesh.your.domain/oauth2/oidc/callback\",\n \"clientid\": \"tZiPTMDNuSaQPapAQJtwDXVnYjjhQybc\",\n \"clientsecret\": \"vrQWspJxdVAxEFJdrxvxeQwWkooVcqdU\",\n \"issuer\": \"https://sso.your.domain\",\n \"tokenURL\": \"https://sso.your.domain/api/oidc/token\",\n \"userInfoURL\": \"https://sso.your.domain/api/oidc/userinfo\",\n \"logoutURL\": \"https://sso.your.domain/logout?rd=https://mesh.your.domain/login\",\n \"groups\": {\n \"recursive\": true,\n \"required\": [\"Group1\", \"Group2\"],\n \"siteadmin\": [\"GroupA\", \"GroupB\"],\n \"sync\": { \n \"filter\": [\"Group1\", \"GroupB\", \"OtherGroup\"]\n }\n },\n \"newAccounts\": true\n},\nIf 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.
"},{"location":"meshcentral/openidConnectStrategy/#links","title":"Links","text":"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
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!
"},{"location":"meshcentral/plugins/#use-cases","title":"Use Cases","text":"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.
"},{"location":"meshcentral/plugins/#list-of-publically-available-plugins","title":"List of publically available plugins","text":"https://github.com/topics/meshcentral-plugin
"},{"location":"meshcentral/plugins/#installation-of-a-plugin","title":"Installation of a plugin","text":"\"plugins\": { \"enabled\": true },
My Server -> Plugins, then hit the Download plugin button.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!
"},{"location":"meshcentral/plugins/#overview","title":"Overview","text":"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.
"},{"location":"meshcentral/plugins/#anatomy-of-a-plugin","title":"Anatomy of a plugin:","text":"- plugin_name/\n-- config.json\n-- plugin_name.js\n-- modules_meshcore/ // optional\n--- plugin_name.js // optional\nA valid JSON object within a file named config.json in the root folder of your project. An example:
{\n \"name\": \"Plugin Name\",\n \"shortName\": \"plugin_name\",\n \"version\": \"0.0.0\",\n \"author\": \"Author Name\",\n \"description\": \"Short Description of the plugin\",\n \"hasAdminPanel\": false,\n \"homepage\": \"https://www.example.com\",\n \"changelogUrl\": \"https://raw.githubusercontent.com/User/Project/master/changelog.md\",\n \"configUrl\": \"https://raw.githubusercontent.com/User/Project/master/config.json\",\n \"downloadUrl\": \"https://github.com/User/Project/archive/master.zip\",\n \"repository\": {\n \"type\": \"git\",\n \"url\": \"https://github.com/User/Project.git\"\n },\n \"versionHistoryUrl\": \"https://api.github.com/repos/User/Project/tags\",\n \"meshCentralCompat\": \">0.4.3\"\n}\ntrue 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."},{"location":"meshcentral/plugins/#plugin-hooks","title":"Plugin Hooks","text":"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.
onDeviceRefreshEnd: called when a device is selected in the MeshCentral web interfaceregisterPluginTab: 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 useonDesktopDisconnect: called when a remote desktop session is disconnectedonWebUIStartupEnd: called when the page has loaded for the first time after a login / refreshgoPageStart: called before page changes take effect. Passes 2 arguments ( : int, : Event) goPageEnd: called after page changes take effect. Passes 2 arguments ( : int, : Event)"},{"location":"meshcentral/plugins/#exports","title":"Exports","text":"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.
server_startup: called once when the server starts (or when the plugin is first installed)hook_agentCoreIsStable: called once when an agent initially checks inhook_processAgentData: called each time an agent transmits data back to the serverhook_userLoggedIn: called when a user has logged into the web interfacehook_setupHttpHandlers: called before all http handlers are setupUse 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.
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.
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.
"},{"location":"meshcentral/plugins/#changelog","title":"Changelog","text":"A changelog is highly recommended so that your users know what's changed since their last version.
"},{"location":"meshcentral/plugins/#sample-plugin","title":"Sample Plugin","text":"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.
"},{"location":"meshcentral/security/","title":"Security","text":""},{"location":"meshcentral/security/#rate-limiting-login-attempts","title":"Rate Limiting login attempts","text":"You can use the MeshCentral Server Console with the command badlogins to see the current settings.
Adjust these items in your config.json
\"settings\": {\n \"_maxInvalidLogin\": {\n \"time\": 10,\n \"count\": 10,\n \"coolofftime\": 10\n },\n}\n{\n \"settings\": {\n \"mpshighsecurity\": true\n }\n}\nThe SSH terminal does support color. The issue is going to be the terminal configuration of the shell. Try typing this:
ls -al --color /tmp\nA 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.
{\n \"$schema\": \"https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json\",\n \"settings\": {\n \"your settings go here\": \"...\"\n }\n}\nNow 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.
"},{"location":"meshcentral/tipsntricks/#downloading-folders","title":"Downloading Folders","text":"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.
"},{"location":"meshcentral/tipsntricks/#share-device-groups-with-ad-logins","title":"Share device groups with AD logins","text":"If you would like to share device groups with different AD users.
In the config.json set \"ldapuserkey\" to \"sAMAccountName\".
"},{"location":"meshcentral/tokens/","title":"14.1 Tokens","text":""},{"location":"meshcentral/tokens/#user-tokens","title":"User Tokens","text":""},{"location":"meshcentral/tokens/#software-integration-tokens","title":"Software Integration Tokens","text":"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\nYou can then reset/revoke/renew the Login Token Key with the following to create a new one:
node node_modules/meshcentral --loginTokenKey --loginTokenGen\nMeshCmd Guide as .pdf as .odt
"},{"location":"meshcmd/#video-walkthru","title":"Video Walkthru","text":""},{"location":"meshcmd/#abstract","title":"Abstract","text":"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\u00ae 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.
"},{"location":"meshcmd/#introduction","title":"Introduction","text":"MeshCmd, called \u201cMesh Command\u201d, 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 \u201cMeshCmd\u201d 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\nMeshCentral Command (MeshCmd)\nNo action specified, use MeshCmd like this:\n\n meshcmd [action] [arguments...]\n\nValid MeshCentral actions:\n Route - Map a local TCP port to a remote computer.\n\nValid local actions:\n SMBios - Display System Management BIOS tables for this computer.\n RawSMBios - Display RAW System Management BIOS tables for this computer.\n MicroLMS - Run MicroLMS, allowing local access to Intel AMT.\n AmtInfo - Show Intel AMT version and activation state.\n AmtVersions - Show all Intel ME version information.\n AmtHashes - Show all Intel AMT trusted activation hashes.\n AmtCCM - Activate Intel AMT into Client Control Mode.\n AmtACM - Activate Intel AMT into Admin Control Mode.\n AmtDeactivate - Deactivate Intel AMT if activated in Client Control mode.\n AmtAcmDeactivate - Deactivate Intel AMT if activated in Admin Control mode.\n\nValid local or remote actions:\n MeshCommander - Launch a local MeshCommander web server.\n AmtUUID - Show Intel AMT unique identifier.\n AmtAuditLog - Show the Intel AMT audit log.\n AmtLoadWebApp - Load MeshCommander in Intel AMT 11.6+ firmware.\n AmtClearWebApp - Clear everything from Intel AMT web storage.\n AmtStorageState - Show contents of the Intel AMT web storage.\n AmtSaveState - Save all Intel AMT WSMAN object to file.\n AmtPresence - Heartbeat a local Intel AMT watchdog agent.\n AmtScript - Run .mescript on Intel AMT.\n AmtIDER - Mount local disk image to remote computer.\n\nHelp on a specific action using:\n\n meshcmd help [action]\nBy 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 \u201chelp\u201d followed by the action name. In this document we will cover the main actions that MeshCmd can perform. If you don\u2019t 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.
"},{"location":"meshcmd/#meshcentral-tcp-port-mapping","title":"MeshCentral TCP port mapping","text":"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 \u201clocalhost:1234\u201d 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 \u201cRouter\u201d 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:
{\n \"action\": \"route\",\n \"localPort\": 1234, \uf0df Change this\n \"remoteName\": \"AmtMachine7\",\n \"remoteNodeId\": \"node//@yw$s5jLUivpzZ49laprt4T0sBaOKImbDAiniothQwccZPukCB696$BvPWAW0Bg2\",\n \"remotePort\": 3389, \uf0df Change this\n \"username\": \"admin\",\n \"password\": \"\", \uf0df Note that the password is empty\n \"serverId\": \"D99362D5ED8BAEA8BF9E743B34B242256370C460FD66CB62373C6CFCB204D6D70\n7403E396CF0EF6DC2B3A42F735135FD\",\n \"serverHttpsHash\": \"D9DE9E27A229B5355708A3672FB23237CC994A680B3570D242A91E36B4AE5BC\n96539E59746E2B71EEF3DBDABBF2AE138\",\n \"debugLevel\": 0,\n \"serverUrl\": \"wss://devbox.mesh.meshcentral.com:443/meshrelay.ashx\"\n}\nThe 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. Be 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 \nRedirecting local port 1234 to AmtMachine7:3389. Press ctrl-c to exit. \nNow, the traffic router is ready. You can now RDP to localhost:1234 and login to the remote computer. \nMeshCommander 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\u2019s worth a moment to get some knowledge about MeshCommander which is available as a standalone tool along with a full user\u2019s guide at:http://www.meshcommander.com/and also included as part of MeshCentral.
The three versions included in MeshCmd are:
In this section, we review the three versions, how they are used and what can be done with them.
"},{"location":"meshcmd/#meshcommander-local-web-server","title":"MeshCommander local web server","text":"You can start MeshCommander on a local web server by typing \u201cmeshcmd meshcommander\u201d. By default, local port 3000 is used, but you can optionally specify the port using \u201c--localport [port]\u201d. Running it with look like this:
C:\\MeshCmd>meshcmd meshcommander\nMeshCommander running on HTTP port 3000. Ctrl-C to exit. \nOnce running, use a web browser and go to \u201chttp://localhost:3000\u201d 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\u2019s storage cache. So, clearing the browser\u2019s cache will also clear the list of computers. You can however load and save the list of computers using the \u201cOpen\u2026\u201d and \u201cSave\u2026\u201d buttons. This version of MeshCommander will have some limitations when compared to the full version installed using the Windows .MSI installer. Notably:
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\nInstalling to \"C:\\Program Files (x86)\\Open Source\\MeshCmd\\MeshCommander.exe\" MeshCommander installed. \n\nC:\\MeshCmd>meshcmd meshcommander start\nMeshCommander starting.\nOn Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.
"},{"location":"meshcmd/#lms-meshcommander","title":"LMS & MeshCommander","text":"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 tryhttp://localhost:16992 or https://localhost:16993in a browser. A page should generally show up.
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\u2019s 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\nMicroLMS started, MeshCommander on HTTP/16994. \nThis 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\u2019s 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 \u201c--noconsole\":
C:\\MeshCmd>meshcmd microlms --noconsole\nMicroLMS started. \nYou 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\nInstalling to \"C:\\Program Files (x86)\\Open Source\\MeshCmd\\MicroLMS.exe\" \nMicroLMS installed. \n\nC:\\MeshCmd>meshcmd microlms start\nMicroLMS starting. \nOn Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.
"},{"location":"meshcmd/#meshcommander-for-firmware","title":"MeshCommander for firmware","text":"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\u2019s 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\nUploading MeshCommander...\nVerifying MeshCommander...\nDone.\nTo get the current state of Intel AMT web storage, type this:
C:\\MeshCmd>meshcmd amtstoragestate --host 192.168.2.144 --pass xxxxxxxx\nStorage State: {\n \"information\": {\n \"version\": 1,\n \"realms\": 7765759,\n \"user\": \"admin\"\n },\n \"content\": {\n \"index.htm\": {\n \"size\": 57246 \uf0df Replacement index.htm with size.\n }\n }\n}\nHere, 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\nDone.\nWhen MeshCommander is loaded into Intel AMT, you can access it from a different computer using http://computername:16992 orhttps://computername:16993 You will need to authenticate first before getting access to the web page.
"},{"location":"meshcmd/#intel-amt-state-activation","title":"Intel AMT state & activation","text":"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 \u201cSMBios\u201d 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\n{\n processorInfo: {\n 0: {\n Processor: \"CPU\"\n MaxSpeed: \"3800 Mhz\"\n Cores: 4\n Threads: 8\n Populated: 1\n Status: \"Enabled\"\n Socket: \"CPU 1\"\n Manufacturer: \"Intel(R) Corporation\"\n Version: \"Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz\"\n }\n }\n memoryInfo: {\n location: \"System Board\"\n maxCapacityKb: 33554432\n }\n systemInfo: {\n uuid: \"C57B83D9A94E11E18BA1505054503030\"\n wakeReason: \"Power Switch\"\n }\n systemSlots: {\n uuid: \"C57B83D9A94E11E18BA1505054503030\"\n wakeReason: \"Power Switch\"\n }\n amtInfo: {\n AMT: true\n enabled: true\n storageRedirection: true\n serialOverLan: true\n kvm: true\n TXT: false\n VMX: true\n MEBX: \"66.0.0.8\"\n ManagementEngine: \"8.1.0.57353\"\n }\n}\nIf you have Intel AMT on your system, you can use the \u201camtinfo\u201d, \u201camtversions\u201d and \u201camthashes\u201d 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:
C:\\MeshCmd>meshcmd amtinfo\nIntel AMT v8.1.71, activated in client control mode.\nWired Enabled, DHCP, 00:1E:8C:F5:4F:ED, 192.168.2.10.\n\nC:\\MeshCmd>meshcmd amtversions\nMEI Version = MKQ7710H.86A.0072.2017.0519.1347\nFlash = 8.1.71\nNetstack = 8.1.71\nAMTApps = 8.1.71\nAMT = 8.1.71\nSku = 24584\nVendorID = 8086\nBuild Number = 3608\nRecovery Version = 8.1.71\nRecovery Build Num = 3608\nLegacy Mode = False\n\nC:\\MeshCmd>meshcmd amthashes\nVeriSign Class 3 Primary CA-G1, (Default, Active)\n SHA256: E7685634EFACF69ACE939A6B255B7B4FABEF42935B50A265ACB5CB6027E44E70\nVeriSign Class 3 Primary CA-G3, (Default, Active)\n SHA256: EB04CF5EB1F39AFA762F2BB120F296CBA520C1B97DB1589565B81CB9A17B7244\n\u2026\nIn addition to getting Intel AMT state, MeshCmd can activate Intel AMT in client control mode (CCM) and de-activate Intel AMT if it\u2019s in this mode. Doing this is very simple, starting with Intel AMT not being activated, you use the \u201camtccm\u201d and \u201camtdeactivate\u201d actions.
C:\\MeshCmd>meshcmd amtinfo\nIntel AMT v8.1.71, pre-provisioning state.\n\nC:\\MeshCmd>meshcmd amtccm --pass xxxxxxxx\nSuccess\n\nC:\\MeshCmd>meshcmd amtinfo\nIntel AMT v8.1.71, activated in client control mode.\n\nC:\\MeshCmd>meshcmd amtdeactivate\nSuccess\nNote that when using the \u201camtccm\u201d 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.
"},{"location":"meshcmd/#intel-amt-audit-log","title":"Intel AMT Audit Log","text":"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\u2019s 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\u2019s Intel AMT was activated, when remote desktop sessions where initiated and more. To get the local audit log, just use the \u201cAmtAuditLog\u201d action.
C:\\MeshCmd>meshcmd amtauditlog\n2004-01-01 19:17:58.000-08:00 - Local: Provisioning Started\n2018-01-26 14:03:16.000-08:00 - Local: Unprovisioning Started\n2018-01-26 14:03:31.000-08:00 - Local: Provisioning Started\n2018-02-01 12:13:14.000-08:00 - admin: KVM Enabled\n2018-02-01 12:16:01.000-08:00 - admin: KVM Session Started\n2018-02-01 12:16:07.000-08:00 - admin: KVM Session Ended\n2018-02-02 10:56:06.000-08:00 - admin: KVM Session Started\n2018-02-02 10:56:08.000-08:00 - admin: KVM Session Ended\nTo get a remote audit log:
C:\\MeshCmd>meshcmd amtauditlog --host 192.168.2.144 --user admin --pass xxxxxxxx\n2003-12-31 23:06:58.000-08:00 - $$OsAdmin: Intel(r) ME Time Set\n2017-08-15 06:53:31.000-07:00 - $$OsAdmin: Intel(r) ME Time Set\n2017-10-13 17:55:11.000-07:00 - Local: Provisioning Started\n2017-10-13 17:55:54.000-07:00 - Local: Opt-In Policy Change\n2017-10-15 06:44:38.000-07:00 - admin: KVM Enabled\nYou can also save the audit log to file using the \u201c--output\" option.
"},{"location":"meshcmd/#running-intel-amt-script","title":"Running Intel AMT script","text":"MeshCmd has a full WSMAN stack built-in and can be used to run \u201c.mescript\u201d 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 \u201cAdd CIRA\u201d 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\u2019s not localhost, the password and the script file.
C:\\MeshCmd>meshcmd amtscript --host 192.168.2.106 --pass xxxxxxxx --script cira_setup.mescript\nScript Started\nPolicies removed successfully\nAdding root certificate...\nManagement Presence Server (MPS) successfully added\nFound matching (primary) mps: Intel(r) AMT:Management Presence Server 0\nSetting policy...\nPolicy added successfully\nRemote Access user interfaces set to: BIOS & OS Enabed\nParsing block parameters\nSetting Environment Detection\nEnvironment Detection set successfully\nScript Completed\nIn 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.
"},{"location":"meshcmd/#ide-redirection","title":"IDE Redirection","text":""},{"location":"meshcmd/#video-walkthru_1","title":"Video Walkthru","text":"MeshCmd has all the code needed to perform Intel AMT IDE Redirection from the command line. This allows disk images on the administrator\u2019s 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 \u201cAmtIDER\u201d command of MeshCMD to start an IDER session. The help command for AmtIDER looks like this:
C:\\Temp>meshcmd help amtider\nAmtIDER will mount a local disk images to a remote Intel AMT computer. Example usage:\n\n meshcmd amtider --host 1.2.3.4 --user admin --pass mypassword --tls --floppy disk.img --cdrom disk.iso\n\nPossible arguments:\n\n --host [hostname] The IP address or DNS name of Intel AMT.\n --user [username] The Intel AMT login username, admin is default.\n --pass [password] The Intel AMT login password.\n --tls Specifies that TLS must be used.\n --floppy [file] Specifies .img file to be mounted as a flppy disk.\n --cdrom [file] Specifies .img file to be mounted as a CDROM disk.\n --timeout [seconds] Optional, disconnect after number of seconds without disk read.\nThe 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.
"},{"location":"meshcmd/#conclusion","title":"Conclusion","text":"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.
"},{"location":"meshcmd/#license","title":"License","text":"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
"},{"location":"meshctrl/","title":"MeshCtrl","text":"MeshCmd Guide as .pdf as .odt
"},{"location":"meshctrl/#video-walkthru","title":"Video Walkthru","text":""},{"location":"meshctrl/#abstract","title":"Abstract","text":"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\u2019s typically used by administrators to perform various management operations on the MeshCentral server.
"},{"location":"meshctrl/#introduction","title":"Introduction","text":"MeshCtrl, also called \u201cMesh Control\u201d, 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\u2019s 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.
"},{"location":"meshctrl/#running-meshctrl","title":"Running MeshCtrl","text":"MeshCtrl.js is a file that is installed with MeshCentral and is located in the \u201c./node_modules/meshcentral\u201d folder. You can normally run MeshCtrl like this:
node ./node\\_modules/meshcentral/meshctrl \nIn 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.\nInformation at: https://meshcommander.com/meshcentral\nNo action specified, use MeshCtrl like this:\n\n meshctrl [action] [arguments]\n\nSupported actions:\n Help [action] - Get help on an action.\n ServerInfo - Show server information.\n UserInfo - Show user information.\n ListUsers - List user accounts.\n ListDevices - List devices.\n ListDeviceGroups - List device groups.\n ListUsersOfDeviceGroup - List the users in a device group.\n AddUser - Create a new user account.\n RemoveUser - Delete a user account.\n AddDeviceGroup - Create a new device group.\n RemoveDeviceGroup - Delete a device group.\n AddUserToDeviceGroup - Add a user to a device group.\n RemoveUserFromDeviceGroup - Remove a user from a device group.\n SendInviteEmail - Send an agent install invitation email.\n Broadcast - Display a message to all online users.\n\nSupported login arguments:\n --url [wss://server] - Server url, wss://localhost:443 is default.\n --loginuser [username] - Login username, admin is default.\n --loginpass [password] - Login password.\n --token [number] - 2nd factor authentication token.\n --loginkey [hex] - Server login key in hex.\n --loginkeyfile [file] - File containing server login key in hex.\n --domain [domainid] - Domain id, default is empty.\nThis 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.
"},{"location":"meshctrl/#login","title":"Login","text":"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.
"},{"location":"meshctrl/#login-using-username-password","title":"Login using username & password","text":"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\"\nIn this example we are trying to run the \u201cserverinfo\u201d command using the \u201cadmin\u201d user and \u201cmypassword\u201d as the password. Because \u201cadmin\u201d if the default username for MeshCtrl, you can omit it and just type:
Authentication token required, use --token [number].\nIn 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\" \u2013token 123456\nOnce the command is run successfully, you should see a response like this:
name: devbox.meshcentral.com\nmpsname: devbox.meshcentral.com\nmpsport: 4433\nport: 443\nemailcheck: true\ndomainauth: false\ntlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1\u2026\nhttps: true\nredirport: 80\nThis is a typical response for the \u201cserverinfo\u201d command and a good way to test that everything is working as expected.
"},{"location":"meshctrl/#login-using-the-server-login-key","title":"Login using the server login key","text":"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\u2019s 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 \u201cAllowLoginToken\u201d to \u201ctrue\u201d in the \u201csettings\u201d section of config.json:
{\n \"settings\": {\n \"Port\": 443,\n \"AllowLoginToken\": true\n }\n}\nThen run the MeshCentral server with the --logintokenkey parameter, you should see something like this:
node ./node_modules/meshcentral --logintokenkey\nf3bd69a08a2dde4a3423bec8f20d8626b1e6365381f2d9919e7dfe256ace9cbbdea66bed2bdcd00b71eea9d7c727cb6eb37f3148c0c2d240d5ed44c8f3f6795a479c949159dad366571fea4db7f31c24\nThe 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 \u201ckey.txt\u201d, you can do it like this:
node ./node_modules/meshcentral \u2013logintokenkey > key.txt\nNow that you have the server key, you can use MeshCtrl like this:
node ./node_modules/meshcentral/meshctrl serverinfo \u2013-loginkeyfile key.txt --loginuser admin\nInstead of using a password, we use the key file instead. MeshCtrl will generate a time limited cookie and use that to login as \u201cadmin\u201d. Since \u201cadmin\u201d is the default username for MeshCtrl, we can omit this parameter:
node ./node_modules/meshcentral/meshctrl serverinfo \u2013-loginkeyfile key.txt\nLike the username and password example above, the result will be the server information we requested. Something like this:
name: devbox.meshcentral.com\nmpsname: devbox.meshcentral.com\nmpsport: 4433\nport: 443\nemailcheck: true\ndomainauth: false\ntlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1\u2026\nhttps: true\nredirport: 80\nSo 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\"\nor for servers have a DNS name for a domain:
node ./node_modules/meshcentral/meshctrl serverinfo --url wss://domainname.server --loginuser \"admin\" --loginpass \"mypassword\"\nNote 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 \u2013-loginkeyfile key.txt --url wss://server/domainname --domain mycustomer\nSo, 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:
{\n \"settings\": {\n \"Cert\": \"myserver.com\",\n \"Port\": 443\n },\n \"domains\": {\n \"\": {\n \"title\": \"Default domain\",\n },\n \"customer1\": {\n \"dns\": \"c1.myserver.com\",\n \"title\": \"Customer1 domain\",\n }\n }\n}\nThe domain login for MeshCtrl with a key file would look like this:
node ./node_modules/meshcentral/meshctrl serverinfo \u2013-loginkeyfile key.txt --url wss://c1.myserver.com --domain customer1\nIn 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.
"},{"location":"meshctrl/#making-use-of-meshctrl","title":"Making use of MeshCtrl","text":"We can start doing useful operations with MeshCtrl. The current list of operations are:
edituser\nlistusers\nlistusersessions\nlistdevicegroups\nlistdevices\nlistusersofdevicegroup\nlistevents\nlogintokens\nserverinfo\nuserinfo\nadduser\nremoveuser\nadddevicegroup\nremovedevicegroup\neditdevicegroup\nbroadcast\nshowevents\naddusertodevicegroup\nremoveuserfromdevicegroup\naddusertodevice\nremoveuserfromdevice\nsendinviteemail\ngenerateinvitelink\nconfig\nmovetodevicegroup\ndeviceinfo\neditdevice\naddusergroup\nlistusergroups\nremoveusergroup\nruncommand\nshell\nupload\ndownload\ndeviceopenurl\ndevicemessage\ndevicetoast\naddtousergroup\nremovefromusergroup\nremoveallusersfromusergroup\ndevicesharing\ndevicepower\nindexagenterrorlog\nagentdownload\nreport\nYou can get this list by just running MeshCtrl without any argument and can get more information on each action by typing \u201cmeshctrl help [action]\u201d
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\".
"},{"location":"meshctrl/#gathering-information","title":"Gathering information","text":"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 \u201c--json\" to receive the response in JSON format. For example, getting the list of users will look like this:
node meshctrl.js listusers\nid, name, email\n---------------\n\"admin\", \"admin\", \"username@domain.com\"\n\"joe\", \"joe\", \"joe@domain.com\"\n\"mytestuser\", \"MyTestUser\", \"a@a.com\"\n\"test.user\", \"test.user\", \"test.user@user.com\"\nIn the --json argument is used, it looks like this:
node meshctrl.js listusers --json\n {\n \"_id\": \"user//admin\",\n \"name\": \"admin\",\n \"creation\": 1417814230,\n \"siteadmin\": 4294967295,\n \u2026\nThe 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 \u201clistdevices\u201d that just displays all the devices in the account grouped by device groups. For example:
node meshctrl listdevices\n\nDevice group: \"Lab Computers\"\nid, name, icon, conn, pwr, ip\n-----------------------------\np3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, \"raspberrypi\", 5, 1, 1\nyjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, \"tinkerboard\", 5, 1, 1\nDRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, \"LattePanda\", 5, 1, 1\nggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, \"MeshLabTop\", 1, 5, 1\nECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, \"MeshLabRight\", 1, 1, 1\nfCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, \"DevLinux\", 1, 1, 1\nhfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, \"AmtMachine11\", 1, 1, 1\nYRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, \"CoffeeTable\", 1, 1, 1\nPpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, \"DevBox\", 1, 0, 0\ntyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, \"MeshLabLeft\", 1, 5, 1\ni@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, \"raspberrypi\", 5, 1, 1\n2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, \"AmtMachine7\", 1, 5, 1\n0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, \"RaspberryPi\", 5, 1, 1\n\nDevice group: \"IntelAMT only\"\nid, name, icon, conn, pwr, ip\n-----------------------------\nLN8qsH634RGjDwATIOd3ICzfKrB@t@ERow8AEyDndyAs3yqwfrfhEaMPABMg53cg, \"AmtMachine7\", 0, 0, 0\nEa3GcF$EoMnDEc9Tbz$Vu9wnmTziqqcOZ0URSdYeuVn4LU9LLMT@91P5s1WLSgVA, \"DevBox\", 0, 0, 0\nIt\u2019s 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 \u201cDeisplayDeviceGroups\u201d command. For example:
node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055\u2026\n\nid, name, icon, conn, pwr, ip\n-----------------------------\np3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, \"raspberrypi\", 5, 1, 1\nyjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, \"tinkerboard\", 5, 1, 1\nDRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, \"LattePanda\", 5, 1, 1\nggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, \"MeshLabTop\", 1, 5, 1\nECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, \"MeshLabRight\", 1, 1, 1\nfCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, \"DevLinux\", 1, 1, 1\nhfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, \"AmtMachine11\", 1, 1, 1\nYRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, \"CoffeeTable\", 1, 1, 1\nPpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, \"DevBox\", 1, 0, 0\ntyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, \"MeshLabLeft\", 1, 5, 1\ni@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, \"raspberrypi\", 5, 1, 1\n2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, \"AmtMachine7\", 1, 5, 1\n0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, \"RaspberryPi\", 5, 1, 1\nYou can also add \u201c--count\" to just return the number of devices instead of displaying them. An example of this would be:
node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055\u2026 --count\n13\nHere we see that in a specific device group, there are 13 devices.
"},{"location":"meshctrl/#adding-and-removing-accounts","title":"Adding and removing accounts","text":"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 \u201cMy Users\u201d tab and press \u201cNew Account\u2026\u201d 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 \nThis will create a basic user account with the specified \u201cSampleUser\u201d username and \u201cSamplePassword\u201d 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.\n--emailverified - New account email is verified.\n--resetpass - Request password reset on next login.\n--siteadmin - Create the account as full site administrator.\n--manageusers - Allow this account to manage server users.\n--fileaccess - Allow this account to store server files.\n--serverupdate - Allow this account to update the server.\n--locked - This account will be locked.\n--nonewgroups - Account will not be allowed to create device groups\n--notools - Account not see MeshCMD download links.\nInstead of specifying a password, one can specify \u201c--randompass\" to have MeshCtrl generate a random password, this is typically use along with \u201c--resetpass\" and \u201c--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 \u201c-- 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\nNote 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\u2019s by using the \u201cListUsers\u201d command.
MeshCtrl will return \u201cok\u201d if the command is successful and the account will be added in real-time to the \u201cMy Users\u201d tab on the website.
"},{"location":"meshctrl/#creating-and-removing-device-groups","title":"Creating and removing device groups","text":"MeshCtrl can be used to add and remove device groups. When a group is created, it\u2019s 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 \u201cAdd Device Group\u201d 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 \u201cAddDeviceGroup\u201d command like this:
node ./node_modules/meshcentral/meshctrl adddevicegroup --name \"Sample group name\" --desc \"Sample description\"\nHere 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 \u201cok\" and the group will be created in the logged in account in real-time.
You can delete a group by using the \u201cRemoveDeviceGroup\u201d command like this:
node ./node_modules/meshcentral/meshctrl removedevicegroup --id 7b4b43cd\u2026dc89fe0e581c\nTo 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.
"},{"location":"meshctrl/#adding-and-removing-users-from-device-groups","title":"Adding and removing users from device groups","text":"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 \u201clistusers\u201d and \u201clistdevicegroups\u201d commands. Then, you can for example do this:
node ./node_modules/meshcentral/meshctrl addusertodevicegroup --id 7b4b43cd\u2026dc89fe0e581c --userid bob --fullrights\nTypically, the group identifier is a long hex value. The command will add user \u201cbob\u201d 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.\n --editgroup - Allow the user to edit group information.\n --manageusers - Allow the user to add/remove users.\n --managedevices - Allow the user to edit device information.\n --remotecontrol - Allow device remote control operations.\n --agentconsole - Allow agent console operations.\n --serverfiles - Allow access to group server files.\n --wakedevices - Allow device wake operation.\n --notes - Allow editing of device notes.\n --desktopviewonly - Restrict user to view-only remote desktop.\n --limiteddesktop - Limit remote desktop keys.\n --noterminal - Hide the terminal tab from this user.\n --nofiles - Hide the files tab from this user.\n --noamt - Hide the Intel AMT tab from this user.\nNote that if \u201cfullrights\u201d are granted, all other access right arguments are ignored. If successful, MeshCtrl will display \u201cok\u201d, otherwise it will show an error message.
To remove a user from a group, use the \u201cremoveuserfromdevicegroup\u201d command. For example:
node ./node_modules/meshcentral/meshctrl removeuserfromdevicegroup --id 7b4b43cd\u2026dc89fe0e581c --userid bob\nThe syntax of this command is identical to the \u201caddusertodevicegroup\u201d command, but there are no rights arguments. MeshCtrl will also display \u201cok\u201d if the command got processed correctly.
"},{"location":"meshctrl/#message-broadcast","title":"Message Broadcast","text":"One fun command the MeshCtrl offers is the \u201cbroadcast\u201d 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\" \nAll connected users will see this:
The broadcast command is great for notifying users of upcoming server downtime or other events.
"},{"location":"meshctrl/#conclusion","title":"Conclusion","text":"MeshCtrl is an essential tools in every MeshCentral administrator\u2019s tool box. It allows administrators to automate various MeshCentral management tasks which can be useful for large scale management of many devices and users.
"},{"location":"meshctrl/#license","title":"License","text":"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
"},{"location":"meshrouter/","title":"MeshCentral Router","text":"MeshCentral Router Guide as .pdf as .odt
"},{"location":"meshrouter/#video-walkthru","title":"Video Walkthru","text":""},{"location":"meshrouter/#abstract","title":"Abstract","text":"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.
"},{"location":"meshrouter/#introduction","title":"Introduction","text":"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.
"},{"location":"meshrouter/#downloading","title":"Downloading","text":"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\u2019s 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:
The router link will only show up on Windows browsers.
"},{"location":"meshrouter/#login","title":"Login","text":"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.
If the second factor authentication is required, MeshCentral Router does not support hardware keys (WebAuthn), but does support the YubiKey\u2122 OTP.
"},{"location":"meshrouter/#creating-port-maps","title":"Creating Port Maps","text":"Once logged in, you can start adding port maps using the \u201cAdd Map\u2026\u201d and \u201cAdd Relay Map\u2026\u201d buttons on the bottom right. You can then create a map and open the associated application using the \u201cOpen\u2026\u201d button and remote to port map using the \u201cRemove\u201d button.
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.
A relay port map will route traffic thru the server and thru the remote agent to a target IP address on the remote agent\u2019s 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\u2019s recommended to use port mappings to tunnel data that is also encrypted for that end-to-end encryption is assured.
"},{"location":"meshrouter/#custom-apps","title":"Custom Apps","text":"Starting v1.0.21
"},{"location":"meshrouter/#command-line-arguments","title":"Command Line Arguments","text":"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\nCauses MeshCentral Router to generate a \u201cdebug.log\u201d dump file that can be useful for debugging.
-host:<hostname>\n-user:<username>\n-pass:<password>\n-ignorecert\nThis 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 \u201cignorecert\u201d argument is not recommended as it\u2019s going to cause MeshCentral Router to ignore untrusted server certificates. This should only be used for debugging.
-map:<protocol>:<localport>:<computername>:<app>:<remoteport>\nThe \u201cmap\u201d argument will automatically create a network map once MeshCentral Router is logged In. The protocol must be \u201cTCP\u201d or \u201cUDP, 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 \u201cHTTP\u201d, \u201cHTTPS\u201d, \u201cRDP\u201d, \u201cPuTTY\u201d or \u201cWinSCP\u201d. 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\n-map:UDP:1235:\"MyComputer\"::1234\nThe first example will map a random local port to port 80 of \u201cMyComputer\u201d and is expected for use with HTTP traffic. The second example maps local UDP port 1235 to port 1234 on \u201cMyComputer\u201d. It\u2019s 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>\n :<app>:<remoteip>:<remoteport>\nThis 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\nThis 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\nThe \u201call\u201d 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\nThe \u201ctray\u201d switch will place MeshCentral Router on the Windows system tray instead of the normal application bar.
"},{"location":"meshrouter/#meshcentral-router-with-saml-or-oauth","title":"MeshCentral Router with SAML or OAuth","text":"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
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.
"},{"location":"meshrouter/#conclusion","title":"Conclusion","text":"MeshCentral Router is a free, open source tool for routing TCP and UDP traffic over the internet. It\u2019s a powerful as it allows for any traffic to go thru NAT routers and firewalls while being encrypted using TLS.
"},{"location":"meshrouter/#license","title":"License","text":"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.
"},{"location":"messaging/","title":"Messaging","text":""},{"location":"messaging/#table-of-contents","title":"Table of Contents","text":"Introduction Telegram Setup Discord Setup XMPP Setup CallMeBot Setup Pushover Setup ntfy Setup Zulip Setup User Setup Administrator Management Two-Factor Authentication
"},{"location":"messaging/#introduction","title":"Introduction","text":"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.
"},{"location":"messaging/#telegram-setup","title":"Telegram Setup","text":"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:
{\n \"settings\": {\n \"Cert\": \"devbox.mesh.meshcentral.com\",\n },\n \"domains\": {\n \"\": {\n \"title\": \"My Server\"\n }\n },\n \"messaging\": {\n \"telegram\": {\n \"apiid\": 0,\n \"apihash\": \"00000000000000000000000\",\n \"bottoken\": \"00000000:aaaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n}\nNote the \"messaging\" section in the config.json. For Telegram user login, it looks like this:
{\n \"messaging\": {\n \"telegram\": {\n \"apiid\": 0,\n \"apihash\": \"00000000000000000000000\",\n \"session\": \"aaaaaaaaaaaaaaaaaaaaaaa\"\n }\n }\n}\nUser 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.\nMeshCentral v1.0.87, Hybrid (LAN + WAN) mode.\nMeshCentral Intel(R) AMT server running on central.mesh.meshcentral.com:4433.\nMeshCentral HTTPS server running on central.mesh.meshcentral.com:443.\nMeshCentral HTTPS relay server running on relay1.mesh.meshcentral.com:443.\nMeshCentral Telegram client is bot connected.\nNote 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.
{\n \"messaging\": {\n \"telegram\": {\n \"apiid\": 0,\n \"apihash\": \"00000000000000000000000\",\n \"session\": \"aaaaaaaaaaaaaaaaaaaaaaa\",\n \"useWSS\": false, // Important. Most proxies cannot use SSL.\n \"proxy\": {\n \"ip\": \"123.123.123.123\", // Proxy host (IP or hostname)\n \"port\": 123, // Proxy port\n \"MTProxy\": false, // Whether it's an MTProxy or a normal Socks one\n \"secret\": \"00000000000000000000000000000000\", // If used MTProxy then you need to provide a secret (or zeros).\n \"socksType\": 5, // If used Socks you can choose 4 or 5.\n \"timeout\": 2 // Timeout (in seconds) for connection,\n }\n }\n }\n}\nFor 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:
{\n \"messaging\": {\n \"discord\": {\n \"serverurl\": \"https://discord.gg/xxxxxxxxx\",\n \"token\": \"xxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx\"\n }\n }\n}\nOnce 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.
"},{"location":"messaging/#xmpp-setup","title":"XMPP Setup","text":"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.
{\n \"messaging\": {\n \"xmpp\": {\n \"service\": \"xmppserver.com\",\n \"credentials\": {\n \"username\": \"username\",\n \"password\": \"password\"\n }\n }\n }\n}\nAn 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.
"},{"location":"messaging/#callmebot-setup","title":"CallMeBot Setup","text":"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:
{\n \"messaging\": {\n \"callmebot\": true\n }\n}\nOnce 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.
"},{"location":"messaging/#pushover-setup","title":"Pushover Setup","text":"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:
{\n \"messaging\": {\n \"pushover\": {\n \"token\": \"xxxxxxxxxxxxxxxxxxxxx\"\n }\n }\n}\nOnce 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.
"},{"location":"messaging/#ntfy-setup","title":"ntfy setup","text":"ntfy is a completely free notification service. You can enable the ntfy integration with the following config.json section:
{\n \"messaging\": {\n \"ntfy\": true\n }\n}\nFor 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
{\n \"messaging\": {\n \"ntfy\": {\n \"host\": \"myntfyserver.com\",\n \"userurl\": \"https://myntfyserver.com/userhelp\",\n \"authorization\": \"Basic cGhpbDpteXBhc3M=\"\n }\n }\n}\nYou can enable the MeshCentral Zulip integration with the following config.json section:
{\n \"messaging\": {\n \"zulip\": {\n \"site\": \"https://api.zulip.com\",\n \"email\": \"your-bot@zulip.com\",\n \"api_key\": \"your_32_character_api_key\"\n }\n }\n}\nSlack 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
{\n \"messaging\": {\n \"slack\": true\n }\n}\nOnce 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.
"},{"location":"messaging/#administrator-management","title":"Administrator Management","text":"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.
"},{"location":"messaging/#two-factor-authentication","title":"Two-Factor Authentication","text":"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:
{\n \"settings\": {\n \"Cert\": \"devbox.mesh.meshcentral.com\",\n },\n \"domains\": {\n \"\": {\n \"title\": \"My Server\",\n \"passwordRequirements\": {\n \"msg2factor\": false\n }\n }\n }\n}\nNotice 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:
"},{"location":"other/adfs_sso_guide/","title":"ADFS SSO Guide","text":""},{"location":"other/adfs_sso_guide/#assumptions","title":"Assumptions","text":"The following guide was built under the assumptions that:
The guide was built to deal specifically with adding mesh as a Relying Party. I\u2019m 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.
"},{"location":"other/adfs_sso_guide/#guide","title":"Guide","text":"As with anything SSO, you need 2 pieces \u2013 the IDP setup (in this case ADFS) and the SP setup (in this case Mesh).
"},{"location":"other/adfs_sso_guide/#mesh-setup","title":"Mesh Setup","text":"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\nSave the config and restart the mesh server.
"},{"location":"other/adfs_sso_guide/#windows-server-configuration","title":"Windows Server Configuration","text":"ADFS setup (in pictures):
Relying Party Trust -> New Relying Party Trust
Edit the new \u201cRelying Party Trust\u201d Properties:
Then it\u2019s time to add Claims\u2026
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
"},{"location":"other/meshcentral_satellite/","title":"MeshCentral Satellite","text":"Coming Soon
"},{"location":"other/meshcentral_satellite/#abstract","title":"Abstract","text":"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.
"},{"location":"other/meshcentral_satellite/#introduction","title":"Introduction","text":"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:
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.
"},{"location":"other/meshcentral_satellite/#installation-and-configuration","title":"Installation and Configuration","text":"Start by creating an empty folder on a computer that is part of the domain you need to interact with. For example, create a \u201cc:\\MeshCentralSatellite\u201d then copy \u201cMeshCentralSatellite.exe\u201d into that folder. You can find that executable in the \u201cnode_modules/meshcentral/agents\u201d folder of your server. If it\u2019s 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 \u201cSettings\u2026\u201d, 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\u2019t 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 \u201cMy Account\u201d 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 \u201cDevice Name\u201d has two options, \u201cOperating System Name\u201d or \u201cNode Identifier\u201d. If you opt for \u201cOperating System Name\u201d, Intel AMT devices will show as, for example, \u201ciME-ComputerName\u201d in the list of domain computers. If \u201cnode identifier\u201d is used, Intel AMT devices will look like \u201ciME-xxxxxxxxxxx\u201d where xxx is the start of the MeshCentral node identifier for this device.
Using the node identifier is more secure as it can\u2019t 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 \u201cComputers\u201d 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 \u201c\\\u201d 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 \u201cSAM Account Name\u201d and the common name and all alternative names selected.
Once done, you can hit ok. The settings will be saved in a file called \u201cconfig.txt\u201d in plain text in the same folder as \u201cMeshCentralSatellite.exe\u201d. 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 \u201cLocal Connect\u201d the \u201cFiles\u201d menu to connect to the MeshCentral server.
MeshCentral Satellite should be connected and ready to receive commands from the server.
"},{"location":"other/meshcentral_satellite/#checking-the-connection","title":"Checking the connection","text":"In order to make sure the server correctly recognizes the MeshCentral Satellite connection, you can go to the server console and type \u201cusersession\u201d. 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.
"},{"location":"other/meshcentral_satellite/#configuring-intel-amt-8021x","title":"Configuring Intel\u00ae AMT 802.1x","text":"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\": {\n \"802.1x\": {\n \"AuthenticationProtocol\": \"EAP-TLS\",\n \"SatelliteCredentials\": \"admin\"\n },\n \"WifiProfiles\": [\n {\n \"ssid\": \"Network-8021x\",\n \"authentication\": \"wpa2-802.1x\",\n \"encryption\": \"ccmp-aes\"\n }\n ]\n }\nIn 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\": {\n \"802.1x\": {\n \"AuthenticationProtocol\": \"PEAPv0/EAP-MSCHAPv2\",\n \"SatelliteCredentials\": \"admin\"\n },\n \"WifiProfiles\": [\n {\n \"ssid\": \"Network-8021x\",\n \"authentication\": \"wpa2-802.1x\",\n \"encryption\": \"ccmp-aes\"\n }\n ]\n }\nThe second example does not require that a certificate authority be setup, the first example does. In both cases, the WIFI profile is set to \u201cwpa2-802.1x\u201d 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, \u201cSatelliteCredentials\u201d indicates the account name that MeshCentral Satellite will be connected on. In our case, we used the \u201cadmin\u201d 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.
"},{"location":"other/meshcentral_satellite/#computer-and-certificate-operations","title":"Computer and certificate operations","text":"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 \u201camtconfig\u201d 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 \u201cNode Identifier\u201d 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\u2019s 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 \u201cSecurity\u201d 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.
"},{"location":"other/meshcentral_satellite/#running-as-a-background-service","title":"Running as a Background Service","text":"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 \u201cService\u201d menu in MeshCentral Satellite to install, start, stop and uninstall the Windows service. Make sure to come and run \u201cMeshCentralSatellite.exe\u201d 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 \u201cLog On\u201d 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 \u201cService:\u201c are coming from the background service. At this point, you can close the local application and the service will keep running in the background.
"},{"location":"other/meshcentral_satellite/#license","title":"License","text":"MeshCentral, MeshCentral Satellite 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.
"}]}