move docs to new repo
Signed-off-by: si458 <simonsmith5521@gmail.com>
si458 committed
Mar 1, 2026 at 10:43 UTC
f7142203513b0348518119fba065642482e0bb68
369 files changed
+15
-8319
.github/workflows/deploy-docs.yml
deleted
-38
@@ -1,38 +0,0 @@
1
-name: Deploy Docs
2
-on:
3
- push:
4
- branches:
5
- - master
6
- paths:
7
- - docs/**
8
-
9
-defaults:
10
- run:
11
- working-directory: docs
12
-
13
-jobs:
14
- deploy:
15
- runs-on: ubuntu-latest
16
- steps:
17
- - uses: actions/checkout@v4
18
- with:
19
- fetch-depth: 0
20
-
21
- - uses: actions/setup-python@v5
22
- with:
23
- python-version: 3.x
24
-
25
- - name: Install dependencies
26
- run: |
27
- pip install --upgrade pip
28
- pip install zensical mkdocs-material mkdocs-print-site-plugin pymdown-extensions
29
-
30
- - name: Build with Zensical
31
- run: zensical build
32
-
33
- - name: Deploy to Pages branch
34
- uses: peaceiris/actions-gh-pages@v4
35
- with:
36
- github_token: ${{ secrets.GITHUB_TOKEN }}
37
- publish_dir: docs/site
38
- publish_branch: gh-pages
\ No newline at end of file
docs/.gitignore
deleted
-2
@@ -1,2 +0,0 @@
1
-/site
2
-# ^ zensical's build directory
\ No newline at end of file
docs/.vscode/launch.json
deleted
-15
@@ -1,15 +0,0 @@
1
-{
2
- // Use IntelliSense to learn about possible attributes.
3
- // Hover to view descriptions of existing attributes.
4
- // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
5
- "version": "0.2.0",
6
- "configurations": [
7
- {
8
- "type": "chrome",
9
- "request": "launch",
10
- "name": "Launch Chrome against localhost",
11
- "url": "http://localhost:8080",
12
- "webRoot": "${workspaceFolder}"
13
- }
14
- ]
15
-}
\ No newline at end of file
docs/Example configs/haproxy-with-client-certs.cfg.example
deleted
-284
@@ -1,284 +0,0 @@
1
-# This example config is designed for HAProxy. It allows MeshCentral to use and validate Client Certificates.
2
-# Usernames/Passwords are still required. This will provide a layer for authorization.
3
-#
4
-# The MeshID enviorment variable is used for the binary paths. Simply put your MeshID for an incoming group
5
-# into this variable and the binary paths will use the ID for downloading the agent directly to the client.
6
-# Simply type in your specific url (https://reallycoolmeshsystem.com/win10full) and the agent will download
7
-# with the proper meshid for the specified group. In my usage, I have an incoming group assigned.
8
-#
9
-# The config also ensures a split between IPv4 and IPv6. Thus if a client attempts to connect on IPv4,
10
-# it will connect to Meshcentral with IPv4. And if IPv6 is used, IPv6 connection to Meshcentral will be used.
11
-# This config is written in *long* form, it is written for simplicity and clarity. I'm confident that someone
12
-# can shorten the script size easily.
13
-#
14
-# Please examine the MeshID, location of the certificates, certificate names and OU test for the certificates.
15
-# CRL and guest connections are not integrated yet.
16
-#
17
-#
18
-# The following specific path names do not require a validated client certificate:
19
-#
20
-# /win10background - Windows 10 Background Binary Installer
21
-# /win10full - Windows 10 Binary Interactive and Background Installer
22
-# /macosxfull - MacOS 10 Binary Interactive and Background Installer
23
-# /linuxscript - Linux Script ( See Docs)
24
-# /linux64full - Linux AMD64 Binary Interactive and Background Installer
25
-# /linux64background - Linux AMD64 Binary Background Installer
26
-# /linuxarmfull - Linux ARMhf Binary Interactive and Background Installer
27
-# /linuxarmbackground - Linux ARMhf Binary Background Installer
28
-#
29
-# /agent.ashx - Agent to server connection (Websockets)
30
-# /meshrelay.ashx - Agent to server relay
31
-# /meshagents - Default agent download path
32
-# /meshosxagent - Default agent download path for Mac OS X
33
-
34
-
35
-global
36
- log /dev/log local0
37
- log /dev/log local1 info
38
- chroot /var/lib/haproxy
39
- stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
40
- stats timeout 30s
41
- user haproxy
42
- group haproxy
43
- daemon
44
-
45
- # Set the meshID to the incoming group ID
46
- setenv meshID {{really long mesh group ID}}
47
-
48
- # Default SSL material locations
49
- # Probably needs a more secure location
50
- ca-base /etc/haproxy/
51
- crt-base /etc/haproxy/
52
-
53
-
54
- # Default ciphers to use on SSL-enabled listening sockets.
55
- # For more information, see ciphers(1SSL). This list is from:
56
- # https://hynek.me/articles/hardening-your-web-servers-ssl-ciphers/
57
- # An alternative list with additional directives can be obtained from
58
- # https://mozilla.github.io/server-side-tls/ssl-config-generator/?server=haproxy
59
- ssl-default-bind-ciphers ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:RSA+AESGCM:RSA+AES:!aNULL:!MD5:!DSS
60
- ssl-default-bind-options no-sslv3
61
-
62
-
63
-defaults
64
- log global
65
- mode http
66
- option httplog
67
- option dontlognull
68
- timeout connect 5000
69
- timeout client 50000
70
- timeout server 50000
71
- errorfile 400 /etc/haproxy/errors/400.http
72
- errorfile 403 /etc/haproxy/errors/403.http
73
- errorfile 408 /etc/haproxy/errors/408.http
74
- errorfile 500 /etc/haproxy/errors/500.http
75
- errorfile 502 /etc/haproxy/errors/502.http
76
- errorfile 503 /etc/haproxy/errors/503.http
77
- errorfile 504 /etc/haproxy/errors/504.http
78
-
79
-frontend http
80
- bind :::80 v4v6
81
- redirect scheme http code 301 if !{ ssl_fc }
82
-
83
-frontend https
84
- # Replace Root-ca.pem and mesh.pem with proper certs
85
- bind :::443 v4v6 ssl crt mesh.pem ca-file Root-ca.pem verify optional crt-ignore-err all ca-ignore-err all
86
- http-request add-header X-Forwarded-Proto https
87
-
88
-# Testing for Client Certificate used
89
- acl clientssl ssl_c_used
90
-
91
-# Set SSL Cert OU here to verify a proper user
92
- acl clientssl ssl_c_s_dn(OU) "Bad Ass Mesh Services Inc"
93
-
94
-# Agents for download
95
- acl meshagent path_beg /meshagents
96
- acl macmeshagent path_beg /meshosxagent
97
-
98
-# IPV4 vs IPV6 test
99
- acl meshipv4 src 0.0.0.0/0
100
- acl meshipv6 src ::/0
101
-
102
-# Websockets ACL
103
- acl host_ws path_beg /agent.ashx
104
-
105
-# MeshRelay
106
- acl meshrelay path_beg /meshrelay.ashx
107
-
108
-# Specific Agent installers for each platform
109
- acl winback path_beg /win10background
110
- acl winfull path_beg /win10full
111
- acl macosx path_beg /macosxfull
112
- acl linuxscript path_beg /linuxscript
113
- acl linux64full path_beg /linux64full
114
- acl linux64back path_beg /linux64background
115
- acl linuxarmfull path_beg /linuxarmfull
116
- acl linuxarmback path_beg /linuxarmbackground
117
-
118
-# WebSockets
119
- use_backend meshWebSocket4 if host_ws meshipv4 !clientssl
120
- use_backend meshWebSocket6 if host_ws meshipv6 !clientssl
121
-
122
-# Mesh Relay
123
- use_backend meshcentralv4 if meshrelay meshipv4
124
- use_backend meshcentralv6 if meshrelay meshipv6
125
-
126
-# Client SSL Specific
127
- use_backend meshcentralv4 if meshipv4 !meshagent !macmeshagent clientssl
128
- use_backend meshcentralv6 if meshipv6 !meshagent !macmeshagent clientssl
129
-
130
-# Direct Mesh Agent download
131
- use_backend meshcentralv4 if meshipv4 meshagent
132
- use_backend meshcentralv6 if meshipv6 meshagent
133
-
134
- use_backend meshcentralv4 if meshipv4 macmeshagent
135
- use_backend meshcentralv6 if meshipv6 macmeshagent
136
-
137
-# Windows Custom Download
138
- use_backend Win10full4 if meshipv4 winfull
139
- use_backend Win10full6 if meshipv6 winfull
140
-
141
- use_backend Win10back4 if meshipv4 winback
142
- use_backend Win10back6 if meshipv6 winback
143
-
144
-# Mac CUstom Download
145
- use_backend macosx4 if meshipv4 macosx
146
- use_backend macosx6 if meshipv6 macosx
147
-
148
-# Linux Script Custom Download
149
- use_backend linuxSCRIPT4 if meshipv4 linuxscript
150
- use_backend linuxSCRIPT6 if meshipv6 linuxscript
151
-
152
-# Linux Script Custom Download
153
- use_backend linux64-bin-full4 if meshipv4 linux64full
154
- use_backend linux64-bin-full6 if meshipv6 linux64full
155
-
156
- use_backend linux64-bin-back4 if meshipv4 linux64back
157
- use_backend linux64-bin-back6 if meshipv6 linux64back
158
-
159
- use_backend linuxarm-bin-full4 if meshipv4 linuxarmfull
160
- use_backend linuxarm-bin-full6 if meshipv6 linuxarmfull
161
-
162
- use_backend linuxarm-bin-back4 if meshipv4 linuxarmback
163
- use_backend linuxarm-bin-back6 if meshipv6 linuxarmback
164
-# Fail if none of the above
165
- http-request deny if !macmeshagent !meshagent !clientssl !host_ws !winback !winfull !macosx !linuxscript !linux64full !linux64back !linuxarmfull !linuxarmback !meshrelay
166
-
167
-
168
-# Websockets
169
-backend meshWebSocket4
170
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
171
- server ipv4 127.0.0.1:444
172
-
173
-backend meshWebSocket6
174
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
175
- server ipv6 [::1]:444
176
-
177
-# Standard Interface
178
-backend meshcentralv4
179
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
180
- server ipv4 127.0.0.1:444
181
-
182
-backend meshcentralv6
183
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
184
- server ipv6 [::1]:444
185
-
186
-# Windows Agent Download
187
-backend Win10back4
188
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
189
- http-request set-path /meshagents
190
- http-request set-query id=4&meshid=%[env(meshID)]&installflags=2
191
- server ipv4 127.0.0.1:444
192
-
193
-backend Win10back6
194
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
195
- http-request set-path /meshagents
196
- http-request set-query id=4&meshid=%[env(meshID)]&installflags=2
197
- server ipv6 [::1]:444
198
-
199
-backend Win10full4
200
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
201
- http-request set-path /meshagents
202
- http-request set-query id=4&meshid=%[env(meshdID)]&installflags=0
203
- server ipv4 127.0.0.1:444
204
-
205
-backend Win10full6
206
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
207
- http-request set-path /meshagents
208
- http-request set-query id=4&meshid=%[env(meshID)]&installflags=0
209
- server ipv6 [::1]:444
210
-
211
-# MacOS Agent Download
212
-backend macosx6
213
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
214
- http-request set-path /meshosxagents
215
- http-request set-query id=100054&meshid=%[env(meshID)]
216
- server ipv6 [::1]:444
217
-
218
-backend macosx4
219
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
220
- http-request set-path /meshosxagents
221
- http-request set-query id=100054&meshid=%[env(meshID)]
222
- server ipv4 127.0.0.1:444
223
-
224
-# Linux Script Downloads
225
-backend linuxSCRIPT6
226
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
227
- http-request set-path /meshagents
228
- http-request set-query scrpot=1
229
- server ipv6 [::1]:444
230
-
231
-backend linuxSCRIPT4
232
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
233
- http-request set-path /meshagents
234
- http-request set-query scrpot=1
235
- server ipv4 127.0.0.1:444
236
-
237
-# Linux Binary Downloads
238
-backend linux64-bin-full6
239
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
240
- http-request set-path /meshagents
241
- http-request set-query id=%[env(meshID)]&installflags=0&meshinstall=6
242
- server ipv6 [::1]:444
243
-
244
-backend linux64-bin-full4
245
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
246
- http-request set-path /meshagents
247
- http-request set-query id=%[env(meshID)]&installflags=0&meshinstall=6
248
- server ipv4 127.0.0.1:444
249
-
250
-backend linux64-bin-back6
251
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
252
- http-request set-path /meshagents
253
- http-request set-query id=%[env(meshID)]&installflags=2&meshinstall=6
254
- server ipv6 [::1]:444
255
-
256
-backend linux64-bin-back4
257
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
258
- http-request set-path /meshagents
259
- http-request set-query id=%[env(meshID)]&installflags=2&meshinstall=6
260
- server ipv4 127.0.0.1:444
261
-
262
-backend linuxarm-bin-full6
263
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
264
- http-request set-path /meshagents
265
- http-request set-query id=%[env(meshID)]&installflags=0&meshinstall=25
266
- server ipv6 [::1]:444
267
-
268
-backend linuxarm-bin-full4
269
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
270
- http-request set-path /meshagents
271
- http-request set-query id=%[env(meshID)]&installflags=0&meshinstall=25
272
- server ipv4 127.0.0.1:444
273
-
274
-backend linuxarm-bin-back6
275
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
276
- http-request set-path /meshagents
277
- http-request set-query id=%[env(meshID)]&installflags=2&meshinstall=25`
278
- server ipv6 [::1]:444
279
-
280
-backend linuxarm-bin-back4
281
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
282
- http-request set-path /meshagents
283
- http-request set-query id=%[env(meshID)]&installflags=2&meshinstall=25
284
- server ipv4 127.0.0.1:444
docs/Example configs/haproxy-with-sni-sample.cfg
deleted
-55
@@ -1,55 +0,0 @@
1
-# Uses proxy protocol in HAProxy in combination with SNI to preserve the original host address
2
-# Update the config.json to work with HAProxy
3
-# Specify the IP addrehostname that the traffic will come from HAProxy (this might not be the address that is bound to the listener)
4
-# "tlsOffload": "10.1.1.10",
5
-#
6
-# Specify the HAPRoxy URL with the hostname to get the certificate
7
-# "certUrl": "https://mc.publicdomain.com:443/"
8
-
9
-frontend sni-front
10
- bind 10.1.1.10:443
11
- mode tcp
12
- tcp-request inspect-delay 5s
13
- tcp-request content accept if { req_ssl_hello_type 1 }
14
- default_backend sni-back
15
-
16
-backend sni-back
17
- mode tcp
18
- acl gitlab-sni req_ssl_sni -i gitlab.publicdomain.com
19
- acl mc-sni req_ssl_sni -i mc.publicdomain.com
20
- use-server gitlabSNI if gitlab-sni
21
- use-server mc-SNI if mc-sni
22
- server mc-SNI 10.1.1.10:1443 send-proxy-v2-ssl-cn
23
-
24
-frontend cira-tcp-front
25
- bind 10.1.1.10:4433
26
- mode tcp
27
- option tcplog
28
- tcp-request inspect-delay 5s
29
- default_backend mc-cira-back
30
-
31
-backend cira-tcp-back
32
- mode tcp
33
- server mc-cira 10.1.1.30:4433
34
-
35
-frontend mc-front-HTTPS
36
- mode http
37
- option forwardfor
38
- bind 10.1.1.10:1443 ssl crt /etc/haproxy/vm.publicdomain.net.pem accept-proxy
39
- http-request set-header X-Forwarded-Proto https
40
- option tcpka
41
- default_backend mc-back-HTTP
42
-
43
-backend mc-back-HTTPS
44
- mode http
45
- option forwardfor
46
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
47
- option http-server-close
48
- server mc-01 10.1.1.30:443 check port 443 verify none
49
-
50
-# In the event that it is required to have TLS between HAProxy and Meshcentral,
51
-# Remove the tls_Offload line and replace with trustedProxy
52
-# Specify the IP addrehostname that the traffic will come from HAProxy (this might not be the address that is bound to the listener)
53
-# "trustedProxy": "10.1.1.10",
54
-# and change the last line of backend mc-back-HTTPS to use HTTPS by adding the ssl keyword
55
-# server mc-01 10.1.1.30:443 check ssl port 443 verify none
docs/README.md
new
+15
@@ -0,0 +1,15 @@
1
+# 📚 MeshCentral Documentation
2
+
3
+> **Note:** The Docs folder has been moved to its own repository for better organization and maintenance.
4
+
5
+## 🔗 Access the Documentation
6
+
7
+You can find the complete MeshCentral documentation at:
8
+
9
+**[MeshCentral Docs Repository](https://github.com/Ylianst/MeshCentralDocs/tree/main)**
10
+
11
+This repository contains all the latest guides, tutorials, and reference materials for MeshCentral.
12
+
13
+---
14
+
15
+*For the main MeshCentral project, visit [Ylianst/MeshCentral](https://github.com/Ylianst/MeshCentral).*
\ No newline at end of file
docs/docs/design/images/2022-05-15-12-57-36.jpg
Binary files a/docs/docs/design/images/2022-05-15-12-57-36.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-01-56.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-01-56.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-03-25.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-03-25.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-36-01.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-36-01.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-41-26.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-41-26.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-44-41.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-44-41.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-47-26.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-47-26.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-54-44.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-54-44.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-55-28.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-55-28.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-56-09.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-56-09.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-56-46.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-56-46.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-58-06.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-58-06.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-58-29.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-58-29.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-58-56.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-58-56.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-13-59-54.jpg
Binary files a/docs/docs/design/images/2022-05-15-13-59-54.jpg and /dev/null differ
docs/docs/design/images/2022-05-15-14-00-21.jpg
Binary files a/docs/docs/design/images/2022-05-15-14-00-21.jpg and /dev/null differ
docs/docs/design/images/Aspose.Words.61f7827a-f327-4beb-a49f-32222e664dff.002.jpg
Binary files a/docs/docs/design/images/Aspose.Words.61f7827a-f327-4beb-a49f-32222e664dff.002.jpg and /dev/null differ
docs/docs/design/images/Aspose.Words.61f7827a-f327-4beb-a49f-32222e664dff.011.jpg
Binary files a/docs/docs/design/images/Aspose.Words.61f7827a-f327-4beb-a49f-32222e664dff.011.jpg and /dev/null differ
docs/docs/design/index.md
deleted
-425
@@ -1,425 +0,0 @@
1
-# Design and Architecture
2
-
3
-
4
-
5
-## 🎬 Video Walkthrough
6
-
7
-<div class="video-wrapper">
8
- <iframe src="https://www.youtube.com/embed/MOQ0uCUs7_M" frameborder="0" allowfullscreen></iframe>
9
-</div>
10
-
11
-## 🧾 Abstract
12
-
13
-This document goes over the architecture and design of the second version of MeshCentral, on which work started in late 2016, and covers the overview of the design, as well as providing 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.
14
-
15
-## 📘 Introduction
16
-
17
-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.
18
-
19
-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.
20
-
21
-## 🎯 Goals & Requirements
22
-
23
-The goal of MeshCentral is to be the best open source remote management software in the world. Remote computer management is a big area with many different usages and requirements. To best suite this, it’s important to have software that is as flexible as possible.
24
-
25
-Additionally, there are many other goals:
26
-
27
- > - **Must be quick and easy to install.**
28
- > - **Must install on all major operating systems and platforms.**
29
- > - **Can be deployed on small computers and the cloud.**
30
- > - **Can be deployed within containers.**
31
- > - **Can be deployed in many network environments.**
32
- > - **Must support both software agent and Intel® AMT hardware agent.**
33
- > - **Must only use open source dependencies.**
34
- > - **Must provide all basic remote management features (desktop, terminal, files…)**
35
- > - **Must use the network efficiently.**
36
- > - **Must have a real time user interface.**
37
- > - **Must be easy to use.**
38
- > - **Must be fast.**
39
- > - **Etc.**
40
-
41
-Basically, all the requirements you would expect from open source software that can go viral. Since this software is sponsored by Intel, it’s going to support Intel® AMT really well, making it possible to manage a remote computer regardless of its OS or power state. Intel® AMT is not required to use this software, however it’s a great fit.
42
-
43
-## 🖥️ Design Overview
44
-
45
-In this section, we do a very high level overview of MeshCentral’s design. MeshCentral has 3 big components :
46
-
47
- - *The server*,
48
- - *The agent and*
49
- - *The web application*.
50
-
51
-
52
-
53
-There is of course more software that support these 3 components like the Windows Server Installer, ClickOnce application, MeshCentral Discovery Tool and more. These will be covered later. Most of the document will focus on these 3 main components. Another component that is significant but not part of the software itself is Intel® AMT (Intel® Active Management Technology). MeshCentral supports Intel AMT that acts like an optional hardware based agent for MeshCentral.
54
-
55
-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.
56
-
57
-
58
-
59
-It’s important to note that while JavaScript is used in all 3 components, the JavaScript runtime is very different. The JavaScript written to run within a browser sandbox uses different calls than the one running in NodeJS on the server or on the agent with DukTape.
60
-
61
-This is probably a good time to introduce DukTape [(https://www.duktape.org/)](https://www.duktape.org/). Unlike the browser and NodeJS JavaScript engines, DukTape is a less known JavaScript runtime written in C. The agent is built in C code with little smarts other than being able to securely connect back to the server. The server then pushes to the agent a JavaScript file that the agent runs. This makes the agent very flexible since a developers can quickly change the JavaScript that is pushed to the agent and change the agent’s behavior instantly.
62
-
63
-Another interesting design decision is that MeshCentral makes almost no use of RESTful API’s. Instead, almost everything is done using WebSocket. This allows JSON objects to be exchanged fully asynchronously. There is no pushing the refresh button or polling as events are sent by all actors in real time.
64
-
65
-## 🗄️ MeshCentral server
66
-
67
-The MeshCentral server is a NodeJS application that is published on NPM at : [https://www.npmjs.com/package/meshcentral](https://www.npmjs.com/package/meshcentral) Many administrators can get started quickly using `npm install meshcentral` once NodeJS is installed. MeshCentral will work on Node 6.x and higher.
68
-
69
-## 📦 Dependencies
70
-
71
-The server makes use of the following dependencies on NPM. These are all automatically installed by NPM when installing MeshCentral.
72
-
73
-Can be found in the file : `MeshCentralServer.njsproj`
74
-
75
-The main takeaway is that MeshCentral is mostly an ExpressJS application. This is not a complete list of dependencies as many of these packages have their own dependencies creating a large tree. The security of these packages is a concern and all of the dependency tree is a concern. In addition to the dependencies that are “hard coded”, there are a few more that are installed only when needed. These are :
76
-
77
-### node-windows
78
-
79
-- **greenlock, le-store-certbot, le-challenge-fs** :
80
-
81
- > Installed on all Windows install. Allows background service install:
82
-
83
-- **le-acme-core** :
84
-
85
- > Installed only when Let’s Encrypt must be used:
86
-
87
-- **mongojs** :
88
-
89
- > Installed when MongoDB is in used.
90
-
91
-- **nodemailer** :
92
-
93
- > Installed when SMTP server support is in used.
94
-
95
-MeshCentral will run `npm install` automatically when any of these optional modules are needed but not currently available.
96
-
97
-## 🎬 Understanding the different modes: LAN, WAN and Hybrid
98
-
99
-
100
-<div class="video-wrapper">
101
- <iframe width="320" height="180" src="https://www.youtube.com/embed/gx5Fh3pQOns" frameborder="0" allowfullscreen></iframe>
102
-</div>
103
-
104
-## 📁 Code files and folders
105
-
106
-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.
107
-
108
-### Folders
109
-
110
- `agents`: Compiled agents, install scripts, tools and agent JavaScript.
111
-
112
- `public`: Static web elements such as images, CSS, HTML and more.
113
-
114
- `views`: Main web application, login screen and messenger app.
115
-
116
-### Configuration & text files
117
-
118
-`package.json`: Description of the MeshCentral package on NPM.
119
-
120
-`sample-config.json`: A sample “config.json” file to get started.
121
-
122
-`readme.txt`: Readme file published with the MeshCentral package.
123
-
124
-### Code files
125
-
126
-```bash
127
- amtevents.js | Used to decode Intel AMT WSMAN events.
128
- amtmanager.js | Used to handle Intel AMT/CIRA things.
129
- amtprovisioningserver.js | Used to Provision Intel AMT on a Local Network.
130
- amtscanner.js | Used to scan a local network for Intel AMT machines.
131
- amtscript.js | Used to run Intel AMT scripts from MeshCommander.
132
- certoperations.js | Used to generate and perform certificate operations.
133
- common.js | Various commonly used methods.
134
- crowdsec.js | Used to handle all crowdsec security features
135
- db.js | Used to access the MongoDB or NeDB database.
136
- exeHandler.js | Used to modify windows executables.
137
- firebase.js | Used to handle Google Firebase things.
138
- interceptor.js | Used to insert credentials in an HTTP stream.
139
- letsencrypt.js | Used to obtain and use a Let’s Encrypt certificate.
140
- mcrec.js | Standalone Session Recording Indexer.
141
- meshaccelerator.js | Used to offload RSA sign to other CPU cores.
142
- meshagent.js | Used to communicate to agents.
143
- meshbot.js | Sample bot to connect to meshcentral and preform various tasks
144
- meshcentral.js | The is the main module, gets the server started.
145
- meshctrl.js | MeshCtrl performs command line actions on a MeshCentral server.
146
- meshcore.js | Main Agent Code that runs on your remote devices.
147
- meshdesktopmultiplex.js | Used to handle remote desktop multiplexing.
148
- meshdevicefile.js | Used to handle file download requests.
149
- meshipkvm.js | Used to handle IP KVM integration
150
- meshmail.js | Used to send SMTP mails.
151
- meshmessaging.js | Used to handle all users messaging methods like 2FA.
152
- meshrelay.js | Used to relay agent and browser web socket connections.
153
- meshscanner.js | MeshCentral server discovery when in LAN mode.
154
- meshsms.js | Used to handle all users sms methods.
155
- meshuser.js | Used to communicate with browsers.
156
- mpsserver.js | Used to communicate to Intel® AMT CIRA.
157
- mqttbroker.js | Used to create/handle an MQTT broker (beta)
158
- multiserver.js | Used for server-to-server communication.
159
- pass.js | Performs password hash + salt.
160
- redirserver.js | Used to handle HTTP traffic.
161
- swarmserver.js | Used to upgrade legacy MeshCentralv1 agents.
162
- webauthn.js | Handles all WebAuthN things.
163
- webrelayserver.js | Used for all HTTP/HTTPS web relaying from agents.
164
- webserver.js | Handles HTTPS traffic.
165
- winservice.js | Server background install on Windows.
166
-
167
-```
168
-
169
-At a high level, the MeshCentral.js file will get the server started.
170
-
171
-By default, it will start :
172
-
173
-- `webserver.js` on port `443`,
174
-- `redirectserver.js` on port `80` and
175
-- `mpssrver.js` on port `4433`.
176
-
177
-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.
178
-
179
-### Server database
180
-
181
-One of the big design decision on the server is its database. We want something that scales and so, opted to deal with the good and the bad of a NoSQL database, MongoDB. On the other hand, we want the server to be really simple to install for people who want to try it out or want to manage 100 computers or less. We don’t want the added learning curve of MongoDB for people that don’t really need it. It turned out, we can have both. NeDB is a NPM package that provides a simple MongoDB-like API while being completely implemented in NodeJS. For most people, this is plenty good to get started.
182
-
183
-By default, MeshCentral will just create and use a NeDB database, but can be configured to use MongoDB. The internal code path for both databases are almost exactly identical so the “db.js” file handles both, almost the same way and the exact database in use is completely abstracted from the rest of the server code.
184
-
185
-## 🔐 Certificates
186
-
187
-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.
188
-
189
-
190
-
191
-In this section we review what certificates are created, what are their uses and how they are stored. Most administrators using MeshCentral will not need a deep understanding of this section to run the server, however, a basic understanding of this section can help understand how to best protect the server’s critical security assets.
192
-
193
-### Server Certificates
194
-
195
-As indicated above, the MeshCentral server creates four certificates when it first runs. It uses ForgeJS to perform certificate creation and all four certificates below are saved in the `meshcentral-data` folder. The four certificates are:
196
-
197
-#### Server root
198
-
199
-`root-cert-public.crt`
200
-
201
-This is a self-signed root certificate that is used only to issue the 3 next certificates. This certificate can be useful when it’s installed as a root of trust in some situations. For example, when Intel AMT connects to the MPS server on port `4433`, it will correctly connect only if this root certificate is loaded into Intel AMT as a trusted certificate. Browser can also be setup to trust this root certificate in order to create a trusted connection between a browser and the servers HTTPS port. This certificate is RSA3072 unless the option `--fastcert` is used, in that case a RSA2048 certificate is generated.
202
-
203
-#### MPS certificate
204
-
205
-`mpsserver-cert-public.crt`
206
-
207
-This is a TLS certificate signed by the root above used as a TLS server certificate on the MPS port 4433. Intel AMT computers will connect to this port and verify the certificate time, common name and that it’s signed by the root above. This certificate is not typically changed, even when the server is running in production. This certificate is always generated as RSA2048 because older Intel AMT firmware will not accept certificates with larger keys.
208
-
209
-#### Web certificate
210
-
211
-`webserver-cert-public.crt`
212
-
213
-This is the default certificate used to secure the HTTPS port `443`. It is signed by the root above and is the certificate users will first see then connecting the browser to the server. Often, users will need to ignore the browser security warning. This certificate is RSA3072 unless the option `--fastcert` is used, in that case a RSA2048 certificate is generated. In production environments, this certificate is replaced with a real certificate.
214
-
215
-There are many ways to change this certificate for a more appropriate certificate in production environments :
216
-
217
-- You can replace the `webserver-cert-\*` files in the `meshcentral-data` folder.
218
-
219
-- You can use Let’s Encrypt which will override this certificate automatically.
220
-
221
-- You can use a reverse-proxy in front of the server with `--tlsoffload`.
222
-
223
-#### Agent certificate
224
-
225
-`agentserver-cert-public.crt`
226
-
227
-This certificate is used to authenticate the server to agents. It’s signed by the root above and when installing an agent, the hash of this certificate is given to the agent so that it can connect back to the server securely. This certificate is RSA3072 unless the option `--fastcert` is used, in that case a RSA2048 certificate is generated.
228
-
229
-The `meshcentral-data` folder contains critical server information including private keys therefore, it’s important that it be well protected. It’s important to backup the `meshcentral-data` folder and keep the backup in a secure place. If, for example the “agent certificate” on the server is lost, there is no hope for agents ever be able to connect back to this server. All agents will need to be re-installed with a new trusted certificate.
230
-
231
-If someone re-installs a server, placing the `meshcentral-data` folder back with these certificates should allow the server to resume normal operations and accept connections for Intel AMT and agents as before.
232
-
233
-### Agent Certificates
234
-
235
-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.
236
-
237
-
238
-
239
-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.
240
-
241
-#### Agent root certificate
242
-
243
-This certificate is the root trust of the agent. The SHA384 hash of this certificates public key is the agent’s identifier on the server. When a agent connects to the server using web socket, it performs a secondary authentication check using this certificate. The server will compute the agent’s identifier after the agent sent a signed proof to the server. This certificate is also used to sign the secondary certificate below when it’s needed.
244
-
245
-#### Secondary certificate
246
-
247
-This is a certificate signed by the agent root above. It’s currently only used by WebRTC to perform dTLS authentication to a remote browser. This certificate does not need to be signed by a trusted CA for WebRTC purposes since the hash of the certificate will be sent to the browser using a trusted path. If the agent root certificate is not hardened using platform cryptography, the secondary certificate is not created and the agent root cert is used for all purposes.
248
-
249
-A possible attack would occur if someone were to be able to access the agent root certificate. They could impersonate the agent to the server. Agents don’t have any rights to perform management operations on the server or other agents, but by impersonating a agent, a rogue agent would pretend to be an office computer to which administrator would login with their username & password, especially when the root is not hardened. Some care should be taken to protect the `meshagent.db` file and to not give important information to untrusted agents.
250
-
251
-## 🔒 TLS Security
252
-
253
-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.
254
-
255
-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.
256
-
257
-### MeshCentral HTTPS port 443
258
-
259
-The HTTPS port on the MeshCentral server will only support TLS 1.2 and above, and makes use of only 6 cypher suites:
260
-
261
-```
262
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0xc030)
263
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384 (0xc028)
264
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA (0xc014)
265
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0xc02f)
266
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0xc027)
267
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA (0xc013)
268
-```
269
-
270
-Note that these cipher suites are all perfect forward secrecy (PFS) suites and are considered cryptographically secure as of the writing of this document. When the server is deployed on the Internet,[ https://ssllabs.com ](https://ssllabs.com/)gives the server an A rating with no known vulnerabilities and no weak ciphers detected.
271
-
272
-
273
-
274
-SSL Labs confirms that all major browsers should be able to connect correctly to this server.
275
-
276
-### MeshCentral MPS port 4433
277
-
278
-The Manageability Presence Server (MPS) port `4433` is used for incoming Intel AMT CIRA connections. By default it uses a TLS certificate that is signed by a self-signed root certificates. This port is not intended to be connected to by typical browsers, only Intel AMT should connect to this port. Note that the TLS certificate generated by MeshCentral for port `4433` is RSA 2048bits, this is because older Intel AMT firmware don’t support RSA 3072. Because the port is not secured using a trusted certificate, SSL Labs will not rate the security of this server.
279
-
280
-
281
-
282
-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.
283
-
284
-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:
285
-
286
-```
287
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0xc030)
288
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA384 (0xc028)
289
-TLS\_ECDHE\_RSA\_WITH\_AES\_256\_CBC\_SHA (0xc014)
290
-TLS\_RSA\_WITH\_AES\_256\_GCM\_SHA384 (0x9d)
291
-TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA256 (0x3d)
292
-TLS\_RSA\_WITH\_AES\_256\_CBC\_SHA (0x35)
293
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0xc02f)
294
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0xc027)
295
-TLS\_ECDHE\_RSA\_WITH\_AES\_128\_CBC\_SHA (0xc013)
296
-TLS\_RSA\_WITH\_AES\_128\_GCM\_SHA256 (0x9c)
297
-TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA256 (0x3c)
298
-TLS\_RSA\_WITH\_AES\_128\_CBC\_SHA (0x2f)
299
-
300
-```
301
-
302
-The suites starting with `TLS\_RSA\_` don’t have perfect forward secrecy (PFS) and so, are considered weak by SSL Labs. However, these are generally the suites that are supported by Intel AMT.
303
-
304
-## 🛰️ Agent to server handshake
305
-
306
-One interesting aspect of MeshCentral’s design is how the agent connects to the server. We wanted a way for the agent to connect to the server that would be similar to how browsers connect to web servers. This allows for a large number of agents to connect just like if a large number of browsers where connecting. All of the infrastructure that helps web server’s scale would be put to use in the same way for agent connections. For example: TLS offload hardware, load balancers, reverse-proxies, web server scaling, etc. could all be put to use. It also makes the server easier to setup because only one port (HTTPS 443) is needed for both users and agents.
307
-
308
-One big difference between the agent connecting and a typical browser is how the server is authenticated. Browsers have a set of known trusted root certificates. The server’s web certificate is checked for validity including the name, time trusted CA and more. The agent does not have this. Instead, it just has a hash to a private server certificate.
309
-
310
-The public facing web certificate of the server can change frequently. For example, Let’s Encrypt certificates are valid 90 days. Agents need to be able to validate a specific server for a long time and don’t really need to trust anything else except one specific server. We also don’t want to tie the agents to a specific domain name as we could change that in the future or want to support servers with dynamic IP addresses and no fixed DNS names.
311
-
312
-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.
313
-
314
-
315
-
316
-The secondary check allows the agent to confirm that this server does own the private key of the private certificate expected by the agent. The agent caches the hash of the “outer” web certificate. When re-connecting, if the agent sees the same outer web certificate, it will skip the secondary check. For obvious security raisons, it’s important that the agent not accept any management messages until the secondary check is completed or skipped.
317
-
318
-To prevent man-in-the-middle attacks, the secondary check also “pins” the outer web certificate. That is, the server both confirms it’s the right server and indicates to the agent the hash of the outer certificate that it must have seen during the TLS connection. The agent must check this hash to make sure there is no attacker in the middle.
319
-
320
-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.
321
-
322
-
323
-
324
-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).
325
-
326
-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.
327
-
328
-
329
-
330
-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.
331
-
332
-In addition, there are two extra messages of interest that can be sent by the agent right at the start. The agent may send the server message number 4 if the secondary check can be skipped and may send binary message number 5 indicating what server hash it expects to verify. Message number 5 is interesting because a server may have many “identities” at the same time, and so, the server will use message number 5 in order to use the right Agent Server certificate.
333
-
334
-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.
335
-
336
-The server and agent signatures are computed like this :
337
-
338
-
339
-
340
-While the server will often skip its RSA signature operation due to the agents caching the outer web certificate, the server must perform an RSA verify to each agent connection. This can’t be skipped but is needed to authenticate the agent.
341
-
342
-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.
343
-
344
-## 🌍 Browser to agent relay and WebRTC
345
-
346
-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.
347
-
348
-To setup a session between a browser and the agent, the server will send a URL to both sides to connect to. The URL is generated by the server and includes a unique connection token. It is sent to both the browser and agent using the web socket control channel and a JSON message. Both sides perform a websocket connection to the target URL and the server will “pipe” both sessions together to act as a passive relay. For security, the agent will only accept connections to the URL given by the server if the server has the same outer web certificate as its control connection. Also note that in this mode, the session is not end-to-end encrypted. The server is performing a TLS decrypt and re-encrypt and the traffic cost is high as each byte of data has to be received and sent again.
349
-
350
-
351
-
352
-
353
-The relay server is just websocket server that will wait for connections with session tokens. When two connection with the same connection token arrive, the server makes sure that at least one of the two connections is an authenticated user, it then sends the character `c` on both sides to inform both parties that the relay is starting and then pipes both sessions together. Once the session is started, the browser and agent are free to send messages to each other. Note that when the server sends the relay URL to the agent, it also sends to the agent the user’s permissions flags. This may be used by the agent to limit what the user can do on this session.
354
-
355
-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.
356
-
357
-A unique feature of MeshCentral is its use of WebRTC. WebRTC was introduced in major browsers as a way to allow browsers to directly communicate to each other and perform audio/video streaming. The mesh agent has a WebRTC data-only stack that is custom built for this project in C code. It’s compatible with Chrome and Firefox implementations and once a session is set up, allows data to flow directly from the browser to the agent, bypassing the server.
358
-
359
-
360
-
361
-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.
362
-
363
-To setup WebRTC, browsers typically use STUN and TURN servers to get traffic through 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 through 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.
364
-
365
-To perform the switch-over, both browser and agent will exchange WebRTC control messages over the newly established web socket relay session.
366
-
367
-
368
-
369
-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.
370
-
371
-The browser will kick off the WebRTC setup sending the initial WebRTC offer with the agent responding with a WebRTC answer. If the WebRTC session gets setup, both sides need to negotiate a clear transition from the web socket session to the WebRTC session. To do this, both sides send a start switch control fragment (this is a text fragment), the other side will respond with an ACK when the web socket session is flushed out and it’s safe to switch.
372
-
373
-On the agent side, the new WebRTC session inherits the user access rights of the web socket. Currently, the web socket channel is still maintained open. While it’s not strickly needed, the web socket session terminates more cleanly than WebRTC and so, oddly its closure is used to signal the end of the WebRTC session.
374
-
375
-## 💬 Messenger
376
-
377
-MeshCentral includes its own messaging web application it can be used to chat, transfer files and optionally used for audio and video chat. It’s used to support two different usages :
378
-
379
- - *User-to-user and*
380
-
381
- - *user-to-computer communication.*
382
-
383
- 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.
384
-
385
-
386
-
387
-
388
-The chat app is standalone web application that is served by the MeshCentral server using a connection token and title in the URL. Once loaded in its own web frame, the messenger web application will get the connection token and title from the URL and proceed to connect to the URL using web socket. The same web socket relay that is used for browser-to-agent connections is also used in this case for browser-to-browser connections. The server relay acts the same and pipes both sessions together after sending the character `c` to both sides. At this point, the messenger application will show the remote user as connected and chat and file transfers can start. File transfers are just a set of binary messages sent over the web socket session with lots of JSON control messages.
389
-
390
-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.
391
-
392
-
393
-
394
-
395
-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.
396
-
397
-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.
398
-
399
-## 💡 Additional Resources
400
-
401
-In addition to this document, there are a growing set of MeshCentral resources at :
402
-
403
- - **[https://www.meshcommander.com/meshcentral2.](https://www.meshcommander.com/meshcentral2)** :
404
-
405
- This includes an Installer’s documents, a User’s Guide and plenty of YouTube tutorial videos.
406
-
407
-For developers, it’s best to start on the MeshCentral GitHub repository at :
408
-
409
- - **[ https://github.com/Ylianst/MeshCentral](https://github.com/Ylianst/MeshCentral)**
410
-
411
-If any issues are found, it’s best to create a new issue in GitHub or mail [ylianst@gmail.com](mailto:ylianst@gmail.com)
412
-
413
-## 🏁 Conclusion
414
-
415
-MeshCentral is a free, open source and powerful remote management solution that is cross- platform. In this document, we have covered the goals, overview, design and some details of the software. It’s hoped that this document will encourage developers to take a look at MeshCentral for more usages and review its security in detail. MeshCentral’s use of modern web technologies make it a unique and amazing solution for remote management of computers. As with any good software, MeshCentral will continue to be updated and evolve.
416
-
417
-## License
418
-
419
-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](https://www.apache.org/licenses/LICENSE-2.0)
420
-
421
-## PDF and ODT handout(s).
422
-
423
-[MeshCentral Guide](https://meshcentral.com/docs/MeshCentral2UserGuide.pdf)
424
-
425
-MeshCmd Guide [as .pdf](https://meshcentral.com/docs/MeshCmdUserGuide.pdf) [as .odt](../documents/MeshCentral%20Design%20&%20Architecture%20v0.0.4.odt)
\ No newline at end of file
docs/docs/documents/MeshCentral ADFS SSO Guide 0.0.1.odt
Binary files a/docs/docs/documents/MeshCentral ADFS SSO Guide 0.0.1.odt and /dev/null differ
docs/docs/documents/MeshCentral Design & Architecture v0.0.4.odt
Binary files a/docs/docs/documents/MeshCentral Design & Architecture v0.0.4.odt and /dev/null differ
docs/docs/documents/MeshCentral Install Guide v0.1.0.odt
Binary files a/docs/docs/documents/MeshCentral Install Guide v0.1.0.odt and /dev/null differ
docs/docs/documents/MeshCentral Intel AMT Guide v0.0.1.odt
Binary files a/docs/docs/documents/MeshCentral Intel AMT Guide v0.0.1.odt and /dev/null differ
docs/docs/documents/MeshCentral Router User Guide v0.0.2.odt
Binary files a/docs/docs/documents/MeshCentral Router User Guide v0.0.2.odt and /dev/null differ
docs/docs/documents/MeshCentral Satellite v0.0.1.odt
Binary files a/docs/docs/documents/MeshCentral Satellite v0.0.1.odt and /dev/null differ
docs/docs/documents/MeshCentral User's Guide v0.2.9.odt
Binary files a/docs/docs/documents/MeshCentral User's Guide v0.2.9.odt and /dev/null differ
docs/docs/documents/MeshCmd User's Guide v0.0.3.odt
Binary files a/docs/docs/documents/MeshCmd User's Guide v0.0.3.odt and /dev/null differ
docs/docs/documents/MeshCtrl User's Guide v0.0.1.odt
Binary files a/docs/docs/documents/MeshCtrl User's Guide v0.0.1.odt and /dev/null differ
docs/docs/how-to-contribute/images/translation-msg-output.png
Binary files a/docs/docs/how-to-contribute/images/translation-msg-output.png and /dev/null differ
docs/docs/how-to-contribute/index.md
deleted
-99
@@ -1,99 +0,0 @@
1
-# Contribute to MeshCentral
2
-
3
----
4
-## 📤 Contributing to MeshCentral via GitHub Pull Request
5
-
6
-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 :
7
-
8
-1. **Fork the Repository :**
9
-
10
- > Start by forking the [MeshCentral](https://github.com/Ylianst/MeshCentral) repository on GitHub.
11
-
12
- > This creates a copy of the repository under your own GitHub account, allowing you to make changes without affecting the original project.
13
-
14
-2. **Make Your Changes**
15
-
16
- > - In your forked repository, create a new branch to keep your changes organized. This helps in managing different contributions separately.
17
-
18
- > - Make the necessary changes in your repository. This could involve updating documentation files or modifying code to add new features or fix bugs.
19
-
20
-3. **Review Your Changes :**
21
-
22
- > Before submitting your work, carefully review the changes you’ve made. Check the "Files Changed" section on GitHub to ensure that all modifications are intended and correctly implemented.
23
-
24
-4. **Submit a Pull Request**
25
-
26
- > - Once your changes are ready and reviewed, submit a pull request (PR) from your branch to the `master` branch of the main MeshCentral repository.
27
- > - When creating the pull request, provide a clear and detailed description of what changes have been made and why. This helps maintainers understand the purpose of your contributions.
28
-
29
-5. **Wait for Review :**
30
-
31
- > 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.
32
-
33
-6. **Respond to Feedback :**
34
-
35
- > The maintainer may request further modifications or provide feedback on your pull request. Be prepared to make additional changes based on their suggestions to ensure that your contribution meets the project’s standards and requirements.
36
-
37
-7. **Final Steps :**
38
-
39
- > 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!
40
-
41
----
42
-
43
-## 🗣️ Contribute to MeshCentral's Multilingual Support
44
-
45
-To make MeshCentral multilingual, your contributions are crucial. Follow these steps to translate the interface into various languages.
46
-
47
-1. **Remove Local Translations :**
48
-
49
- > 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.
50
-
51
-2. **Access MeshCentral :**
52
-
53
- > Ensure you are logged into MeshCentral.
54
-
55
-3. **Open Translation Tool:**
56
-
57
- > Visit `https://YOURMESHCENTRALSERVER.COM/translator.htm` to access the translation interface.
58
-
59
-4. **Choose a Language :**
60
-
61
- > Select the language you wish to translate from the list provided.
62
-
63
-5. **Translate Text :**
64
-
65
- > 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.
66
-
67
-6. **Enter Translations :**
68
-
69
- > For each text segment, enter your translation in the bottom box (not the top one) and click `SET (F1)`.
70
-
71
-7. **Repeat Translation :** Continue translating by repeating steps 5 and 6 for other texts as desired.
72
-
73
-8. **Save and Apply Translations**
74
-
75
- > - Click `SAVE TO SERVER (F3)` to save your translations to `meshcentral-data/translate.json` locally in your MeshCentral server.
76
- > - Optionally, click `SAVE TO FILE (F4)` to download the `translate.json` file for offline review or sharing.
77
-
78
-9. **Deploy Translations :**
79
-
80
- > 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.
81
-
82
- > 
83
-
84
-10. **Finalize Changes :**
85
-
86
- > It’s crucial to restart MeshCentral to ensure that the translated files are picked up correctly.
87
-
88
-11. **Share your translations :**
89
-
90
- > Once a language translation is complete, take the latest `translation.json` and share it by emailing it to the maintainer (Ylianst, `ylianst@gmail.com`) or by submitting it to the MeshCentral GitHub repository via a pull request.
91
-
92
----
93
-
94
-!!! note
95
- Additional Information :
96
-
97
- If you make any changes to `default.handlebars`, run the translate server to propagate these modifications to the language-specific handlebar files located in `node_modules/meshcentral/views/translations`.
98
-
99
-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.
docs/docs/images/2022-08-04-18-19-19.png
Binary files a/docs/docs/images/2022-08-04-18-19-19.png and /dev/null differ
docs/docs/images/back.png
Binary files a/docs/docs/images/back.png and /dev/null differ
docs/docs/images/favicon-303x303.png
Binary files a/docs/docs/images/favicon-303x303.png and /dev/null differ
docs/docs/images/favicon.ico
Binary files a/docs/docs/images/favicon.ico and /dev/null differ
docs/docs/index.md
deleted
-76
@@ -1,76 +0,0 @@
1
-# MeshCentral Documentation
2
-
3
-## ❓ About
4
-
5
-MeshCentral is a versatile, open-source computer management platform. By hosting your own MeshCentral server, you can remotely manage computers from anywhere in the world. The platform provides a seamless, web-based experience for remote desktop access, terminal control, and file management.
6
-
7
-!!! tip
8
- For more information, [visit MeshCentral.com](https://meshcentral.com).
9
-
10
-## 🌐 Social Media
11
-
12
-  [YouTube](https://www.youtube.com/channel/UCJWz607A8EVlkilzcrb-GKg/videos)
13
-  [Reddit](https://www.reddit.com/r/MeshCentral/)
14
-  [Telegram](https://t.me/meshcentral)
15
-  [Discord](https://discord.gg/wF9UT3Vjdj)
16
-  [BlueSky](https://bsky.app/profile/meshcentral.bsky.social)
17
-  [BlogSpot](https://meshcentral2.blogspot.com/)
18
-
19
-## 📚 Documentation
20
-
21
-The [User's Guide](meshcentral/index.md) 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.
22
-
23
-The [Installation Guide](install/quickstart.md) 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.
24
-
25
-The [Design and Architecture Guide](design/index.md) 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.
26
-
27
-## 📺 Video Tutorials
28
-
29
-You can watch many tutorial videos on the [MeshCentral YouTube Channel](https://www.youtube.com/channel/UCJWz607A8EVlkilzcrb-GKg/videos). Here are some essential ones to get you started :
30
-
31
-**[MeshCentral - Installation](https://www.youtube.com/results?search_query=MeshCentral+Installation)**
32
-Installing MeshCentral on **Windows**, **Linux**, and **macOS**.
33
-
34
-
35
-**[MeshCentral - Basics](https://www.youtube.com/results?search_query=MeshCentral+Basics)**
36
-Learn how to install the agent and use remote **desktop**, **terminal**, and **file access** features.
37
-
38
-
39
-**[MeshCentral - Two Factor Authentication](https://www.youtube.com/results?search_query=MeshCentral+Two+Factor+Authentication)**
40
-Secure your MeshCentral instance with **two-factor authentication**.
41
-
42
-
43
-**[MeshCentral - NGINX Reverse Proxy](https://www.youtube.com/results?search_query=MeshCentral+NGINX+Reverse+Proxy)**
44
-Configure MeshCentral with an **NGINX reverse proxy** for better security and scalability.
45
-
46
-
47
-**[MeshCentral - Android](https://www.youtube.com/results?search_query=MeshCentral+Android)**
48
-Install and use the **MeshCentral Android agent** for mobile device management.
49
-
50
-
51
-**[MeshCentral - Basics](https://www.youtube.com/results?search_query=MeshCentral+Router+Port+Mapping)**
52
-Use **MeshCentral Router** to **port map TCP connections** securely.
53
-
54
-
55
-## 💬 Feedback
56
-
57
-If you encounter a problem or have a suggestion to improve MeshCentral, you may want to create a [GitHub issue](https://github.com/Ylianst/MeshCentral/issues/).<br>
58
-If you are filing a problem report, you should include:
59
-
60
-* The version of MeshCentral you are using.
61
-> For example: v1.1.56.
62
-* The operating system and its version.
63
-> For example: Debian 12.
64
-* Any troubleshooting you took to resolve the issue yourself.
65
-> For example: Reinstalling MeshCentral. (and your OS!)
66
-* Any other similar reports.
67
-> For example: other GitHub issues.
68
-* The observed output.
69
-* The expected output.
70
-
71
-If you are having issues with the following other products, you should file a report on their respective issue pages
72
-[MeshAgent](https://github.com/Ylianst/MeshAgent/issues)
73
-[MeshRouter](https://github.com/Ylianst/MeshCentralRouter/issues)
74
-License
75
-
76
-This software is licensed under [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0).
docs/docs/install/abstract.md
deleted
-16
@@ -1,16 +0,0 @@
1
-# Installation
2
-
3
-## 🧾 Abstract
4
-
5
-These guides are specifically intended to help users install and configure MeshCentral.<br>
6
-Once installed, you can take a look at the MeshCentral user’s guide,<br>
7
-for information on how to configure MeshCentral for your specific use.<br>
8
-In this document, we will look at installing MeshCentral on different operating systems like:
9
-
10
-And remember! The `config.json` is case insensitive in its keys.
11
-
12
- - 📢 **[Quick-start](./quickstart.md)**
13
-
14
- - 🧐 **[Advanced Information](./advanced.md)**
15
-
16
- - 🪟 **[Windows-specific](./windows.md)**
docs/docs/install/advanced.md
deleted
-91
@@ -1,91 +0,0 @@
1
-# 📦 NPM Installation for Advanced Users
2
-
3
-
4
-
5
-## Prerequisites and Verification
6
-
7
-Before beginning the installation, ensure **Node.js** and **NPM** (Node Package Manager) are installed on your host operating system.
8
-
9
-If your server is behind an HTTP/HTTPS proxy, you may need to configure NPM's proxy settings.
10
-
11
-### 1\. Verify Node.js and NPM
12
-
13
-Open your command-line terminal (CMD/PowerShell on Windows, or Shell on Linux) and run the following commands to check the installed versions:
14
-
15
- * **Node.js:**
16
- ```shell
17
- node -v
18
- ```
19
- * **NPM:**
20
- ```shell
21
- npm -v
22
- ```
23
-
24
------
25
-
26
-### 2\. Configure Proxy Settings (If Applicable)
27
-
28
-If your server requires a proxy to access the internet, you must set the proxy configurations for NPM. **Skip this step if not needed.**
29
-
30
-```shell
31
-# Set HTTP proxy
32
-npm config set proxy http://proxy.com:88
33
-# Set HTTPS proxy
34
-npm config set https-proxy http://proxy.com:88
35
-```
36
-
37
------
38
-
39
-## MeshCentral Installation
40
-
41
-### 3\. Install MeshCentral
42
-
43
-Create a dedicated directory for the installation, change into it, and use NPM to install the MeshCentral package.
44
-
45
-**Recommendation:** On Linux, use the `/opt` directory.
46
-
47
-> ⚠️ **Important:** Do not use `sudo` when executing the `npm install meshcentral` command.
48
-
49
-```shell
50
-# Create the directory
51
-mkdir -p /opt/meshcentral
52
-# Move into the directory
53
-cd /opt/meshcentral
54
-# Install MeshCentral
55
-npm install meshcentral
56
-```
57
-
58
------
59
-
60
-### 4\. Start the Server
61
-
62
-Once the download is complete, start the MeshCentral server.
63
-
64
-> ⚠️ **Crucial:** **Do not** `cd` into the `node_modules/meshcentral` directory to run the server. Running it from the directory **above** `node_modules` is required for features like auto-install and self-update to function correctly.
65
-
66
-```shell
67
-node node_modules/meshcentral [arguments]
68
-```
69
-
70
-> **LAN-Only Mode:** If you run the command without arguments, MeshCentral will default to **LAN-only mode**, meaning you can only manage computers on the local network.
71
-
72
------
73
-
74
-### 5\. Configure for WAN/Internet Access (Optional)
75
-
76
-To manage computers over the internet (**WAN** or **Hybrid Mode**), your server needs a **static IP** or a **DNS record** that resolves to its public address. This is how remote mesh agents "call home."
77
-
78
-While command-line parameters exist, it's **highly recommended to use a configuration file** for persistent settings.
79
-
80
-Here are examples of starting the server and generating initial certificates for a public address:
81
-
82
-```shell
83
-# Using a domain name
84
-node node_modules/meshcentral --cert servername.domain.com
85
-# Using an IP address
86
-node node_modules/meshcentral --cert 1.2.3.4
87
-```
88
-
89
-> **Note:** The first time you run in WAN or Hybrid Mode, MeshCentral will generate necessary **certificates**, which may take a few minutes.
90
-
91
-Once running, immediately create your **admin account** by navigating to `https://127.0.0.1` (or your public hostname) in a web browser.
\ No newline at end of file
docs/docs/install/container.md
deleted
-107
@@ -1,107 +0,0 @@
1
-# 🐳 Container (OCI-specification).
2
-
3
-[Open Container Initiative](https://opencontainers.org/)
4
-
5
-The following section explains possible ways to install MeshCentral locally with the use of Docker or Podman.
6
-For the syntax, docker will be used as default. This is done because podman also supports this syntax.<br>
7
-
8
-🔗 References:
9
-
10
-- [Docker](https://www.docker.com/)
11
-- [Podman](https://podman.io/)
12
-
13
-!!!warning
14
- Do not use the built-in MeshCentral update functionality (when using containers).<br>
15
- Update the container the 'docker way', by updating the image itself.
16
-
17
-### 🏷️ Basic Tags:
18
-
19
-| Tag-name | Explanation |
20
-|--------|-----|
21
-| `master` | This tag belongs to the image which is built on every new commit to the main branch, therefor it has the latest code. |
22
-| `latest` | This tag takes the latest released version of MeshCentral. |
23
-| `1.1.51` | You can also specify the specific MeshCentral release with its tag, for example: `ghcr.io/ylianst/meshcentral:1.1.43` |
24
-
25
-### All Tags
26
-
27
-All master tags below follow the master branch of MeshCentral, the latest and version numbered versions follow the releases.
28
-
29
-| Tag-name | Explanation |
30
-| -------- | ----------- |
31
-| `master-slim` | Docker image with no database packages present, which makes it the most lean. Uses NeDB. |
32
-| `master-mongodb` | Docker image with the MongoDB packages installed. |
33
-| `master-postgresql` | Docker image with the PostgreSQL packages installed |
34
-| `master-mysql` | Docker image with the MySQL packages installed |
35
-| `1.1.51-slim` and `latest-slim` | Docker image with no database packages present, which makes it the most lean. Uses NeDB. |
36
-| `1.1.51-mongodb` and `latest-mongodb` | Docker image with the MongoDB packages installed. |
37
-| `1.1.51-postgresql` and `latest-postgresql` | Docker image with the PostgreSQL packages installed. |
38
-| `1.1.51-mysql` and `latest-mysql` | Docker image with the MySQL packages installed. |
39
-
40
-!!! note
41
- Refer to [this page](https://github.com/Ylianst/MeshCentral/pkgs/container/meshcentral) for more information on the container status.
42
-
43
-## 🐋 Docker/Podman
44
-
45
-For single-machine setups such as Docker and Podman.
46
-
47
-### Pulling the image:
48
-
49
-To pull the container image use the following container registry.
50
-
51
-```sh
52
-docker pull ghcr.io/ylianst/meshcentral:latest
53
-```
54
-
55
-### Docker CLI:
56
-
57
-If you want to run the container from the Terminal, you can use the following command:
58
-
59
-```sh linenums="1"
60
-docker run -d \
61
- --name meshcentral \
62
- --restart unless-stopped \
63
- -p 80:80 \
64
- -p 443:443 \
65
- -v data:/opt/meshcentral/meshcentral-data \
66
- -v user_files:/opt/meshcentral/meshcentral-files \
67
- -v backup:/opt/meshcentral/meshcentral-backups \
68
- -v web:/opt/meshcentral/meshcentral-web \
69
- ghcr.io/ylianst/meshcentral:latest
70
-```
71
-
72
-### Docker Compose:
73
-
74
-If you want to use a docker compose yaml file, please refer to the example below.
75
-
76
-```yaml linenums="1"
77
-services:
78
- meshcentral:
79
- image: ghcr.io/ylianst/meshcentral:latest
80
- environment:
81
- - DYNAMIC_CONFIG=false # Show the option but disable it by default, for safety.
82
- volumes:
83
- - meshcentral-data:/opt/meshcentral/meshcentral-data
84
- - meshcentral-files:/opt/meshcentral/meshcentral-files
85
- - meshcentral-web:/opt/meshcentral/meshcentral-web
86
- - meshcentral-backups:/opt/meshcentral/meshcentral-backups
87
- ports:
88
- - "80:80"
89
- - "443:443"
90
-volumes:
91
- meshcentral-data:
92
- meshcentral-files:
93
- meshcentral-web:
94
- meshcentral-backups:
95
-```
96
-
97
-Refer to [the Dockerfile](https://github.com/Ylianst/MeshCentral/blob/5032755c2971955161105922e723461385a6c874/docker/Dockerfile#L70-L123) for its environment variables.
98
-
99
-## ☸️ Kubernetes
100
-
101
-###
102
-
103
-> Using YAML deployment files.
104
-
105
-## 📚 Extra sources
106
-
107
-> [Github Docker Resources](https://github.com/Ylianst/MeshCentral/tree/master/docker)
\ No newline at end of file
docs/docs/install/database/local.md
deleted
-52
@@ -1,52 +0,0 @@
1
-# This section will go into how to configure a local database as backend.
2
-
3
-Following [the schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json) we make the following changes to our `config.json`.<br>
4
-Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.
5
-
6
-By default MeshCentral uses NeDB so therefor to change that to another database type, do the following:
7
-
8
----
9
-
10
-### MeshCentral Cheatsheet:
11
-
12
-Sqlite3:
13
-```json
14
-{
15
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
16
- "__comment__": "Omitted these keys to focus on the database",
17
- "settings": {
18
- "sqlite3": {
19
- "name": "meshcentral-db"
20
- }
21
- },
22
- "domains": {
23
- "": {
24
- "__comment__": "Omitted these keys to focus on the database",
25
- }
26
- },
27
- "_letsencrypt": {
28
- "__comment__": "Omitted these keys to focus on the database",
29
- }
30
-}
31
-```
32
-
33
-Acebase:
34
-```json
35
-{
36
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
37
- "__comment__": "Omitted these keys to focus on the database",
38
- "settings": {
39
- "acebase": {
40
- "sponsor": false
41
- }
42
- },
43
- "domains": {
44
- "": {
45
- "__comment__": "Omitted these keys to focus on the database",
46
- }
47
- },
48
- "_letsencrypt": {
49
- "__comment__": "Omitted these keys to focus on the database",
50
- }
51
-}
52
-```
\ No newline at end of file
docs/docs/install/database/mariadb.md
deleted
-80
@@ -1,84 +0,0 @@
1
-# This section will go into how to configure MySQL/MariaDB as a database backend.
2
-
3
-Following [the schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json) we make the following changes to our `config.json`.<br>
4
-Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.
5
-
6
----
7
-
8
-### MeshCentral Cheatsheet:
9
-
10
-Database specific:
11
-
12
-MariaDB:
13
-```json
14
-{
15
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
16
- "__comment__": "Omitted these keys to focus on the database",
17
- "settings": {
18
- "mariaDB": {
19
- "host": "my-mariadb-hostname",
20
- "port": "3306",
21
- "user": "my-mariadb-user",
22
- "password": "my-mariadb-password",
23
- "database": "meshcentral-database"
24
- }
25
- },
26
- "domains": {
27
- "": {
28
- "__comment__": "Omitted these keys to focus on the database",
29
- }
30
- },
31
- "_letsencrypt": {
32
- "__comment__": "Omitted these keys to focus on the database",
33
- }
34
-}
35
-```
36
-
37
-Mysql:
38
-```json
39
-{
40
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
41
- "__comment__": "Omitted these keys to focus on the database",
42
- "settings": {
43
- "mySQL": {
44
- "host": "my-mysql-hostname",
45
- "port": "3306",
46
- "user": "my-mysql-user",
47
- "password": "my-mysql-password",
48
- "database": "meshcentral-database"
49
- }
50
- },
51
- "domains": {
52
- "": {
53
- "__comment__": "Omitted these keys to focus on the database",
54
- }
55
- },
56
- "_letsencrypt": {
57
- "__comment__": "Omitted these keys to focus on the database",
58
- }
59
-}
60
-```
61
-
62
-### MariaDB/MySQL Cheatsheet:
63
-
64
-```bash
65
-mariadb -u root -p
66
-```
67
-or
68
-```bash
69
-mysql -u root -p
70
-```
71
-
72
-```sql
73
-CREATE DATABASE meshcentral;
74
-
75
-CREATE USER 'meshcentral'@'localhost' IDENTIFIED BY 'my-very-secure-password';
76
-
77
-GRANT ALL PRIVILEGES ON meshcentral.* TO 'meshcentral'@'localhost';
78
-
79
-FLUSH PRIVILEGES;
80
-```
\ No newline at end of file
docs/docs/install/database/mongodb.md
deleted
-28
@@ -1,28 +0,0 @@
1
-# This section will go into how to configure MongoDB as a database backend.
2
-
3
-Following [the schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json) we make the following changes to our `config.json`.<br>
4
-Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.
5
-
6
----
7
-
8
-### MeshCentral Cheatsheet:
9
-
10
-MongoDB is configured using the MongoDB connection string.
11
-
12
-```json
13
-{
14
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
15
- "__comment__": "Omitted these keys to focus on the database",
16
- "settings": {
17
- "mongoDb": "mongodb://localhost:27017/meshcentral"
18
- },
19
- "domains": {
20
- "": {
21
- "__comment__": "Omitted these keys to focus on the database",
22
- }
23
- },
24
- "_letsencrypt": {
25
- "__comment__": "Omitted these keys to focus on the database",
26
- }
27
-}
28
-```
\ No newline at end of file
docs/docs/install/database/postgresql.md
deleted
-54
@@ -1,57 +0,0 @@
1
-# This section will go into how to configure PostgreSQL as a database backend.
2
-
3
-Following [the schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json) we make the following changes to our `config.json`.<br>
4
-Some requires keys have been omitted to further the focus on database configuration. Don't remove these as well.
5
-
6
----
7
-
8
-### MeshCentral Cheatsheet:
9
-
10
-The postgres installation inside `settings` is rather straightforward if you are familiar with it on MeshCentral its side.
11
-
12
-```json
13
-{
14
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
15
- "__comment__": "Omitted these keys to focus on the database",
16
- "settings": {
17
- "postgres": {
18
- "host": "my-postgresql-hostname",
19
- "port": "5432",
20
- "user": "my-postgresql-user",
21
- "password": "my-postgresql-password",
22
- "database": "meshcentral-database"
23
- }
24
- },
25
- "domains": {
26
- "": {
27
- "__comment__": "Omitted these keys to focus on the database",
28
- }
29
- },
30
- "_letsencrypt": {
31
- "__comment__": "Omitted these keys to focus on the database",
32
- }
33
-}
34
-```
35
-
36
-> More options are available if needed. Refer to the schema above.
37
-
38
-### Postgres Cheatsheet
39
-
40
-```bash
41
-# Log into the server
42
-psql -U postgres
43
-```
44
-
45
-```sql
46
-
47
-postgres=# CREATE USER meshcentral WITH PASSWORD 'your-very-strong-password';
48
-CREATE ROLE
49
-
50
-postgres=# CREATE DATABASE meshcentral OWNER meshcentral;
51
-CREATE DATABASE
52
-
53
-postgres=# exit
54
-```
\ No newline at end of file
docs/docs/install/images/2022-05-16-23-45-01.jpg
Binary files a/docs/docs/install/images/2022-05-16-23-45-01.jpg and /dev/null differ
docs/docs/install/images/2022-05-16-23-47-10.jpg
Binary files a/docs/docs/install/images/2022-05-16-23-47-10.jpg and /dev/null differ
docs/docs/install/images/2022-05-16-23-47-36.jpg
Binary files a/docs/docs/install/images/2022-05-16-23-47-36.jpg and /dev/null differ
docs/docs/install/images/2022-05-16-23-53-08.jpg
Binary files a/docs/docs/install/images/2022-05-16-23-53-08.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-01-10.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-01-10.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-01-52.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-01-52.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-02-25.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-02-25.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-03-59.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-03-59.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-19-19.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-19-19.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-29-07.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-29-07.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-34-12.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-34-12.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-34-24.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-34-24.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-34-37.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-34-37.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-36-30.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-36-30.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-36-52.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-36-52.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-37-05.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-37-05.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-37-21.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-37-21.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-37-35.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-37-35.jpg and /dev/null differ
docs/docs/install/images/2022-05-17-00-37-46.jpg
Binary files a/docs/docs/install/images/2022-05-17-00-37-46.jpg and /dev/null differ
docs/docs/install/images/2022-05-17_000542.jpg
Binary files a/docs/docs/install/images/2022-05-17_000542.jpg and /dev/null differ
docs/docs/install/images/2022-05-17_003521.jpg
Binary files a/docs/docs/install/images/2022-05-17_003521.jpg and /dev/null differ
docs/docs/install/quickstart.md
deleted
-90
@@ -1,90 +0,0 @@
1
-# Quickstart
2
-
3
-## 🚀 Quick Start Guide: Basic NPM Installation
4
-
5
-MeshCentral is platform-agnostic, running almost anywhere thanks to being primarily written in JavaScript. This guide covers the simplest way to get started using **NPM**.
6
-
7
-### 🛠️ Basic Setup
8
-
9
-The only prerequisites are **Node.js** and **npm**.
10
-
11
------
12
-
13
-#### 1\. Install Node.js
14
-
15
- * **Linux:** Find installation instructions for your distribution [here](https://nodejs.org/en/download/package-manager/all).
16
- * **Windows:** Download the installer from the official site [here](https://nodejs.org/en).
17
-
18
-> 🪟 **Windows Users:** If you prefer an automated setup, you can skip the manual installation and download the **Windows MeshCentral Installer**. However, this is **not recommended for advanced users**.
19
-> [Download Windows MeshCentral Installer](https://meshcentral.com/tools/MeshCentralInstaller.exe)
20
-
21
------
22
-
23
-#### 2\. Install and Start MeshCentral
24
-
25
-Create a dedicated directory (e.g., `/opt/meshcentral`) and run the following commands in your terminal.
26
-
27
-> ⚠️ **Do not** use `sudo` with the `npm install meshcentral` command.
28
-
29
-```shell
30
-# Example: Create and move into the directory
31
-mkdir -p /opt/meshcentral
32
-cd /opt/meshcentral
33
-
34
-# Install the MeshCentral package
35
-npm install meshcentral
36
-
37
-# Start the server
38
-node node_modules/meshcentral
39
-```
40
-
41
-That's it\! MeshCentral will now set itself up and begin managing computers on your **local network** that have the MeshAgent installed.
42
-
43
-#### Running as a Service
44
-
45
-To run MeshCentral as a persistent background service (recommended for production environments), use the --install argument when starting the server. Consult the MeshCentral documentation for OS-specific service setup details.
46
-
47
------
48
-
49
-### ⚙️ Configuration and Customization
50
-
51
-#### Default Mode and Initial Access
52
-
53
-By default, MeshCentral starts in **LAN-only mode**. Agents use local network multicasting to find the server.
54
-
55
- * The first user account you create upon accessing the server will automatically become the **server administrator**. Access the login page in your web browser and create your account right away.
56
- * Once installed, server settings are stored in the **`config.json`** file, which is located inside the **`meshcentral-data`** folder.
57
-
58
-#### Advanced Configuration
59
-
60
-The **`config.json`** file holds hundreds of options for deep customization, including:
61
-
62
- * Switching the server from LAN-only to **WAN/Hybrid mode** by setting a known DNS name.
63
- * Customizing the server with your own **branding**.
64
- * Setting up an **SMTP email server** or **SMS services**.
65
-
66
-The configuration file must be valid **JSON**. You can use an online tool or utilities like `jq` to validate its format.
67
-
68
-You can find sample configuration files on the GitHub repository for reference:
69
-
70
- * [Simple sample config](https://github.com/Ylianst/MeshCentral/blob/master/sample-config.json)
71
- * [Advanced sample config](https://github.com/Ylianst/MeshCentral/blob/master/sample-config-advanced.json)
72
- * [Full config schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json)
73
-
74
------
75
-
76
-### Database and Scaling Notes
77
-
78
- * **Database:** By default, MeshCentral uses **NeDB**, its built-in database. For advanced use cases and better performance, it's recommended to switch to **MongoDB** or an SQL-based solution like **Postgresql**.
79
- * **Hardware:** MeshCentral is very lightweight. You can run a server capable of managing a few hundred devices on a small platform like a **Raspberry Pi** or an **AWS t3.nano** instance running Linux.
80
- * **Service Mode:** To run the server as a background service, start it with the `--help` argument to view options for background installation.
81
-
82
-For a visual guide, check out the official [YouTube Tutorial Videos](https://www.youtube.com/@MeshCentral/videos).
83
-
84
-\<div class="video-wrapper"\>
85
- \<iframe src="[https://www.youtube.com/embed/LSiWuu71k\_U](https://www.youtube.com/embed/LSiWuu71k_U)" frameborder="0" allowfullscreen\>\</iframe\>
86
-\</div\>
87
-
88
------
89
-
90
-Do you want to know more about configuring the server for WAN access or switching to a different database?
\ No newline at end of file
docs/docs/install/security/crowdsec.md
deleted
-9
@@ -1,9 +0,0 @@
1
-# 🛡️ Crowdsec
2
-
3
-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.
4
-
5
-## 🎬 Video Walkthrough
6
-
7
-<div class="video-wrapper">
8
- <iframe width="320" height="180" src="https://www.youtube.com/embed/TVKF9gBJFCE" frameborder="0" allowfullscreen></iframe>
9
-</div>
\ No newline at end of file
docs/docs/install/security/secure.md
deleted
-103
@@ -1,103 +0,0 @@
1
-# Secure
2
-
3
-## 🔒 Increased Security Installation on Debian/Ubuntu
4
-
5
-For enhanced security on Debian-based Linux distributions (like Ubuntu), it's best practice to run **MeshCentral** under a dedicated, low-privilege user account. This prevents the server from making unauthorized changes to the system.
6
-
7
-> ⚠️ **Important:** Running with restricted privileges disables MeshCentral's **self-update capability**. Updates must be performed manually. Additionally, this setup **requires using an external database (like MongoDB)** because the primary data folder will be read-only.
8
-
9
------
10
-
11
-### 1\. Create a Low-Privilege User
12
-
13
-Start by creating a system user named `meshcentral`. This user will be restricted from logging in and changing files outside its designated directory.
14
-
15
-```shell
16
-sudo useradd -r -d /opt/meshcentral -s /sbin/nologin meshcentral
17
-```
18
-
19
-### 2\. Install MeshCentral
20
-
21
-Next, create the installation directory and install the package using NPM.
22
-
23
-```shell
24
-# Create the installation folder
25
-sudo mkdir /opt/meshcentral
26
-
27
-# Change to the installation directory
28
-cd /opt/meshcentral
29
-
30
-# Install MeshCentral (as the created user)
31
-sudo -u meshcentral npm install meshcentral
32
-```
33
-
34
-### 3\. Initialize Data Folders
35
-
36
-Run the server once under the new low-privilege user to generate the necessary data folders and install any initial dependencies.
37
-
38
-```shell
39
-# Run once as the meshcentral user
40
-sudo -u meshcentral node ./node_modules/meshcentral
41
-```
42
-
43
-Once the server is running and the folders have been created, press **CTRL-C** to stop the process.
44
-
45
-### 4\. Restrict Permissions
46
-
47
-Now, set the ownership and permissions to ensure the `meshcentral` user has **read-only access** to the application code, enhancing security.
48
-
49
-```shell
50
-# Change ownership of all files to the meshcentral user and group
51
-sudo chown -R meshcentral:meshcentral /opt/meshcentral
52
-
53
-# Set read/execute permissions for the meshcentral user on data folders
54
-# Note: meshcentral-* refers to meshcentral-data, meshcentral-files, etc.
55
-sudo chmod -R 755 /opt/meshcentral/
56
-```
57
-
58
-### 5\. Adjust Write Permissions for Functionality (Optional)
59
-
60
-In a restricted environment, you need to explicitly grant write access to specific subfolders the server needs to modify during operation.
61
-
62
-#### A. File Upload/Download
63
-
64
-If you plan to use MeshCentral's file transfer features, the server needs to read and write to the `meshcentral-files` folder:
65
-
66
-```shell
67
-sudo chmod -R 755 /opt/meshcentral/meshcentral-files
68
-```
69
-
70
-#### B. Let's Encrypt Support
71
-
72
-If you plan to use MeshCentral's built-in **Let's Encrypt** support, you must make its certificate folder writable to avoid `ACCES: permission denied` exceptions:
73
-
74
-```shell
75
-# Create the necessary sub-folders if they don't exist
76
-sudo mkdir -p /opt/meshcentral/meshcentral-data/letsencrypt
77
-
78
-# Grant write access to the letsencrypt folder
79
-sudo chmod -R 775 /opt/meshcentral/meshcentral-data/letsencrypt
80
-```
81
-
82
-### 6\. Manual Server Update
83
-
84
-Because the `meshcentral` user lacks write access to the `/node_modules` directory, the server cannot update itself. To perform a manual update:
85
-
86
-1. Use `systemctl` (or your service manager) to **stop** the MeshCentral server process.
87
-2. Run the following commands:
88
-
89
-<!-- end list -->
90
-
91
-```shell
92
-cd /opt/meshcentral
93
-
94
-# Update the MeshCentral package via NPM (requires sudo/root privileges)
95
-sudo npm install meshcentral
96
-
97
-# Re-set ownership to the meshcentral user
98
-sudo chown -R meshcentral:meshcentral /opt/meshcentral
99
-```
100
-
101
-3. Use `systemctl` to **restart** the MeshCentral server.
102
-
103
-This process updates the server to the latest version on NPM and reapplies the strict permissions.
\ No newline at end of file
docs/docs/install/windows.md
deleted
-71
@@ -1,71 +0,0 @@
1
-# Quickstart
2
-
3
-## 🪟 Quick Start on Windows with the Installer
4
-
5
-For Microsoft Windows users, the easiest way to install MeshCentral is by using the dedicated installer tool. This tool automates the setup, including checking for and installing **Node.js** if necessary.
6
-
7
-You can download the MeshCentral installer from the official website or by clicking [this link](https://www.meshcommander.com/meshcentral2).
8
-
9
-> **Recommendation:** We advise running the installer on a modern version of Windows (e.g., Windows 8.1, Windows 10, or Windows Server 2012 or newer).
10
-
11
-### Installation Prompts Explained
12
-
13
-The installer will guide you through a few key settings:
14
-
15
-| Setting | Description |
16
-| :--- | :--- |
17
-| **Multi-user Server** | **Enabled (Checked):** The server is open to the public. Users can create accounts and manage their own devices. **Disabled (Unchecked):** The server is limited to a single-user mode, with no login screen, accessible only from the server host machine. |
18
-| **Auto-update Server** | **Enabled:** The server automatically checks for new releases daily (typically between 00:00 and 01:00 local time) and performs an update. The server will be inaccessible during the update process. |
19
-| **Server Mode** | Choose how agents find the server: |
20
-| *LAN Mode* | Recommended for small, local networks. The server does not need a fixed IP or DNS name. |
21
-| *WAN/Hybrid Mode* | Required for managing devices over the internet. You **must** enter the server's public **DNS name** or **static IP address** into the **Server Name** field. This name must be correct or agents will fail to connect. If unsure, start with **LAN Mode**. |
22
-
23
-Once installed, MeshCentral runs as a **background Windows Service** and can be accessed via the web browser link provided by the installer.
24
-
25
-### Updating and Maintenance
26
-
27
-The installation tool can be run again at any time to:
28
-
29
-* **Perform a Server Update:** The tool compares your installed version to the latest one on NPM.
30
-* **Re-install** the server.
31
-* **Un-install** the server.
32
-
33
----
34
-
35
-## 🔒 Windows Defender Firewall Settings
36
-
37
-The installer automatically configures the **Windows Defender Firewall** to allow MeshCentral to accept incoming connections.
38
-
39
-By default, MeshCentral uses the following ports:
40
-* **TCP Ports:** **80** (HTTP), **443** (HTTPS), and **4433** (Intel® AMT CIRA).
41
-* **UDP Port:** **16990** (Added for server discovery in LAN or Hybrid mode).
42
-
43
-If you performed an advanced NPM installation or need to change the default ports, you may need to manually modify these firewall rules.
44
-
45
-### Accessing Firewall Settings
46
-
47
-1. Open **Control Panel**.
48
-2. Go to **System and Security**.
49
-3. Click **Windows Defender Firewall**.
50
-4. Click **Advanced Settings** on the left side.
51
-5. Select **Inbound Rules**.
52
-
53
-If you used the installer, you should see rules named **`MeshCentral Server TCP ports`** and optionally **`MeshCentral Server UDP ports`**.
54
-
55
-### 1. Editing Existing Rules
56
-
57
-To change the allowed ports (e.g., if you changed the MeshCentral configuration):
58
-1. **Double-click** the existing rule (e.g., `MeshCentral Server TCP ports`).
59
-2. Go to the **Protocols and Ports** tab.
60
-3. Modify the **Local ports** field.
61
-
62
-### 2. Adding New Rules
63
-
64
-To create a new inbound firewall rule:
65
-1. Click **New Rule...** on the right side.
66
-2. Select **Port** and click **Next**.
67
-3. Choose either **TCP** or **UDP**.
68
-4. Select **Specific local ports** and enter the port numbers (e.g., `80, 443, 4433`). Click **Next**.
69
-5. Ensure **Allow the connection** is selected and click **Next**.
70
-6. Select the profiles (Domain, Private, Public) where the rule should apply and click **Next**.
71
-7. Enter a descriptive **Name** for the rule and click **Finish**.
\ No newline at end of file
docs/docs/intelamt/images/2022-05-16-23-08-15.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-08-15.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-10-40.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-10-40.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-10-59.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-10-59.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-11-24.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-11-24.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-12-04.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-12-04.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-12-37.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-12-37.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-12-58.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-12-58.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-13-44.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-13-44.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-14-42.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-14-42.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-15-04.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-15-04.png and /dev/null differ
docs/docs/intelamt/images/2022-05-16-23-16-05.png
Binary files a/docs/docs/intelamt/images/2022-05-16-23-16-05.png and /dev/null differ
docs/docs/intelamt/images/amtprovisioningserver.png
Binary files a/docs/docs/intelamt/images/amtprovisioningserver.png and /dev/null differ
docs/docs/intelamt/index.md
deleted
-218
@@ -1,218 +0,0 @@
1
-# Intel AMT
2
-
3
-
4
-Intel AMT Guide [as .odt](../documents/MeshCentral%20Intel%20AMT%20Guide%20v0.0.1.odt)
5
-
6
-## Video Walkthrough
7
-
8
-<div class="video-wrapper">
9
- <iframe width="320" height="180" src="https://www.youtube.com/embed/naWKE3rT6e8" frameborder="0" allowfullscreen></iframe>
10
- <iframe width="320" height="180" src="https://www.youtube.com/embed/TaKsFEVaMpg" frameborder="0" allowfullscreen></iframe>
11
-</div>
12
-
13
-## Abstract
14
-
15
-This user guide contains all essential information for activating and using Intel® Active Management Technology (Intel® AMT) with MeshCentral. We will review how to activate, connect to and use Intel AMT features and how this benefit administrators that want to manage computers remotely. This document expect the reader to already be familiar with how to install and operate MeshCentral and have a basic understanding of how Intel® AMT works.
16
-
17
-## History of AMT
18
-
19
-<div class="video-wrapper">
20
- <iframe width="320" height="180" src="https://www.youtube.com/embed/_SXT0Gr4Mls" frameborder="0" allowfullscreen></iframe>
21
-</div>
22
-
23
-## Introduction
24
-
25
-MeshCentral is a free open source web-based remote computer management software and it fully supports Intel® Active Management Technology (Intel® AMT). MeshCentral does not require that computers it manages support Intel AMT, but if a remote computer has this capability, MeshCentral will make use of it.
26
-
27
-Intel AMT can be seen as a hardware based management agent that is built into some Intel PC’s. Once setup, Intel AMT can be used to remotely manage a computer regardless of the operating system health. It can be used to power on a computer when it’s in soft-off state or to provide enhanced monitoring and security to remote systems.
28
-
29
-Once setup, a computer can have up to management connections to MeshCentral. One of them by the Mesh Agent that lives in the operating system and another connection from Intel AMT. When remote management is made using an operating system agent, we call this “in-band management” and when management is done using a hardware based agent like Intel AMT, we call this “out-of-band management”
30
-
31
-
32
-
33
-MeshCentral can support computers that have either or both agents. So, you can setup a computer with just the Mesh Agent, just Intel AMT or both. In this document we will show how to install computers with both agent connections or with just Intel AMT. When Intel AMT is used alone, we call this “agent-less” as there will be no operating system software required to remotely manage the computer.
34
-
35
-The Mesh Agent and Intel® AMT have very different and complementary capabilities and so, it’s often beneficial to use both and one will offer features the other can’t provide. Here are some of the benefits each has to offer:
36
-
37
-Mesh Agent
38
-
39
- - Fast remote desktop / clipboard access.
40
- - Remote access to operating system files.
41
- - Remote chat and other OS features.
42
-
43
-Intel® AMT
44
-
45
- - Remote desktop even when the agent or operating system is not functional.
46
- - Remote access to BIOS.
47
- - Connectivity when soft-off / sleeping.
48
- - Remote power actions.
49
-
50
-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.
51
-
52
-## Bare-Metal Activation Server
53
-
54
-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.
55
-
56
-This bare-metal activation server is not enabled by default and only makes sense when activating devices on the local network.
57
-
58
-Once enabled, Intel AMT can send “hello” data to the MeshCentral provisioning server on port 9971 and MeshCentral will respond by connecting back, authenticating, and activating Intel AMT. MeshCentral will then log the event, add the device to a pre-defined agent-less device group and complete any remaining configuration. A trusted CA certificate is required to perform this operation fully automatically.
59
-
60
-
61
-
62
-## MeshCentral Group Types
63
-
64
-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.
65
-
66
-
67
-
68
-Note that if you use the OS agent to manage computers, you can also set and use Intel AMT. However, if you opt to create an Intel AMT only group, then Mesh Agents are not supported. One can create groups of both types in order to manage devices that have and don’t have the Mesh Agent installed.
69
-
70
-
71
-
72
-The main benefit of “Intel AMT only” group is if someone does not want to install a background agent on remote systems or already have a remote management solution and intends to only use MeshCentral to supplement the existing solution with Intel AMT features.
73
-
74
-Once a group is created, the links MeshCentral provides to on-board devices will change depending on the group type and how the server is setup. The device on-boarding links are located in the “My Devices” page, next to the group name.
75
-
76
-
77
-
78
-If the MeshCentral server is setup in “LAN mode” or “Hybrid mode”, options will be available to add computers on the local network. If you have an Intel AMT computer that is already activated, you can select the “Add Local” or “Scan Network” options in the “Intel AMT only” group type and start adding local network computers this way. If MeshCentral is in “WAN mode”, you will need to setup Intel AMT to connect back to MeshCentral using a feature called “Client Initiated Remote Access” or CIRA for short. We will cover that in a later section.
79
-
80
-## Client Initiated Remote Access & MPS server
81
-
82
-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.
83
-
84
-CIRA is great when remotely managing Intel AMT devices over the Internet through 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.
85
-
86
-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.
87
-
88
-
89
-
90
-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:
91
-
92
-<https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/HTMLDocuments/MPSDocuments/Intel%20AMT%20Port%20Forwarding%20Protocol%20Reference%20Manual.pdf>
93
-
94
-It’s not necessary to know or understand the details of this protocol, MeshCentral will take care of handling this. In Intel AMT nomenclature, the server that receives a CIRA connection is called a “Management Presence Server” or MPS for short. In other words, MeshCentral has a MPS server on port 4433 ready to receive Intel AMT CIRA connections.
95
-
96
-
97
-
98
-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.
99
-
100
-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.
101
-
102
-
103
-
104
-The CIRA protocol is binary, but MeshCentral will detect that the request is made from a browser and return a short message:
105
-
106
-```
107
-MeshCentral2 MPS server.
108
-Intel® AMT computers should connect here.
109
-```
110
-
111
-This is practical to make sure connectivity with the MeshCentral MPS server is working. Now that we know the basics of Intel AMT CIRA and the MPS server, we can configure Intel AMT to connect.
112
-
113
-## Activation Certificate Setup
114
-
115
-If you have an Intel AMT activation certificate, you should configure MeshCentral to take advantage of it. Your activation certificate must have been issued by one of the certificate authorities (CA’s) that is trusted by Intel AMT and MeshCentral will need the entire certificate chain to be provided since the entire chain is needed to perform Intel AMT ACM activation.
116
-
117
-
118
-
119
-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.
120
-
121
-If you have a certificate chain in a .pfx or .p12 format, place that file in the “meshcentral-data” folder and add the “AmtAcmActivation” section in the domain section like so:
122
-
123
-```json
124
-{
125
- "settings": {
126
- "Cert": "devbox.mesh.meshcentral.com",
127
- },
128
- "domains": {
129
- "": {
130
- "title": "My Server",
131
- "AmtAcmActivation": {
132
- "log": "amtactivation.log",
133
- "certs": {
134
- "myamtcert": {
135
- "certpfx": "amtcert.pfx",
136
- "certpfxpass": "pfxpassword"
137
- }
138
- }
139
- }
140
- }
141
-}
142
-```
143
-
144
-If you have the certificate chain in PEM format as a set of .crt files and a .key file, start by placing all of the certificate files in the “meshcentral-data” folder and setup the certificate chain like this:
145
-
146
-```json
147
-{
148
- "settings": {
149
- "Cert": "devbox.mesh.meshcentral.com",
150
- },
151
- "domains": {
152
- "": {
153
- "title": "My Server",
154
- "AmtAcmActivation": {
155
- "log": "amtactivation.log",
156
- "certs": {
157
- "myvprocert": {
158
- "certfiles": [ "amtacm-vprodemo.crt",
159
- "amtacm-intermediate1.crt",
160
- "amtacm-intermediate2.crt",
161
- "amtacm-root.crt" ],
162
- "keyfile": "amtacm-vprodemo.key"
163
- }
164
- }
165
- }
166
- }
167
-}
168
-```
169
-
170
-It’s important that the leaf certificate file be the first file in the “certfiles” array. The order of the other certificates is not important as MeshCentral will figure out and re-order them correctly.
171
-
172
-Within the new “AmtAcmActivation” section, there is a “log” entry. This is a log file that will contain every activation attempt including the details of the computer being activation and what Intel AMT administrator password was used for activation. This log file should be kept securely as it will contain Intel AMT credentials. It’s also important to have this file as a backup so that Intel AMT credentials are not lost after activation. If MeshCentral can’t write to this log, the activation will not go forward and will fail.
173
-
174
-Once the config.json was modified, restart the server. There will be two indications that the server has the new certificate correctly configured. For “Intel AMT only” groups, a new “Activation” link will show up. Clicking this link will show a command that can be run to perform ACM activation.
175
-
176
-
177
-
178
-For device groups that operate with a Mesh Agent, you can edit the group and select the “Simple Admin Control Mode” Intel AMT activation policy. This policy is not available unless a correct Intel AMT ACM activation certificate is configured.
179
-
180
-
181
-
182
-Once setup, Intel AMT will not automatically activate to Intel AMT unless the right situation is met. The Intel AMT activation certificate is for a specific domain name suffix, for example “meshcentral.com”. Intel AMT must be in a situation where this domain can be accepted. One of the following must be true:
183
-
184
- - Intel AMT must have a wired Ethernet interface that is connected to a local network with a DHCP server responding with option 15 set to “xxx.meshcentral.com”.
185
- - The name “meshcentral.com” by have been set as “Trusted FQDN” in MEBx.
186
- - The name “meshcentral.com” must have been set using a USB key with a setup.bin file.
187
-
188
-<div class="video-wrapper">
189
- <iframe width="320" height="180" src="https://www.youtube.com/embed/mhq0bsWJEOw" frameborder="0" allowfullscreen></iframe>
190
-</div>
191
-
192
-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.
193
-
194
-
195
-
196
-The best way to test this feature is to create an “Intel AMT only” device group and run the MeshCMD command on the remote system to perform activation. If there is a problem, this process should clearly display why ACM activation fails.
197
-
198
-!!!note
199
- Activation over wifi has some additional issues.<br>
200
- First you need to add your WiFi access point to that wifi configuration to allow CSME to take over WiFi when OS is not functioning. Then it should work.<br>
201
- 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.
202
- See [Open AMT Cloud Toolkit](https://www.intel.com/content/www/us/en/developer/topic-technology/edge-5g/tools/open-amt-cloud-toolkit.html) 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.
203
-
204
-## Intel AMT MEI and LMS
205
-
206
-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
207
-
208
-<div class="video-wrapper">
209
- <iframe width="320" height="180" src="https://www.youtube.com/embed/mStyhe-fSC0" frameborder="0" allowfullscreen></iframe>
210
-</div>
211
-
212
-## Intel AMT System Defense
213
-
214
-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.
215
-
216
-<div class="video-wrapper">
217
- <iframe width="320" height="180" src="https://www.youtube.com/embed/q7RyboI4uew" frameborder="0" allowfullscreen></iframe>
218
-</div>
docs/docs/meshcentral/SSLnletsencrypt.md
deleted
-37
@@ -1,37 +0,0 @@
1
-# SSL/Letsencrypt
2
-
3
-## MeshCentral supports SSL using self generated certs, your own certs or Letsencrypt
4
-
5
-### Enabling letsencrypt
6
-
7
-Make sure you match and/or adjust all the following settings appropriately in your config.json file:
8
-
9
-```json
10
-{
11
- "settings": {
12
- "redirPort"
13
- "cert": "yourdomain.com"
14
- },
15
- "domains": {
16
- "letsencrypt": {
17
- "__comment__": "Requires NodeJS 8.x or better, Go to https://letsdebug.net/ first before trying Let's Encrypt.",
18
- "email": "myemail@myserver.com",
19
- "names": "myserver.com,customer1.myserver.com",
20
- "skipChallengeVerification": false,
21
- "production": true
22
- },
23
- }
24
-}
25
-```
26
-
27
-If you need further clarification to know what each of these settings are, check out [the config schema](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json).
28
-
29
-Then restart meshcentral and it will get a cert for you, the process will need to restart to apply the cert.
30
-
31
-### Useful resources/troubleshooting
32
-
33
-To check letsencrypt is working properly please use https://letsdebug.net/. We are using the [HTTP-O1 challenge](https://letsencrypt.org/docs/challenge-types/#http-01-challenge) method with these instructions.
34
-
35
-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.
36
-
37
-You can read more about Letsencrypt and meshcentral [here](https://ylianst.github.io/MeshCentral/meshcentral/#lets-encrypt-support).
docs/docs/meshcentral/agents.md
deleted
-362
@@ -1,362 +0,0 @@
1
-# Mesh Agents
2
-
3
-## Windows
4
-
5
-Default Install Path: `c:\Program Files\Mesh Agent`
6
-
7
-Application Path: `c:\Program Files\Mesh Agent\meshagent.exe`
8
-
9
-Application database Path: `c:\Program Files\Mesh Agent\meshagent.db`
10
-
11
-Application Log Path: `c:\Program Files\Mesh Agent\meshagent.log`
12
-
13
-xxx Path: `c:\Program Files\Mesh Agent\meshagent.msh`
14
-
15
-=== ":material-console-line: Status"
16
-
17
- - Start: `net start "mesh agent"`
18
- - Stop: `net stop "mesh agent"`
19
- - Restart: `net restart "mesh agent"`
20
- - Status: Needs info
21
-
22
-=== ":material-console-line: Troubleshooting"
23
-
24
- Troubleshooting steps: Needs info
25
-
26
-## Linux / BSD
27
-
28
-Uninstall: `sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall`
29
-
30
-## Apple macOS Binary Installer
31
-
32
-Default Install Path: `/usr/local/mesh_services/meshagent/meshagent`
33
-
34
-Launches from `/Library/LaunchAgents/meshagent.plist`
35
-
36
-Controlling agent
37
-
38
-```bash
39
-launchctl stop meshagent
40
-launchctl start meshagent
41
-```
42
-
43
-Install:
44
-
45
-Uninstall: `sudo /usr/local/mesh_services/meshagent/[agent-name]/meshagent -fulluninstall`
46
-
47
-## Apple macOS Universal
48
-
49
-For OSx 11+ including Big Sur, Monterey and later
50
-
51
-## Apple macOS
52
-
53
-For macOS 10.x including Catalina, Mojave, High Sierra, Sierra, El Capitan, Yosemite, Mavericks, Mountain Lion and earlier.
54
-
55
-## Mobile Device (Android)
56
-
57
-## MeshCentral Assistant
58
-
59
-See [Assistant](assistant.md)
60
-
61
-## Apple MacOS Binary Installer
62
-
63
-## Agent Commands
64
-
65
-**agentmsg**
66
-: Add/Remove badged messages to the device's web ui
67
-```
68
- agentmsg add "[message]" [iconIndex]
69
- agentmsg remove [index]
70
- agentmsg list
71
-```
72
-**agentsize**
73
-: Returns the binary size of the agent
74
-
75
-**agentupdate**
76
-: Manually trigger an agent self-update
77
-
78
-**alert**
79
-: Display an alert dialog on the logged in session
80
-```
81
-alert TITLE, CAPTION [, TIMEOUT]
82
-```
83
-
84
-**amt**
85
-
86
-**amtconfig**
87
-
88
-**amtevents**
89
-
90
-**apf**
91
-
92
-**args**
93
-
94
-**av**
95
-: Displays Antivirus State
96
-
97
-**coredump**
98
-
99
-**coreinfo**
100
-
101
-**cpuinfo**
102
-
103
-**cs**
104
-: Display Windows Connected Standby State
105
-
106
-**dbcompact**
107
-: Compacts the agent database
108
-
109
-**dbget**
110
-
111
-**dbkeys**
112
-
113
-**dbset**
114
-
115
-**dnsinfo**
116
-: Display DNS server info
117
-
118
-**domain**
119
-: Display domain metadata
120
-
121
-**errorlog**
122
-
123
-**eval**
124
-: executes javascript on the agent
125
-```
126
-eval [code]
127
-```
128
-
129
-**fdcount**
130
-: Returns the number of active descriptors in the event loop
131
-
132
-**fdsnapshot**
133
-: Returns detailed descriptor/handle/timer metadata
134
-
135
-**getclip**
136
-: Fetches clipboard data from agent
137
-
138
-**getscript**
139
-
140
-**help**
141
-: Returns the list of supported console commands
142
-
143
-**httpget**
144
-
145
-**info**
146
-: Returns general information about the agent, such as connected state, loaded modules, LMS state, etc
147
-
148
-**kill**
149
-: Sends a SIGKILL signal to the specified PID
150
-```
151
-kill [pid]
152
-```
153
-
154
-**kvmmode**
155
-: Displays the KVM Message Format
156
-
157
-**location**
158
-: Displays saves location information about the connected agent
159
-
160
-**lock**
161
-
162
-**log**
163
-: Writes a message to the logfile
164
-```
165
-log [message]
166
-```
167
-
168
-**ls**
169
-: Enumerates the files in the agent's install folder
170
-
171
-**mousetrails**
172
-: Enables/Disables Mouse Trails Accessibility on Windows. To change setting, specify a positive integer representing the number of latent cursors, where 0 is disable
173
-```
174
-mousetrails [n]
175
-```
176
-
177
-**msh**
178
-: Displays the loaded msh settings file
179
-
180
-**netinfo**
181
-: Displays network interface information
182
-
183
-**notify**
184
-: Display a notification on the web interface
185
-
186
-**openurl**
187
-
188
-**osinfo**
189
-: Displays OS information
190
-
191
-**parseuri**
192
-: Parses the specified URI, and displays the parsed output
193
-```
194
-parseuri [uri]
195
-```
196
-
197
-**plugin**
198
-: Invokes a plugin
199
-```
200
-plugin [pluginName] [args]
201
-```
202
-
203
-**power**
204
-: Performs the specified power action
205
-```
206
-power [action]
207
- LOGOFF = 1
208
- SHUTDOWN = 2
209
- REBOOT = 3
210
- SLEEP = 4
211
- HIBERNATE = 5
212
- DISPLAYON = 6
213
- KEEPAWAKE = 7
214
- BEEP = 8
215
- CTRLALTDEL = 9
216
- VIBRATE = 13
217
- FLASH = 14
218
-```
219
-
220
-**print**
221
-
222
-**privacybar**
223
-: Sets/Gets the default pinned state of the Privacy Bar on windows
224
-```
225
-privacybar [PINNED|UNPINNED]
226
-```
227
-
228
-**ps**
229
-: Enumerates processes on the agent
230
-
231
-**rawsmbios**
232
-: Fetches the raw smbios table
233
-
234
-**safemode**
235
-: Sets/Gets the SAFEMODE configuration of the agent, as well as the next boot state.
236
-```
237
-safemode (ON|OFF|STATUS)
238
-```
239
-
240
-**scanwifi**
241
-: Scans the available Wifi access points, and displays the SSID and Signal Strength
242
-
243
-**service**
244
-: Shortcut to be able to restart the agent service
245
-```
246
-service status|restart
247
-```
248
-
249
-**setclip**
250
-: Sets clipboard data to the agent
251
-```
252
-setclip [text]
253
-```
254
-
255
-**setdebug**
256
-: Sets the location target for debug messages
257
-```
258
-setdebug [target]
259
-0 = Disabled
260
-1 = StdOut
261
-2 = This Console
262
-* = All Consoles
263
-4 = WebLog
264
-8 = Logfile
265
-```
266
-
267
-**smbios**
268
-: Displays the parsed SMBIOS metadata
269
-
270
-**startupoptions**
271
-: Displays the command-line options that the agent was started with
272
-
273
-**sysinfo**
274
-: Collects and displays telemetry on the platform
275
-
276
-**task**
277
-
278
-**taskbar**
279
-: Hides or shows the Windows System task bar, optionally on the specified Terminal Server Session ID
280
-```
281
-taskbar HIDE|SHOW [TSID]
282
-```
283
-
284
-**timerinfo**
285
-: Displays metadata about any configured timers on the event loop
286
-
287
-**toast**
288
-: Displays a toast message on the logged in user's session
289
-```
290
-toast [message]
291
-```
292
-
293
-**translations**
294
-: Shows the currently configured translations
295
-
296
-**type**
297
-```
298
-type (filepath) [maxlength]
299
-```
300
-
301
-**uac**
302
-: Get/Sets the Windows UAC mode
303
-```
304
-uac [get|interactive|secure]
305
-```
306
-
307
-**unzip**
308
-```
309
-unzip input, destination
310
-```
311
-: Unzips the specified file
312
-
313
-**users**
314
-: Enumerates the logged in users on the system
315
-
316
-**versions**
317
-: Displays version information about the agent
318
-
319
-**vm**
320
-: Detects if the system is a Virtual Machine
321
-
322
-**volumes**
323
-: Displays volume information reported by the OS
324
-
325
-**wakeonlan**
326
-: Sends wake-on-lan packets to the specified MAC address
327
-```
328
-wakeonlan [mac]
329
-```
330
-
331
-**wallpaper**
332
-: Gets/Toggles the logged in user's desktop background image
333
-```
334
-wallpaper (GET|TOGGLE)
335
-```
336
-
337
-**wpfhwacceleration**
338
-: Enable/Disable WPF HW Acceleration on Windows
339
-```
340
-wpfhwacceleration (ON|OFF|STATUS)
341
-```
342
-
343
-**wsclose**
344
-
345
-**wsconnect**
346
-
347
-**wslist**
348
-
349
-**wssend**
350
-
351
-**zip**
352
-```
353
-zip (output file name), input1 [, input n]
354
-```
355
-
356
-## Agent msh options
357
-
358
-You can find a full list of options for the agent [here](https://github.com/Ylianst/MeshAgent?tab=readme-ov-file#msh-format)
359
-
360
-`skipmaccheck=1`: Will not regenerate the agents nodeid and cause duplication of the agent when the MAC address changes.
361
-
362
-You can add options to your .msh on agent install with [this](https://github.com/Ylianst/MeshCentral/blob/15ff7d12a1e4e5d78936b473ea207b7e02b8ff26/meshcentral-config-schema.json#L2504)
docs/docs/meshcentral/assistant.md
deleted
-43
@@ -1,43 +0,0 @@
1
-# MeshCentral Assistant
2
-
3
-## Initial Setup
4
-
5
-## Agent Invite Code
6
-
7
-```json
8
-"domains": {
9
- "": {
10
- "agentInviteCodes": true
11
- }
12
-}
13
-```
14
-
15
-
16
-
17
-## Agent Invitation
18
-Click on the 'Invite' button next to the device group name to access it.
19
-### Link Invitation
20
-For link invitation web page customization:
21
-
22
-1. Alongside `meshcentral-data` create a folder called `meshcentral-web`
23
-2. Create a `views` folder in it and copy the file `node_modules/meshcentral/views/invite.handlebars` into it.
24
-3. That copy will be served instead of the default one, so you can customize it as you want.
25
-
26
-
27
-
28
-### Email Invitation
29
-This option will show up if you have an SMTP email server set up with MeshCentral.
30
-
31
-For invitation email customization:
32
-
33
-1. Alongside `meshcentral-data` create a folder called `meshcentral-web`
34
-2. Create an `emails` folder in it and copy the files `node_modules/meshcentral/emails/mesh-invite.txt` and `node_modules/meshcentral/emails/mesh-invite.html` into it.
35
-3. These copies will be used instead of the default ones, so you can customize them as you want.
36
-
37
-
38
-
39
-## Email notification
40
-
41
-You can also get an email notification when someone clicks the "Request Help" button in the Assistant agent.
42
-
43
-
docs/docs/meshcentral/codesigning.md
deleted
-150
@@ -1,150 +0,0 @@
1
-# Code Signing
2
-
3
-## Authenticode-JS Video
4
-
5
-Nodejs Code Signing module
6
-
7
-<div class="video-wrapper">
8
- <iframe width="320" height="180" src="https://www.youtube.com/embed/xteKscs_Jgo" frameborder="0" allowfullscreen></iframe>
9
-</div>
10
-
11
-MeshCentral comes with authenticode.js, you can run it like this:
12
-
13
-```bash
14
-node node_modules/meshcentral/authenticode-js
15
-```
16
-
17
-and you will get
18
-
19
-```
20
-MeshCentral Authenticode Tool.
21
-Usage:
22
- node authenticode.js [command] [options]
23
-Commands:
24
- info: Show information about an executable.
25
- --exe [file] Required executable to view information.
26
- --json Show information in JSON format.
27
- sign: Sign an executable.
28
- --exe [file] Required executable to sign.
29
- --out [file] Resulting signed executable.
30
- --pem [pemfile] Certificate & private key to sign the executable with.
31
- --desc [description] Description string to embbed into signature.
32
- --url [url] URL to embbed into signature.
33
- --hash [method] Default is SHA384, possible value: MD5, SHA224, SHA256, SHA384 or SHA512.
34
- --time [url] The time signing server URL.
35
- --proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://
36
- unsign: Remove the signature from the executable.
37
- --exe [file] Required executable to un-sign.
38
- --out [file] Resulting executable with signature removed.
39
- createcert: Create a code signging self-signed certificate and key.
40
- --out [pemfile] Required certificate file to create.
41
- --cn [value] Required certificate common name.
42
- --country [value] Certificate country name.
43
- --state [value] Certificate state name.
44
- --locality [value] Certificate locality name.
45
- --org [value] Certificate organization name.
46
- --ou [value] Certificate organization unit name.
47
- --serial [value] Certificate serial number.
48
- timestamp: Add a signed timestamp to an already signed executable.
49
- --exe [file] Required executable to sign.
50
- --out [file] Resulting signed executable.
51
- --time [url] The time signing server URL.
52
- --proxy [url] The HTTP proxy to use to contact the time signing server, must start with http://
53
- icons: Show the icon resources in the executable.
54
- --exe [file] Input executable.
55
- saveicons: Save an icon group to a .ico file.
56
- --exe [file] Input executable.
57
- --out [file] Resulting .ico file.
58
- --icongroup [groupNumber] Icon groupnumber to save to file.
59
- --removeicongroup [number]
60
- --icon [groupNumber],[filename.ico]
61
-
62
-Note that certificate PEM files must first have the signing certificate,
63
-followed by all certificates that form the trust chain.
64
-
65
-When doing sign/unsign, you can also change resource properties of the generated file.
66
-
67
- --filedescription [value]
68
- --fileversion [value]
69
- --internalname [value]
70
- --legalcopyright [value]
71
- --originalfilename [value]
72
- --productname [value]
73
- --productversion [value]
74
-```
75
-
76
-## Automatic Agent Code Signing
77
-
78
-If you want to self-sign the mesh agent so you can whitelist the software in your AV, as well as lock it to your server and organization:
79
-
80
-<div class="video-wrapper">
81
- <iframe width="320" height="180" src="https://www.youtube.com/embed/qMAestNgCwc" frameborder="0" allowfullscreen></iframe>
82
-</div>
83
-
84
-!!!note
85
- 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`
86
-
87
-## Setting Agent File info
88
-
89
-Now that MeshCentral customizes and signs the agent, you can set that value to anything you like.
90
-
91
-```json
92
-"domains": {
93
- "agentFileInfo": {
94
- "filedescription": "sample_filedescription",
95
- "fileversion": "0.1.2.3",
96
- "internalname": "sample_internalname",
97
- "legalcopyright": "sample_legalcopyright",
98
- "originalfilename": "sample_originalfilename",
99
- "productname": "sample_productname",
100
- "productversion": "v0.1.2.3"
101
- }
102
-}
103
-```
104
-
105
-## External Signing Job
106
-
107
-The externalsignjob feature allows you to perform additional operations on the agent after MeshCentral completes its code signing process. This is particularly useful for:
108
-
109
-1. Using hardware security tokens for signing
110
-2. Performing signing on a separate server or cloud host
111
-3. Archiving signed agents
112
-4. Adding additional security measures
113
-
114
-The externalsignjob is called after MeshCentral completes its entire code signing process, including:
115
-- Resource modification
116
-- Digital signature application
117
-- Timestamp application (if configured)
118
-
119
-To use this feature, add the following to your config.json:
120
-
121
-```json
122
-"settings": {
123
- "externalsignjob": "path/to/your/script.bat"
124
-}
125
-```
126
-
127
-The script will receive the path to the agent as its first argument. Here are example scripts:
128
-
129
-### Batch File Example
130
-```batch
131
-@echo off
132
-Echo External Signing Job
133
-signtool sign /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 /a /v /f path/to/your/signing.cer /csp "eToken Base Cryptographic Provider" /k "[{{MyPassword}}]=PrivateKeyContainerName" "%~1"
134
-```
135
-
136
-### PowerShell Example
137
-```powershell
138
-$file = $args[0]
139
-signtool sign /tr http://timestamp.sectigo.com /td SHA256 /fd SHA256 /a /v /f path/to/your/signing.cer /csp "eToken Base Cryptographic Provider" /k "[{{MyPassword}}]=PrivateKeyContainerName" $file
140
-```
141
-
142
-The externalsignjob can be used for more than just signing. For example, you could:
143
-
144
-1. Archive signed agents to a secure location
145
-2. Upload signed agents to a distribution server
146
-3. Perform additional security checks
147
-4. Add custom metadata or watermarks
148
-5. Integrate with your organization's build pipeline
149
-
150
-Note: The script must return a success exit code (0) for the process to be considered successful. Any non-zero exit code will be treated as a failure and will be logged.
docs/docs/meshcentral/config.md
deleted
-42
@@ -1,42 +0,0 @@
1
-# Configuration Options
2
-
3
-There are MANY configuration options available with meshcentral, search this file for options: <https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json>
4
-
5
-Some options you can find relate to:
6
-
7
-* DNS
8
-* HTTPS
9
-* MPS (Management Presence Server)
10
-* MongoDB
11
-* MariaDB
12
-* SQLite3
13
-* MySQL
14
-* PostgreSQL
15
-* AceBase
16
-* WAN (Wide Area Network)
17
-* LAN (Local Area Network)
18
-* Maintenance Mode
19
-* Session Cookie
20
-* Database Encryption
21
-* Web Relay
22
-* Agent Connection
23
-* TLS (Transport Layer Security)
24
-* WebRTC
25
-* Web Push Notifications
26
-* Auto Backup
27
-* Crowdsec
28
-* IP KVM (Keyboard, Video, Mouse over IP)
29
-* Mesh Router
30
-* Syslog
31
-* WebDAV
32
-* Certificates and Authentication
33
-* MeshCentral Server Settings
34
-* Device Management
35
-* User Permissions
36
-* Remote Desktop Configuration
37
-
38
-and more!
39
-
40
-
41
-
42
-
\ No newline at end of file
docs/docs/meshcentral/customization.md
deleted
-135
@@ -1,135 +0,0 @@
1
-# Customization
2
-
3
-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.
4
-
5
-<div class="video-wrapper">
6
- <iframe width="320" height="180" src="https://www.youtube.com/embed/xUZ1w9RSKpQ" frameborder="0" allowfullscreen></iframe>
7
-</div>
8
-
9
-## Web Branding
10
-
11
-You can put your own logo on the top of the web page. To get started, get the file “logoback.png” from the folder “node_modules/meshcentral/public/images” and copy it to your “meshcentral-data” folder. In this example, we will change the name of the file “logoback.png” to “title-mycompany.png”. Then use any image editor to change the image and place your logo.
12
-
13
-
14
-
15
-Once done, edit the config.json file and set one or all of the following values:
16
-
17
-```json
18
-"domains": {
19
- "": {
20
- "Title": "",
21
- "Title2": "",
22
- "TitlePicture": "title-sample.png",
23
- "loginPicture": "logintitle-sample.png",
24
- "welcomeText": "This is sample text",
25
- "welcomePicture": "mainwelcome-04.jpg",
26
- "welcomePictureFullScreen": true,
27
- "siteStyle": "1",
28
- "nightMode": "1",
29
- "meshMessengerTitle": "Mesh Chat",
30
- "meshMessengerPicture": "chatimage.png",
31
- "footer": "This is a HTML string displayed at the bottom of the web page when a user is logged in.",
32
- "loginfooter": "This is a HTML string displayed at the bottom of the web page when a user is not logged in."
33
- },
34
-```
35
-
36
-This will set the title and sub-title text to empty and set the background image to the new title picture file. You can now restart the server and take a look at the web page. Both the desktop and mobile sites will change.
37
-
38
-
39
-
40
-
41
-
42
-The title image must a PNG image of size 450 x 66.
43
-
44
-You can also customize the server icon in the “My Server” tab. By default, it’s a picture of a desktop with a padlock.
45
-
46
-
47
-
48
-If, for example, MeshCentral is running on a Raspberry Pi. You may want to put a different picture at this location. Just put a “server.jpg” file that is 200 x 200 pixels in the “meshcentral-data” folder. The time MeshCentral page is loaded, you will see the new image.
49
-
50
-
51
-
52
-This is great to personalize the look of the server within the web site.
53
-
54
-### Customizing Web Icons
55
-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`.
56
-
57
-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.
58
-
59
-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.
60
-
61
-
62
-### Customizing Web Style
63
-MeshCentral gives you the flexibility to override some or all of the web interface. An easy way to modify the style is to do the following:
64
-
65
-1. Create the file `custom.css` under `meshcentral-web/public/styles`. See [above](#customizing-web-style) for more information on `meshcentral-web`.
66
-2. Anything added to this file will override the default stylesheets.
67
-
68
-An example file:
69
-
70
-```css
71
-#masthead {
72
- background-color: red;
73
-}
74
-
75
-#page_leftbar {
76
- background: linear-gradient(to bottom, #104893 0%,green 100%)
77
-}
78
-
79
-#footer {
80
- background-color: green;
81
-}
82
-```
83
-
84
-Gives:
85
-
86
-
87
-
88
-!!!note
89
-You can of course override the stylesheets by directly copying them into `meshcentral-web/public/styles` but run the risk that future updates to those files in MeshCentral will be masked. `custom.css` is guaranteed to be loaded last on every page and will contain no content by default which means upgrades will work as normal.
90
-
91
-
92
-### Customizing Agent Invitation
93
-Agents can be invited by public link or via email. [Click Here](assistant.md#agent-invitation) to see details.
94
-
95
-## Agent Branding
96
-
97
-You can customize the Agent to add your own logo, change the title bar, install text, the service name, or even colors!
98
-
99
-!!!note
100
- 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.
101
-
102
-
103
-
104
-```json
105
-"domains": {
106
- "": {
107
- "agentCustomization": {
108
- "displayName": "MeshCentral Agent",
109
- "description": "Mesh Agent background service",
110
- "companyName": "Mesh Agent Company",
111
- "serviceName": "Mesh Agent Service",
112
- "installText": "Text string to show in the agent installation dialog box",
113
- "image": "mylogo.png",
114
- "fileName": "meshagent",
115
- "foregroundColor": "#FFA500",
116
- "backgroundColor": "#EE82EE"
117
- }
118
- }
119
-}
120
-```
121
-
122
-
123
-
124
-## Terms of use
125
-
126
-You can change the terms of use of the web site by adding a “terms.txt” file in the “meshcentral-data” folder. The file can include HTML markup. Once set, the server does not need to be restarted, the updated terms.txt file will get used the next time it’s requested.
127
-
128
-For example, placing this in “terms.txt”
129
-
130
-```
131
-<br />
132
-This is a <b>test file</b>.
133
-```
134
-
135
-Will show this on the terms of use web page.
docs/docs/meshcentral/debugging.md
deleted
-383
@@ -1,383 +0,0 @@
1
-# Debugging
2
-
3
-## Websockets Video
4
-
5
-Make sure you understand how MeshCentral works with your browser using chrome developer tools.
6
-
7
-<div class="video-wrapper">
8
- <iframe width="320" height="180" src="https://www.youtube.com/embed/3vI4URd3VzU" frameborder="0" allowfullscreen></iframe>
9
-</div>
10
-
11
-## MeshCentral Server
12
-
13
-### Useful config.js settings
14
-
15
-<https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json>
16
-
17
-```json
18
-"AgentsInRAM": false,
19
-"AgentUpdateBlockSize": 2048,
20
-"agentUpdateSystem": 1,
21
-"noAgentUpdate": 1,
22
-"WsCompression": false,
23
-"AgentWsCompression": false,
24
-```
25
-
26
-### Understanding node and paths
27
-
28
-Note that when running MeshCentral, you should always run from the path that is parent to node_modules, so you do this:
29
-
30
-```
31
-cd C:\Program Files\Open Source\MeshCentral
32
-node node_modules\meshcentral
33
-```
34
-
35
-You do NOT do this:
36
-
37
-```
38
-cd C:\Program Files\Open Source\MeshCentral\node_modules\meshcentral
39
-node meshcentral
40
-```
41
-
42
-The problem with the second command is that NPM may install missing modules in the incorrect location.
43
-
44
-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:
45
-
46
-```
47
-mkdir c:\meshcentral
48
-cd c:\meshcentral
49
-npm install meshcentral
50
-node node_modules\meshcentral
51
-(ctrl-c when done installing optional modules)
52
-node node_modules\meshcentral --install
53
-```
54
-
55
-This way, you have a lot more control over what is going on. In my opinion, the MSI installer basically does the same thing and installs NodeJS for you.
56
-
57
-### Unable to update server
58
-
59
-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:
60
-
61
-```json
62
-{
63
- "settings": {
64
- "npmPath": "c:\\npm.exe",
65
- "npmProxy": "http://1.2.3.4:80"
66
- }
67
-}
68
-```
69
-
70
-The problem could also be that you need a proxy, the configuration line to that is above.
71
-
72
-You can also manually update. Just stop your server and so this:
73
-
74
-```bash
75
-mv node_modules node_modules_bak
76
-npm install meshcentral
77
-node node_modules/meshcentral
78
-```
79
-
80
-Then wait for all optional modules to install, then once the server starts hit ctrl-c and start up the server again. You can also use the following to help you start/stop the server:
81
-
82
-```bash
83
-node node_modules/meshcentral --install
84
-node node_modules/meshcentral --uninstall
85
-node node_modules/meshcentral --start
86
-node node_modules/meshcentral --stop
87
-```
88
-
89
-### Port Troubleshooting on server
90
-
91
-If you're getting a `port 4433 is not available` error, this is because another process is using this port, very likely another instance of MeshCentral. If your MeshCentral server is bound to ports 81/444 MeshCentral could not get port 80/443 and got the next available ones.
92
-
93
-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.
94
-
95
-### Running Meshcentral server in debug mode
96
-
97
-Debug more will cause MeshCentral to output a lot of debug messages to the console. To display all debug messages, run MeshCentral like this:
98
-
99
-```bash
100
-node node_modules/meshcentral --debug
101
-```
102
-
103
-A more practical way to run the debug command it to specify what messages you want printed out using a comma seperated list, for example:
104
-
105
-```bash
106
-node node_modules/meshcentral --debug web,amt,mps
107
-```
108
-
109
-Here is the list of all debug options:
110
-
111
-```
112
-cookie - Cookie encoder
113
-dispatch - Message Dispatcher
114
-main - Main Server Messages
115
-peer - MeshCentral Server Peering
116
-agent - MeshAgent traffic
117
-agentupdate - MeshAgent update
118
-cert - Server Certificate
119
-db - Server Database
120
-email - Email/SMS/Push Traffic
121
-web - Web Server
122
-webrequest - Web Server Requests
123
-relay - Web Socket Relay
124
-httpheaders - Web Server HTTP Headers
125
-authlog - User Authentication Log
126
-amt - Intel AMT
127
-webrelay - Connection Relay
128
-mps - CIRA Server
129
-mpscmd - CIRA Server Commands
130
-```
131
-
132
-You can also specify the `debug` option in the config.json file in the `settings` section. For example:
133
-
134
-```
135
-"settings": {
136
- "debug": "web,amt,mps"
137
-}
138
-```
139
-
140
-
141
-### Enabling trace in your browser Dev Tools
142
-
143
-You can enable browser console tracing by adding `trace=1` as a parameter to the URL of the MeshCentral main web page. For example `https://myserver.com/?trace=1`. Once present, open the browser's console window to see all web client tracing messages.
144
-
145
-To log all database queries, change log_statement in /etc/postgresql/13/main/postgresql.conf
146
-
147
-```
148
-# CUSTOM
149
-log_statement = 'all' # none, ddl, mod, all
150
-```
151
-
152
-The stacktrace was logged to `stdout/journalctl`. Supposedly, you can enable debug logging for node modules by adding `DEBUG=<modulename>` to the environment.
153
-
154
-Adding this to `/etc/systemd/system/meshcentral.service` should do it but it didn't seem to do anything.
155
-
156
-I think that's because Mesh uses the trace logging in the browser instead of logging things in the server logs.
157
-
158
-```
159
-Environment=DEBUG=mesh*
160
-```
161
-
162
-If you want to change node to meshcentral in journalctl, add this to /etc/systemd/system/meshcentral.service.
163
-
164
-```
165
-SyslogIdentifier=meshcentral
166
-```
167
-
168
-### Finding agent problems
169
-
170
-Using the servers `My Server > console`
171
-
172
-* `agentstatus` - Gives you summary counts of problems
173
-* `agentissues` - Gives IP:port and what error
174
-* `dupagents` - Gives duplicateAgent IP's, counts and names
175
-
176
-### Logging it all
177
-
178
-To log everything that's possible, prepare the log directory.
179
-
180
-```
181
-mkdir /meshcentral/meshcentral-logs/
182
-chown tactical:tactical logs
183
-ln -s ../meshcentral-logs/log.txt /meshcentral/meshcentral-data/log.txt
184
-```
185
-
186
-And then add this to your config.
187
-
188
-```json
189
- "meshErrorLogPath": "/meshcentral/meshcentral-logs/",
190
- "authLog": "/meshcentral/meshcentral-logs/auth.log",
191
- "log": [
192
- "cookie",
193
- "dispatch",
194
- "main",
195
- "peer",
196
- "web",
197
- "webrequest",
198
- "relay",
199
- "webrelaydata",
200
- "webrelay",
201
- "mps",
202
- "mpscmd",
203
- "swarm",
204
- "swarmcmd",
205
- "agentupdate",
206
- "agent",
207
- "cert",
208
- "db",
209
- "email",
210
- "amt",
211
- "httpheaders",
212
- "websocket"
213
- ],
214
-```
215
-
216
-You'll then have 3 files:
217
-
218
-```bash
219
--rw-rw-r-- 1 tactical tactical 2593 Feb 2 12:22 auth.log
220
--rw-r--r-- 1 tactical tactical 147593 Feb 2 12:31 log.txt
221
--rw-rw-r-- 1 tactical tactical 381 Feb 2 12:02 mesherrors.txt
222
-```
223
-
224
-`log.txt` will now log everything in the Trace tab
225
-
226
-### Restricting server to specific IP(s)
227
-
228
-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:
229
-
230
-```
231
-"agentAllowedIp": [ "192.168.2.147" ],
232
-```
233
-
234
-Of course, this is just for debugging.
235
-
236
-### Finding system ID types
237
-
238
-<https://serverurl/meshagents> aka trying figure out what this is
239
-
240
-
241
-
242
-### Pull down cert .crt file from internet
243
-
244
-[See #1662](https://github.com/Ylianst/MeshCentral/issues/1662#issuecomment-666559391) 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:
245
-
246
-```bash
247
-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
248
-service meshcentral restart
249
-```
250
-
251
-## MeshAgent
252
-
253
-Troubleshooting agent
254
-
255
-```bash
256
-./meshagent -state
257
-```
258
-
259
-### Agent Debug Logs to server
260
-
261
-This automatically downloads all agent error logs into `meshcentral-data/agenterrorlogs.txt`
262
-
263
-[Set](https://github.com/Ylianst/MeshCentral/blob/aa58afcc3a5d738177ab7a7b6d0228d72af82b85/meshcentral-config-schema.json#L100) in `config.json`
264
-
265
-```json
266
-"agentLogDump": true
267
-```
268
-
269
-### Determine Agent capabilities
270
-
271
-On the server goto the agents console tab. Type:
272
-
273
-```
274
-info
275
-```
276
-
277
-### Useful MeshAgent.msh flags
278
-
279
-<https://github.com/Ylianst/MeshAgent/blob/master/meshcore/agentcore.h#L190>
280
-
281
-```json
282
-controlChannelDebug=1
283
-logUpdate=1
284
-```
285
-
286
-### Obtain generated .msh File
287
-
288
-If you need a trick to get the .msh file, you can add ?debug=1 to the URL and click "Add Agent", there will be an extra link to download it.
289
-
290
-### MeshAgent Commands
291
-
292
-```
293
-MeshAgent run
294
-MeshAgent dbTool.js list
295
-```
296
-
297
-Forcing Core version from Cmdline
298
-
299
-* Download meschore.js and rename to CoreModule.js and put it alongside MeshAgent.exe
300
-* Stop MeshAgent service
301
-* Run `MeshAgent.exe dbTool.js import CoreModule`
302
-
303
-### On the fly Patching MeshAgent
304
-
305
-[MeshAgent#89 (comment)](https://github.com/Ylianst/MeshAgent/issues/89#issuecomment-949901720)
306
-
307
-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.....
308
-
309
-When you are satisfied with your changes to the .js file, you can use the clipboard, in the following fashion:
310
-
311
-```bash
312
-meshagent -exec "require('clipboard').nativeAddCompressedModule('foo');process.exit();"
313
-```
314
-
315
-if the file you modified isn't in the same folder as the agent binary, you can use the following command if you don't want to move the file, and edit it directly in the modules folder:
316
-
317
-```bash
318
-meshagent -exec "setModulePath('pathToFolder');require('clipboard').nativeAddCompressedModule('foo');process.exit();"
319
-```
320
-
321
-This command is just like the previous, except it searches for modules in the path specified.
322
-
323
-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.
324
-
325
-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.
326
-
327
-### Agent Debugging using MeshCore JS Debugger
328
-
329
-[(#119)](https://github.com/Ylianst/MeshAgent/issues/119) How to test changes to the meshagent and recompile them.
330
-
331
-* Copy duktape-debugger.js to the mesh directory on the target machine.
332
-* From the console tab of the agent, enter this command, substituting the port number you want to use instead of 9999
333
-`eval "attachDebugger({ webport: 9999 })"`
334
-
335
-Then open your browser to http://localhost:9999 or whatever port you used.
336
-
337
-!!!note
338
- 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.
339
-
340
-### Troubleshooting Agent connectivity
341
-
342
-If an agent keeps disconnecting and reconnecting, add this line to the "settings" section of the config.json:
343
-
344
-```
345
-"agentping": 30
346
-```
347
-
348
-This will cause MeshCentral to "ping" the agent every 30 seconds and the agent to respond with a "pong" each time. That usually solves the issue however, it does generate more traffic. If that works, you can remove the line and try this line instead:
349
-
350
-```
351
-"agentpong": 30
352
-```
353
-
354
-This will cause MeshCentral to "pong" the agent every 30 seconds, the agent will not respond. This usually fixes the issue, but you have half the traffic. I would also increase the time like:
355
-
356
-```
357
-"agentpong": 90
358
-```
359
-
360
-This is the best, you have one way traffic to all agents every 90 seconds. The larger the number you can get away with the better.
361
-
362
-If you ever get the same problem but on the browser side, you can also use one of these:
363
-
364
-```
365
-"browserping": 30
366
-"browserpong": 30
367
-```
368
-
369
-Same idea, browser side instead of agent side.
370
-
371
-## Intel AMT
372
-
373
-To debug issues, confirm that Intel AMT is active and there MeshCentral is not showing any red errors on the "Intel AMT" line:
374
-
375
-
376
-
377
-Next, you can go in the "My Server / Trace" tab and enable tracing on the "Intel AMT Manager" like this:
378
-
379
-
380
-
381
-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.
382
-
383
-
docs/docs/meshcentral/devicetabs.md
deleted
-272
@@ -1,272 +0,0 @@
1
-# Device Tabs
2
-
3
-## Search or Filter
4
-
5
-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):
6
-
7
-```
8
-user:xxx or u:xxx
9
-ip:xxx
10
-group:xxx or g:xxx
11
-tag:xxx or t:xxx
12
-atag:xxx or a:xxx
13
-os:xxx
14
-amt:xxx
15
-desc:xxx
16
-wsc:ok
17
-wsc:noav
18
-wsc:noupdate
19
-wsc:nofirewall
20
-wsc:any
21
-```
22
-
23
-## General
24
-
25
-For viewing general information about the agent
26
-
27
-* Group
28
-* Description
29
-* IP-KVM Port Number
30
-* IP-KVM Port Type
31
-* Intel AMT
32
-* Intel AMT Tag
33
-* Mesh Agent
34
-* Operating System
35
-* Windows Security
36
-* Antivirus
37
-* Active User
38
-* User Consent
39
-* Notifications
40
-* Tags
41
-
42
-### Fields
43
-
44
-### Buttons
45
-
46
-Actions
47
-Notes
48
-Log Event
49
-Message
50
-PDU On/Off/Control
51
-Chat
52
-
53
-### 7 Day Power State
54
-
55
-
56
-
57
-Legend
58
-
59
-* **_Black color_**: Device is Powered On on (Intel AMT & agents)
60
-* **_Purple color_**: Device is in sleep state such as Hibernating (Intel AMT agents only)
61
-* **_Teal color_**: Device is connected through AMT/CIRA, but the Power State is UNKNOWN (Intel AMT agents only)
62
-* **_DarkGreen color_**: Device is connected through AMT/CIRA and is in Soft-Off Power State (Intel AMT agents only)
63
-* **_Grey color_**: Device is Powered Off/Not Connected To MeshCentral (Intel AMT & agents)
64
-
65
-### Text Links
66
-
67
-You can set alternate port in the link if it's not default by right-clicking.
68
-
69
-
70
-
71
-* Interfaces
72
-* Location
73
-* MeshCmd
74
-* RDP
75
-* Web-VNC
76
-* Web-RDP
77
-* Web-SSH
78
-* XTerm
79
-* HTTP
80
-* HTTPS
81
-* SSH
82
-* SCP
83
-* MQTT Login
84
-
85
-## Desktop
86
-
87
-For connecting to the machines KVM interface.
88
-
89
-### Connect Button
90
-
91
-Right-clicking on Connect button will give you additional options:
92
-
93
-* Ask Consent + Bar
94
-* Ask Consent
95
-* Privacy Bar
96
-
97
-
98
-
99
-### RDP Connect Button
100
-
101
-Right-clicking on RDP Connect button allows you to specify Alternate Port.
102
-
103
-
104
-
105
-### Intel AMT Connect Button
106
-
107
-Uses Intel AMT to control video output of the hardware video card.
108
-
109
-### During a desktop session
110
-
111
-**Bottom left include:**
112
-
113
-
114
-
115
-* Sending special Keys
116
-
117
-**Top Right include:**
118
-
119
-Actions
120
-
121
-
122
-
123
-* Wake Up
124
-* Run Commands
125
-* Sleep
126
-* Reset
127
-* Power Off
128
-* Uninstall Agent
129
-
130
-Settings
131
-
132
-
133
-
134
-* Quality
135
-* Scaling
136
-* Frame rate
137
-* Swap Mouse Buttons
138
-* Reverse Mouse Wheel
139
-* Use Remote Keyboard Map
140
-* Automatic Clipboard
141
-* Lock on Disconnect
142
-
143
-
144
-
145
-* Session recording indicator
146
-* Screen rotating
147
-* switching view mode
148
-* full screen
149
-
150
-Bottom right include:
151
-
152
-
153
-
154
-* Session Sharing with Guest
155
-* Toggling keyboard lockout on guest
156
-* Refresh Desktop view
157
-* Upload Clipboard
158
-* Download Clipboard
159
-* Record Session to file
160
-* Take screenshot
161
-* Toggle Remote Desktop Background
162
-* Open URL on remote desktop
163
-* Lock the Remote computer
164
-* Display a notification on the remote computer
165
-* Open Chat Window
166
-
167
-## Terminal
168
-
169
-For connecting to a command line based interface on the agent
170
-
171
-Right-clicking on Connect button allows you to:
172
-
173
-!!!note
174
- Linux and Windows have different options:
175
-
176
-* Admin Shell (Windows)
177
-* Admin Powershell (Windows)
178
-* User Shell (Windows)
179
-* User Powershell (Windows)
180
-* SSH (Linux)
181
-
182
-
183
-
184
-## Files
185
-
186
-For transferring files to and from the agent.
187
-
188
-## Events
189
-
190
-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.
191
-
192
-## Details
193
-
194
-Agent information that includes:
195
-
196
-* OS
197
-* Agent Info
198
-* Network Info
199
-* BIOS
200
-* Motherboard
201
-* Memory
202
-* Storage
203
-* Intel AMT
204
-
205
-Note you can show CPU and Memory usage info by clicking the icon in the top right corner
206
-
207
-
208
-
209
-## Intel AMT
210
-
211
-## Console
212
-
213
-For debugging and communicating with the mesh agent.
214
-
215
-It allows JS commands to be issued to the device but also run extra commands from the meshcore. Type `help` for all available options
216
-
217
-- 2falock
218
-- acceleratorsstats
219
-- agentissues
220
-- agentstats
221
-- amtacm
222
-- amtmanager
223
-- amtpasswords
224
-- amtstats
225
-- args
226
-- autobackup
227
-- backupconfig
228
-- bad2fa
229
-- badlogins
230
-- certexpire
231
-- certhashes
232
-- closeusersessions
233
-- cores
234
-- dbcounters
235
-- dbstats
236
-- dispatchtable
237
-- dropallcira
238
-- dupagents
239
-- email
240
-- emailnotifications
241
-- firebase
242
-- heapdump
243
-- heapdump2
244
-- help
245
-- info
246
-- le
247
-- lecheck
248
-- leevents
249
-- maintenance
250
-- migrationagents
251
-- mps
252
-- mpsstats
253
-- msg
254
-- nodeconfig
255
-- print
256
-- relays
257
-- removeinactivedevices
258
-- resetserver
259
-- serverupdate
260
-- setmaxtasks
261
-- showpaths
262
-- sms
263
-- swarmstats
264
-- tasklimiter
265
-- trafficdelta
266
-- trafficstats
267
-- updatecheck
268
-- usersessions
269
-- versions
270
-- watchdog
271
-- webpush
272
-- webstats
docs/docs/meshcentral/faq.md
deleted
-83
@@ -1,83 +0,0 @@
1
-# FAQ
2
-
3
-## json config files
4
-
5
-Any item in the config.json file starting with an underscore character are ignored.
6
-
7
-Ignored
8
-
9
-```json
10
-"_title": "MyServer"
11
-```
12
-
13
-Valid setting
14
-
15
-```json
16
-"title": "MyServer"
17
-```
18
-
19
-json requires correct formatting, if in doubt copy/paste your json config into a web based format checker to make sure you have it right: <https://duckduckgo.com/?va=j&t=hc&q=json+lint&ia=answer>
20
-
21
-## Help! I've been hacked there are weird agents appearing in my MeshCentral Console
22
-
23
-No, you haven't.
24
-
25
-1. Your agent installer was scanned by an antivirus.
26
-
27
-2. It didn't recognize the exe.
28
-
29
-3. You have the option enabled to submit unknown applications for analysis.
30
-
31
- 
32
-
33
-4. They ran it against their virtualization testing cluster.
34
-
35
-5. You allow anyone to connect to your server (you should look into techniques to hide your server from the internet).
36
-
37
-6. Here are some examples of what that looks like.
38
-
39
-## Can't login on server after first setup
40
-
41
-You're sure you're typing in everything right, giving it 2FA code and can't login
42
-
43
-[TOTP](https://en.wikipedia.org/wiki/Time-based_one-time_password) is time sensitive, check your time/NTP and make sure it's right (on server and TOTP app device)! :)
44
-
45
-
46
-
47
-## Branding and Customization
48
-
49
-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](https://ylianst.github.io/MeshCentral/meshcentral/#branding-terms-of-use)
50
-
51
-!!!note
52
- You will need to reinstall the agent for agent customizations to take effect.
53
-
54
-## Mac Clients
55
-
56
-You have to manually grant Mac permissions outside of the agent install process due to the MacOS security system under Security & Privacy > Privacy
57
-
58
-To see the screen (otherwise you just see the menu bar, and otherwise blank)
59
-
60
-
61
-
62
-To be able to transfer files
63
-
64
-
65
-
66
-To be able to control keyboard and mouse
67
-
68
-
69
-
70
-## I'm using CloudFlare and I'm getting a black screen but the mouse moves?
71
-
72
-If you are using CloudFlare for your DNS hosting and your remote screen is black, DONT PANIC!
73
-
74
-Unfortunately, MeshCentral doesn't always work with CloudFlare's Proxy DNS Mode.
75
-
76
-The fix is to simply set the 'Proxy Status' to OFF inside your DNS A Record, within the CloudFlare control panel.
77
-
78
-Simply follow the steps [here](https://developers.cloudflare.com/fundamentals/setup/manage-domains/pause-cloudflare/#disable-proxy-on-dns-records)
79
-
80
-Once done, open your firewall for the `port` and `agentPort` ports of where your meshcentral is hosted, then restart your MeshCentral Server
81
-
82
-There is currently a PINNED GitHub issue about this [here](https://github.com/Ylianst/MeshCentral/issues/5302)
83
-
docs/docs/meshcentral/images/2022-05-18-22-11-41.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-11-41.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-16-11.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-16-11.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-20-08.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-20-08.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-23-59.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-23-59.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-25-39.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-25-39.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-26-14.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-26-14.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-27-25.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-27-25.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-29-12.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-29-12.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-29-40.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-29-40.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-29-47.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-29-47.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-22-32-35.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-22-32-35.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-33-08.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-33-08.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-34-22.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-34-22.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-35-19.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-35-19.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-37-31.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-37-31.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-37-40.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-37-40.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-38-45.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-38-45.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-39-03.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-39-03.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-41-23.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-41-23.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-41-58.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-41-58.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-42-51.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-42-51.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-46-26.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-46-26.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-49-37.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-49-37.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-49-53.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-49-53.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-53-04.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-53-04.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-55-26.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-55-26.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-56-29.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-56-29.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-56-59.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-56-59.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18-23-59-28.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18-23-59-28.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-18_223720.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-18_223720.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-00-05.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-00-05.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-00-18.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-00-18.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-01-19.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-01-19.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-01-43.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-01-43.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-02-03.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-02-03.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-03-32.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-03-32.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-03-46.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-03-46.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-03-58.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-03-58.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-19-29.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-19-29.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-19-46.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-19-46.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-21-19.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-21-19.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-21-54.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-21-54.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-23-11.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-23-11.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-25-11.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-25-11.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-32-32.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-32-32.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-34-54.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-34-54.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-35-32.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-35-32.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-38-11.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-38-11.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-38-51.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-38-51.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-39-35.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-39-35.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-39-42.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-39-42.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-40-00.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-40-00.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-40-13.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-40-13.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-42-49.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-42-49.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-44-03.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-44-03.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-44-25.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-44-25.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-45-31.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-45-31.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-45-45.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-45-45.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-48-17.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-48-17.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-48-41.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-48-41.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-48-54.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-48-54.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-49-25.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-49-25.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-50-18.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-50-18.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-50-30.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-50-30.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-50-52.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-50-52.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-51-14.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-51-14.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-51-29.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-51-29.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-52-05.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-52-05.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-52-36.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-52-36.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-52-53.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-52-53.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-53-38.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-53-38.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-54-31.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-54-31.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-54-50.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-54-50.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-55-29.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-55-29.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-56-05.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-56-05.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-57-06.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-57-06.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-19-00-57-28.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-19-00-57-28.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-31-10-30-07.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-31-10-30-07.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-31-10-30-42.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-31-10-30-42.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-31-10-30-50.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-31-10-30-50.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-31-10-31-00.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-31-10-31-00.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-05-31-10-32-46.jpg
Binary files a/docs/docs/meshcentral/images/2022-05-31-10-32-46.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-56-14.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-56-14.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-56-55.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-56-55.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-57-03.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-57-03.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-57-15.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-57-15.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-57-30.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-57-30.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-06-17-15-57-52.jpg
Binary files a/docs/docs/meshcentral/images/2022-06-17-15-57-52.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-07-02-06-27-36.jpg
Binary files a/docs/docs/meshcentral/images/2022-07-02-06-27-36.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-08-24-06-42-40.jpg
Binary files a/docs/docs/meshcentral/images/2022-08-24-06-42-40.jpg and /dev/null differ
docs/docs/meshcentral/images/2022-09-06-16-38-57.jpg
Binary files a/docs/docs/meshcentral/images/2022-09-06-16-38-57.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-02-24vscodejsonediting.jpg
Binary files a/docs/docs/meshcentral/images/2023-02-24vscodejsonediting.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-11-29-12-57-15.jpg
Binary files a/docs/docs/meshcentral/images/2023-11-29-12-57-15.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-11-29-12-58-05.jpg
Binary files a/docs/docs/meshcentral/images/2023-11-29-12-58-05.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-11-29-12-58-36.jpg
Binary files a/docs/docs/meshcentral/images/2023-11-29-12-58-36.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-11-29_140845 - mesh json1.jpg
Binary files a/docs/docs/meshcentral/images/2023-11-29_140845 - mesh json1.jpg and /dev/null differ
docs/docs/meshcentral/images/2023-11-29_140845 - mesh json2.jpg
Binary files a/docs/docs/meshcentral/images/2023-11-29_140845 - mesh json2.jpg and /dev/null differ
docs/docs/meshcentral/images/7daypowerstate.jpg
Binary files a/docs/docs/meshcentral/images/7daypowerstate.jpg and /dev/null differ
docs/docs/meshcentral/images/agentico.jpg
Binary files a/docs/docs/meshcentral/images/agentico.jpg and /dev/null differ
docs/docs/meshcentral/images/amt_troubleshoot1.jpg
Binary files a/docs/docs/meshcentral/images/amt_troubleshoot1.jpg and /dev/null differ
docs/docs/meshcentral/images/amt_troubleshoot2.jpg
Binary files a/docs/docs/meshcentral/images/amt_troubleshoot2.jpg and /dev/null differ
docs/docs/meshcentral/images/amt_troubleshoot3.jpg
Binary files a/docs/docs/meshcentral/images/amt_troubleshoot3.jpg and /dev/null differ
docs/docs/meshcentral/images/assistant_agent_code.jpg
Binary files a/docs/docs/meshcentral/images/assistant_agent_code.jpg and /dev/null differ
docs/docs/meshcentral/images/assistant_invitation_link.jpg
Binary files a/docs/docs/meshcentral/images/assistant_invitation_link.jpg and /dev/null differ
docs/docs/meshcentral/images/custom-style-example.png
Binary files a/docs/docs/meshcentral/images/custom-style-example.png and /dev/null differ
docs/docs/meshcentral/images/custom-web-icons.jpg
Binary files a/docs/docs/meshcentral/images/custom-web-icons.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_buttonsbottomleft.jpg
Binary files a/docs/docs/meshcentral/images/desktop_buttonsbottomleft.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_buttonsbottomright.jpg
Binary files a/docs/docs/meshcentral/images/desktop_buttonsbottomright.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_buttonstopright_actions.jpg
Binary files a/docs/docs/meshcentral/images/desktop_buttonstopright_actions.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_buttonstopright_other.jpg
Binary files a/docs/docs/meshcentral/images/desktop_buttonstopright_other.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_connectbutton.jpg
Binary files a/docs/docs/meshcentral/images/desktop_connectbutton.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_rdpconnectbutton.jpg
Binary files a/docs/docs/meshcentral/images/desktop_rdpconnectbutton.jpg and /dev/null differ
docs/docs/meshcentral/images/desktop_settings.jpg
Binary files a/docs/docs/meshcentral/images/desktop_settings.jpg and /dev/null differ
docs/docs/meshcentral/images/details_cpuram.jpg
Binary files a/docs/docs/meshcentral/images/details_cpuram.jpg and /dev/null differ
docs/docs/meshcentral/images/determine-id.jpg
Binary files a/docs/docs/meshcentral/images/determine-id.jpg and /dev/null differ
docs/docs/meshcentral/images/email-invitation.jpg
Binary files a/docs/docs/meshcentral/images/email-invitation.jpg and /dev/null differ
docs/docs/meshcentral/images/faq_av_option1.jpg
Binary files a/docs/docs/meshcentral/images/faq_av_option1.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-newproject.jpg
Binary files a/docs/docs/meshcentral/images/gc-newproject.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-oauthconsent.jpg
Binary files a/docs/docs/meshcentral/images/gc-oauthconsent.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-oauthconsent2.jpg
Binary files a/docs/docs/meshcentral/images/gc-oauthconsent2.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-oauthcredentials.jpg
Binary files a/docs/docs/meshcentral/images/gc-oauthcredentials.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-oauthscopes.jpg
Binary files a/docs/docs/meshcentral/images/gc-oauthscopes.jpg and /dev/null differ
docs/docs/meshcentral/images/gc-playground.webp
Binary files a/docs/docs/meshcentral/images/gc-playground.webp and /dev/null differ
docs/docs/meshcentral/images/general_alternateports.jpg
Binary files a/docs/docs/meshcentral/images/general_alternateports.jpg and /dev/null differ
docs/docs/meshcentral/images/in-production.jpg
Binary files a/docs/docs/meshcentral/images/in-production.jpg and /dev/null differ
docs/docs/meshcentral/images/ldap_integration.jpg
Binary files a/docs/docs/meshcentral/images/ldap_integration.jpg and /dev/null differ
docs/docs/meshcentral/images/oauth-internal-external.jpg
Binary files a/docs/docs/meshcentral/images/oauth-internal-external.jpg and /dev/null differ
docs/docs/meshcentral/images/rate_limiting_logins.jpg
Binary files a/docs/docs/meshcentral/images/rate_limiting_logins.jpg and /dev/null differ
docs/docs/meshcentral/images/terminal_connectbutton.jpg
Binary files a/docs/docs/meshcentral/images/terminal_connectbutton.jpg and /dev/null differ
docs/docs/meshcentral/images/user_tokens1.jpg
Binary files a/docs/docs/meshcentral/images/user_tokens1.jpg and /dev/null differ
docs/docs/meshcentral/images/user_tokens2.jpg
Binary files a/docs/docs/meshcentral/images/user_tokens2.jpg and /dev/null differ
docs/docs/meshcentral/index.md
deleted
-2015
@@ -1,2015 +0,0 @@
1
-# MeshCentral Guide
2
-
3
-## 🧾 Abstract
4
-
5
-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.
6
-
7
-## 📘 Introduction
8
-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.
9
-
10
-
11
-
12
-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.
13
-
14
-At a high level, there are only four (4) main steps : **_Setup_**, **_Install_**, **_Connect_**, and **_Control_**.
15
-
16
- 1. Setup the MeshCentral server on VM or PC
17
- 2. Log on to MeshCentral portal with a valid account, creates an administrative mesh to collect all end-points (systems to be managed)
18
- 3. Generates an agent and installs it on a target or each end-point that immediately attempts a connection back to MeshCentral server.
19
- 4. Controls/manages assets or end-points that are available in respective administrative mesh
20
-
21
-## 🎬 Video Walkthrough
22
-
23
-<div class="video-wrapper">
24
- <iframe src="https://www.youtube.com/embed/D9Q7M7PdTg0" frameborder="0" allowfullscreen></iframe>
25
-</div>
26
-
27
-## 🖥️ Server Installation
28
-
29
-Because the MeshCentral server is written in NodeJS it can be installed on many operating systems including Windows, Linux. Please refer to the MeshCentral Installer’s Guide available at <https://www.meshcommander.com/meshcentral2> for information on how to install the server.
30
-
31
-!!! note
32
- For information on how to install the server, please refer to the **MeshCentral Installer’s Guide** available at [https://www.meshcommander.com/meshcentral2](https://www.meshcommander.com/meshcentral2).
33
-
34
-The server can be installed both on a local area network for local computer management and in the cloud for management of computers over the Internet. You can also install it on small IoT devices like a Raspberry Pi all the way to big servers. It’s recommended to get started with a test setup to get a feel for this server. Once installed, come back to this document for configuring and using your new server.
35
-
36
-## 🚀 Basic Usage
37
-
38
-In this section we will cover the basics of MeshCentral in your newly setup server.
39
-
40
-### Launch
41
-
42
-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:
43
- 
44
-
45
-This is because by default MeshCentral is using a self-signed certificate that is not known to the browser as a “trusted” or “trustworthy” certificate. To prevent this warning from recurring, the following chapter will provide useful steps that can be considered.
46
-
47
----
48
-#### Proceeding with Browser Security Warnings
49
-
50
-##### Firefox
51
-
52
-To continue on **Firefox**:
53
-
54
-1. Click on *Advanced*
55
-2. Select *Add Exception*
56
-3. Click *Confirm Security Exception*
57
-
58
-##### Chrome
59
-
60
-To continue on **Chrome**:
61
-
62
-1. Click on *Advanced*
63
-2. Click *Proceed to `http://serverIP` (unsafe)*
64
----
65
-
66
-!!! note
67
- You can also get to a device by specifying the device name in the URL by adding *`?viewmode=10&gotodevicename=MyComputer`* to the URL of the MeshCentral web page. The new *`gotodevicename`* will find a device with the specified name and navigate to that device's page. This is perfect for integrating MeshCentral with other solutions but be aware that a computer name is not a unique identifier and so, *`&gotonode=`* is always the preferred way to access a device. This feature also works on the mobile web site.
68
-
69
-### Create Account
70
-
71
-Create an account by clicking “Create One” and click “Create Account” once the text fields had been populated correctly. As shown in the following image :
72
-
73
-
74
-
75
-### New device group
76
-
77
-Once logged in, create a new device group. This is a group of computers that we want to manage. To proceed,
78
-
79
-1. Click on “Click here to create a new group of devices”,
80
-2. Key in a suitable “Name”, .e.g. “SampleGroup”
81
-3. Leave “Type” to default “Manage using a software agent” and click ‘OK”.
82
-
83
-
84
-
85
-!!! note
86
- There are two types of groups: <br>
87
- - **Software Agent Group**: Commonly used to manage computers. Administrator must install a “remote management agent” on the remote computers. <br>
88
- - **Intel® AMT Agent-less Group**: Exclusive for remote computers that has Intel® AMT activated and needs to be managed independent of a “remote management agent”.
89
-
90
-### Add device
91
-
92
-To add devices into new mesh
93
-
94
-1. Click “Add Agent”,
95
-2. Select the right Operating Systems (Windows* OS) and download the Mesh Agent executable.
96
-3. Copy the Mesh Agent file into remote computers with Windows* OS
97
-
98
- 
99
-4. Run Mesh Agent and Click “install”
100
-
101
- 
102
-
103
-!!! note
104
- Mesh Agent is available for Windows*\* and Linux*\*.
105
-
106
- - *For Windows*\*, the mesh agent doesn’t contain any sensitive data and can copied and reused on many Windows* computers.
107
-
108
- - *For Linux*\*, instead of an executable, an installation script is provided to add remote computers.
109
-
110
- The script checks the type of computer and installs the proper agent automatically.
111
-
112
-### After agent install
113
-
114
-Once the agents are installed, it will take up to a minute before the computer shows up on the user’s account automatically. Click on each computer to access it and user can rename the each computer with a unique name and icons.
115
-
116
-
117
-
118
-
119
-
120
-### Manage Computer
121
-
122
-Click on any computer and go into the “Desktop” and “Files” tabs to remotely manage the computer or perform file transfer.
123
-
124
-
125
-
126
-
127
-
128
-For advance users with console/command line interface experience, go into “Terminal” to perform scripting or quick tasks with CLI tools.
129
-
130
-### Desktop Control
131
-
132
-<div class="video-wrapper">
133
- <iframe width="320" height="180" src="https://www.youtube.com/embed/alknFiojQPM" frameborder="0" allowfullscreen></iframe>
134
-</div>
135
-
136
-Depending on how the agent is connected to the server, there are multiple methods to remote control :
137
-
138
-- *Mesh Agent*,
139
-- *RDP*,
140
-- *and AMT*
141
-
142
-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.
143
-
144
-## 🔐 Server Certificate
145
-
146
-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.
147
-
148
-Users have few ways to handle this certificate warning:
149
-
150
-- Ignore the warning and proceed with an exception in a recurring fashion. However, traffic from the server to the web browser remains encrypted. User must check the validity of the certificate presented by the website and compare with `“webserver-cert-public.crt”` file in the `“meshcentral-data”` folder of the server.
151
-- Add webserver’s root certificate into web browser’s trust list. Click on “Root Certificate” link at the bottom right of login page to download the root certificate of the web server and then add/import this as a trusted certificate into web browser. Some web browser may require a restart before the certificate installation takes effect.
152
-- If you own a domain name that points to your MeshCentral server, you can get a free trusted certificate using Let’s Encrypt (https://letsencrypt.org/). See the section on Let’s Encrypt in this document for more information on this option. MeshCentral has built-in support for Let’ Encrypt.
153
-
154
-!!! danger
155
- Before adding/importing the certificate, user must check the validity of the certificate presented by the website and compare with `“root-cert-public.crt”` file in the `“meshcentral-data”` folder of the server.
156
-
157
-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.
158
-
159
-- If a legitimate trusted certificate is available, replace `“webserver-cert-public.crt”` and `“webserver-cert-private.key” with your certificate. These files are located in “meshcentral-data” folder of the server.
160
-- If intermediate certificates are needed, add the files `“webserver-cert-chain1.crt”`, `“webserver-cert-chain2.crt”`, `“webserver-cert-chain3.crt”` respectively with the intermediate certificates.
161
-
162
-!!! note
163
- If you're using TLS offloading, see the section on “TLS Offloading” cover in the latter parts of this document.
164
-
165
-## 📁 Files and Folder Structure
166
-
167
-It’s important to know the basic file and folder structure from which MeshCentral was installed as shown below
168
-
169
-
170
-
171
-Right after running the `npm install meshcentral` command, the node_module folder will be created which contains meshcentral and all of its dependent modules. When the server executes for the first time, both meshcentral-data and meshcentral-files folders will be created.
172
-
173
-!!! danger
174
- User must periodically backup both meshcentral-data and meshcentral-files which contains all of server’s data.
175
-
176
-
177
-The `“meshcentral-data”` folder will contain:
178
-
179
-- **`meshcentral.db`** :
180
-
181
- The server’s database file which contains all of the user and computer information. This includes account information and other sensitive information.
182
-
183
-- **`Five .key and .crt files`**:
184
-
185
- These are the server’s certificates and private keys. They are used to securely identify the server. The .key files must not be obtained by anyone else since they could be used to impersonate the server.
186
-
187
-- **`config.json file`**:
188
-
189
- This is the server’s configuration file. It first starts with a sample configuration that you can change. In a following section, we will discuss how to edit this file to customize the server.
190
-
191
-The `“meshcentral-files”` folder contains user files that have been uploaded to the server. This folder can be quite large, especially if no user space quota is set in the config.json file. Users can upload a significant amount of files on the server.
192
-
193
-!!! danger
194
- Back-up the “meshcentral-data” folder since this is the folder needed to reconstruct the server if something goes wrong. Without it, user will to start over. Recommended to apply suitable encryption on both folders given that they contain sensitive data.
195
-
196
-## ⚙️ Server Configuration File
197
-
198
-In the “meshcentral-data” folder, there is a file called config.json that contains the main configuration of the server. A sample configuration file could look like this:
199
-
200
-```json
201
- {
202
- "settings": {
203
- "cert": "mesh.myserver.com",
204
- "port": 8080,
205
- "redirport": 81
206
- },
207
- "domains": {
208
- "": {
209
- "title": "MyServer",
210
- "title2": "Servername",
211
- "userQuota": 1048576,
212
- "meshQuota": 248576,
213
- "newAccounts" : 1
214
- },
215
- "Customer1": {
216
- "title": "Customer1",
217
- "title2": "Extra String",
218
- "newAccounts" : 0
219
- }
220
- },
221
- "peers": {
222
- "serverId" : "Server1",
223
- "servers": {
224
- "Server1": { "url": "wss://192.168.1.100:443/" },
225
- "Server2": { "url": "wss://192.168.1.101:443/" }
226
- }
227
- }
228
- }
229
-```
230
-
231
-First, we will look at each of the top levels of the configuration file. The tops levels are `“settings”`, `“domains”`, `“peers”`, and `“smtp”` as shown in the table below.
232
-
233
-
234
-
235
-### Settings
236
-
237
-As indicated before, the settings section of the config.json is equivalent to passing arguments to the server at runtime. In tha folowing table is a list of settings that are available for the user :
238
-
239
-| **Setting** | **Description** |
240
-|------------------|-----------------|
241
-| **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. |
242
-| **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) |
243
-| **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. |
244
-| **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. |
245
-| **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. |
246
-| **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.|
247
-| **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. |
248
-| **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. |
249
-| **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. |
250
-| **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. |
251
-| **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 |
252
-| **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. |
253
-| **MpsAliasPort** | Specify an alias port for the MPS server. See the section on "Server port aliasing" for use of this option. |
254
-| **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. |
255
-| **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. |
256
-| **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. |
257
-| **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. |
258
-| **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. |
259
-| **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. |
260
-| **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. |
261
-| **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. |
262
-| **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. |
263
-| **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 through 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. |
264
-
265
-!!! danger
266
- Changes in config.json will **NOT** take effect until the server is restarted.
267
-
268
-!!! tip
269
- We recommend that you use a non-production server to experiment with the options above.
270
-
271
-### Domains
272
-
273
-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 :
274
-
275
-
276
- - 🔗 [https://servername:8080/](https://servername:8080/) — *Default domain*
277
-
278
- - 🔗 [https://servername:8080/customer1](https://servername:8080/customer1) — *Customer1 domain*
279
-
280
- - 🔗 [https://servername:8080/customer2](https://servername:8080/customer2) — *Customer2 domain*
281
-
282
-
283
-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.
284
-
285
-Each domain has sub-settings as follows:
286
-
287
-| **Sub Settings** | **Description** |
288
-| -------------- | -------- |
289
-| **Title & Title2** | This are the strings that will be displayed at the banner of the website. By default title is set to “MeshCentral” and title2 is set to a version number |
290
-| **UserQuota** | This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a user account. |
291
-| **MeshQuota** | This is the maximum amount of data in kilobytes that can be placed in the “My Files” tab for a given mesh |
292
-| **NewAccounts** | If set to zero (0) | only the administrator of this domain can create new user accounts. If set to one (1), anyone that can access the login page can create new user account |
293
-| **UserAllowedIP** | Allows user to set a list of allowed IP addresses. See section on server IP filtering. |
294
-| **Auth** | This mode is often used in corporate environments. When server is running on Windows and this value is set to “sspi”, domain control authentication to the website is performed. In this mode, no login screen is displayed and browser will authenticate using the user’s domain credentials. |
295
-| **Dns** | The DNS record for this domain. If specified, the domain is accessed using a DNS record like “customer1.servername.com” instead of “servername/customer1”. This feature requires the DNS server to be configured to point this server with a valid DNS record. |
296
-| **CertUrl** | Load the TLS certificate for this domain from this https url. For example “https://127.0.0.1:123”. This option is useful when used along with the “TlsOffload” option. When MeshCentral is not doing any TLS but has a reverse-proxy or TLS offload device doing this work in front of the server, you can use this to have MeshCentral load the certificate from the server in front of MeshCentral.<br><br>This is needed because when agents connect, they need to be told that the certificate they saw upon connecting is the correct one. Using this, MeshCentral will know what certificate the agents are expected to see. |
297
-| **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.<br><br>The value must be set to an object, for example:<br><br>`{ ""min"": 8, ""max"": 128, ""upper"": 1, ""lower"": 1, ""numeric"": 1, ""nonalpha"": 1 }`<br><br>This indicated that passwords must be at least 8 characters long and have at least one upper case, one lower case, one numeric and one non-alphanumeric character. You can also set the maximum length of the password, however MeshCentral has already a limit of 256 characters. Specifying anything above this will have no effect.<br><br>Note that password requirements for Intel® AMT are defined by Intel and so, Intel® AMT passwords will always be verified using a separate set of requirements. |
298
-
299
-!!! note
300
- When the DNS value is set for a domain, a user can't access the domain using `servername/customer1`, and instead, it must be accessed with a valid DNS record, and the DNS server should be setup to have two or more DNS records pointing to the same IP address.
301
-
302
-In this mode, the server will serve a different TLS certificate depending on what DNS record is used to access the server.
303
-
304
-
305
-
306
-As shown in the example above, we have two names that point to the same IP address. Since the configuration specifies the “dns” value, the second domain is only shown when the right name is used. We use “meshcentral” and “devbox” for DNS names, but in practice the user will use fully qualified domain names (FQDN) like “meshcentral.com” or “devbox.meshcentral.com”.
307
-
308
-## 🤝 Server Peering
309
-
310
-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.
311
-
312
-
313
-
314
-Hence, the user is expected to have good understanding on networking, server administration and applications to accomplish this setup. This document will not get into the details of setting up a load-balancer.
315
-
316
-!!! Recommended
317
- 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)
318
-
319
-
320
-
321
-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.
322
-
323
-When Meshcentral is ready for peering setup (5), replicate the “meshcentral-data” directory on each server and configure the “peers” section of the config.json file as shown below.
324
-
325
-```json
326
- {
327
- "peers": {
328
- "serverId" : "Server1",
329
- "servers": {
330
- "Server1": { "url": "wss://192.168.1.100:443/" },
331
- "Server2": { "url": "wss://192.168.1.101:443/" }
332
- }
333
- }
334
- }
335
-```
336
-
337
-The configuration above assumes that server1 has an IP address of `192.168.1.100` and server2 has `192.168.1.101` respectively. The "serverId" value is a short and unique identifier for each server and it is optional. If it's not specified, the computer hostname is used instead.
338
-
339
-The “servers” section of the configuration file should have the identifier of the server followed by each websocket URL and port (generally 443) of the peer servers. If the servers are running with `--tlsoffload`, then use “ws://” for the URL instead of `wss://`.
340
-
341
-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.
342
-
343
-Once peered, all of the servers should act like one single host, no matter which server the user(s) are connected to.
344
-
345
-## 📧 Email Setup
346
-
347
-We highly recommend the use of an email server (SMTP) because we could allow MeshCentral to verify user account’s email address by sending a confirmation request to the user to complete the account registration and for password recovery, should a user forget account password as illustrated below
348
-
349
-A verification email is sent when a new account is created or if the user requests it in the “My Account” tab.
350
-
351
-
352
-
353
-The password recovery flow when “Reset Account” is triggered at the login page.
354
-
355
-
356
-
357
-Both account verification and password recovery are triggered automatically once SMTP mail server configuration is included into the config.json file.
358
-
359
-#### SMTP: User/Pass
360
-##### Normal Server
361
-
362
-Update the config.json with “smtp” section as shown below and restart the server.
363
-
364
-```json
365
-{
366
- "smtp": {
367
- "host": "smtp.server.com",
368
- "port": 25,
369
- "from": "myaddress@server.com",
370
- "user": "myaddress@server.com", # Optional
371
- "pass": "mypassword", # Optional
372
- "tls": false # Optional, default false
373
- }
374
-}
375
-```
376
-
377
-Please map the host, port values to connect to the right host that provides this SMTP service. For “from” value, administrators may put something like donotreply@server.com, but often times it needs to be a valid address since SMTP server will not send out messages with an invalid reply address.
378
-
379
-Some SMTP servers will require a valid username and password to login to the mail server. This is to prevent unauthorized e-mail correspondence. TLS option can be set to ‘true’ if the SMTP server requires TLS.
380
-
381
-##### Gmail
382
-
383
-One option is to configure MeshCentral work with Google Gmail by setting `host` with smtp.gmail.com, and `port` with 587. In the config.json file, use user’s Gmail address for both `from` and “user” and Gmail password in the “pass” value. You will also need to enable “Less secure app access” in for this Google account. It’s in the account settings, security section:
384
-
385
-
386
-
387
-If a Google account is setup with 2-factor authentication, the option to allow less secure applications not be available. Because the Google account password is in the MeshCentral config.json file and that strong authentication can’t be used, it’s preferable to use a dedicated Google account for MeshCentral email.
388
-
389
-#### SMTP: OAuth Authentication
390
-##### Gmail
391
-
392
-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.
393
-
394
-Start by visiting the Google API console:
395
-
396
-> 🔗 [Google Developers Console](https://console.developers.google.com/)
397
-
398
-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"
399
-
400
-
401
-
402
-Click on the "OAuth Consent Screen" link, Under "APIs and Services" from the left hand menu:
403
-
404
-
405
-
406
-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.
407
-
408
-
409
-
410
-Add the Gmail address under which you have created this project to the fields labelled ‘User support email’ and ‘Developer contact information’ so that you will be allowed for authentication. After that, you will want to add a scope for your app, so that your token is valid for gmail:
411
-
412
-
413
-
414
-Once this is complete, the next step will be to add credentials.
415
-
416
-
417
-
418
-Choose OAuth Client
419
-
420
-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.
421
-
422
-Next, you will need to visit the Google OAuth Playground:
423
-
424
-https://developers.google.com/oauthplayground
425
-
426
-
427
-
428
-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.
429
-
430
-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:
431
-
432
-```json
433
-"smtp": {
434
- "host": "smtp.gmail.com",
435
- "port": 587,
436
- "from": "my@googleaccount.com",
437
- "auth": {
438
- "clientId": "<YOUR-CLIENT-ID>",
439
- "clientSecret": "<YOUR-CLIENT-SECRET>",
440
- "refreshToken": "<YOUR-REFRESH-TOKEN>"
441
- },
442
- "user": "noreply@authorizedgooglealias.com",
443
- "emailDelaySeconds": 10,
444
- "tls": false,
445
- "verifyEmail": true
446
- }
447
-```
448
-
449
-
450
-Regardless of what SMTP account is used, MeshCentral will perform a test connection to make sure the server if working as expected when starting. Hence, the user will be notified if Meshcentral and SMTP server has been configured correctly as shown below.
451
-
452
-
453
-
454
-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.
455
-
456
-
457
-
458
-
459
-## 🛢️ Database
460
-
461
-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 `meshcentral.db` will be created in the “meshcentral-data” folder when MeshCentral is first launched. This database works well for small deployments scenarios.
462
-
463
-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.
464
-
465
-### Database Export
466
-
467
-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.
468
-
469
-To export the database, stop the MeshCentral server and run the server again with `--dbexport` and a JSON file called `meshcentral.db.json` will be created in the `meshcentral-data` folder as shown below.
470
-
471
-
472
-
473
-Alternatively, user can also specify the full export path for the JSON file as shown below.
474
-
475
-
476
-
477
-### Database Import
478
-
479
-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.
480
-
481
-!!! danger
482
- Importing a JSON file will overwrite the entire content of the database. A starting empty database is recommended.
483
-
484
-When you are ready to import a JSON file into the database, run meshcentral with `--dbimport` as shown below. If path is not specified, the application will default to use `meshcentral.db.json` that is in `meshcentral-data` folder.
485
-
486
-
487
-
488
-Alternatively, user can specify the full path of the import JSON as shown below.
489
-
490
-
491
-
492
-### Viewing the Database
493
-
494
-For debugging purposes, Meshcentral allow users to have quick preview of certain frequently accessed data in the database with the following options:
495
-
496
-| **Option** | **Description** |
497
-| ------------ | -------------------------------------- |
498
-| **`--showusers`** | List of all users in the database. |
499
-| **`--showmeshes`** | List of all meshes in the database. |
500
-| **`--shownodes`** | List of all nodes in the database |
501
-| **`--showevents`** | List all events in the database |
502
-| **`--showpower`** | List all power events in the database. |
503
-| **`--showall`** | List all records in the database. |
504
-
505
-For example, you can show the list of users with the `--showusers`
506
-
507
-
508
-
509
-### MongoDB Setup
510
-
511
-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 on [MongoDB's website](mongodb.com).
512
-
513
-In this guide, we will focus on the 64-bit version of MongoDB (with SSL support!)'s installer.
514
-
515
-
516
-
517
-After completing the installation,
518
-
519
-1. Stop any instance of MeshCentral that is running locally or on any other machine.
520
-2. Start Terminal or Windows' Command Prompt.
521
-3. Create a folder at the path of `C:\data\db`.
522
-4. Enter MongoDB's `bin` folder and run `mongod --bind 127.0.0.1`.
523
-
524
-This executes the database engine and stores the database data in the default location of `/data/db` and binds a loopback on the local IP of `127.0.0.1`.
525
-
526
-!!! tip
527
- We recommend that you use a non-production server to experiment with the options above.
528
-
529
-
530
-
531
-!!! note
532
- Upon successful execution, MongoDB will begin to wait for connections on its default port of `27017`.
533
-
534
-5. Now run MeshCentral with the command below, and this will tell MeshCentral to connect to MongoDB and use the `meshcentral` database. MongoDB will automatically create this database if it doesn't already exist.
535
-
536
-```bash
537
-node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral
538
-```
539
-
540
-
541
-
542
-6. Alternatively, to transition an existing MeshCentral DB from NeDB to MongoDB, just run the following commands below:
543
-
544
-```bash
545
-node meshcentral --dbexport
546
-```
547
-
548
-```bash
549
-node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral --dbimport
550
-```
551
-
552
-```bash
553
-node meshcentral --mongodb mongodb://127.0.0.1:27017/meshcentral
554
-```
555
-
556
-7. We recommend that you include your MongoDB configuration into MeshCentral's `config.json` to avoid specifying the `--mongodb` argument each time MeshCentral is executed, as shown below:
557
-
558
-```json
559
-{
560
- "settings": {
561
- "mongodb": "mongodb://127.0.0.1:27017/meshcentral",
562
- "mongodbcol": "meshcentral"
563
- }
564
-}
565
-```
566
-
567
-!!! info
568
- By default, MeshCentral will create a single collection called `meshcentral` in the specified database. If you want to specify a different collection name, use the `--mongodbcol` argument or specify the `mongodbcol` variable in MeshCentral's `config.json` for those settings, as shown above.
569
-
570
-If you are using MongoDB with authentication, you can change the URL slightly to add the username and password, for example:
571
-
572
-```
573
-mongodb://username:password@127.0.0.1:27017/meshcentral
574
-```
575
-
576
-You can also provide extra connection parameters, like this:
577
-
578
-```
579
-mongodb://username:password@127.0.0.1:27017/meshcentral?authMechanism=MONGODB-CR&authSource=db
580
-```
581
-
582
-## 🌀 Running State-less
583
-
584
-By default, MeshCentral will read its configuration information from the `meshcentral-data` folder. The most important file in that folder being the `config.json` file, but the folder also contains certificates, branding images, terms of service and more.
585
-
586
-
587
-
588
-After the configuration is read, MeshCentral will connect to its database and continue to start the server. For most user’s this is a perfectly acceptable way to setup the server. However, in some cases, it’s advantageous to setup the server “state-less”. That is, there is no local configuration files at all and everything is in the database. Two examples of this would be when running MeshCentral is a Docker container where we don’t want the container to have any state or for compliance with security specifications where the database is “encrypted at rest”. In this cases, we will load the configuration files into the database and MeshCentral will only be told how to connect to the database.
589
-
590
-
591
-
592
-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.
593
-
594
-To make this happen, we will be using the following command line options from MeshCentral:
595
-
596
-| **Command** | **Description** |
597
-| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
598
-| **`--configkey (key)`** | Specifies the encryption password that will be used to read or write the configuration files to the database. |
599
-| **`--dblistconfigfiles`** | List the names and size of all configuration files in the database. |
600
-| **`--dbshowconfigfile (filename)`** | Show the content of a specified filename from the database. --configkey is required. |
601
-| **`--dbdeleteconfigfiles`** | Delete all configuration files from the database. |
602
-| **`--dbpushconfigfiles '*' or (folder path)`** | Push a set of configuration files into the database, removing any existing files in the process. When * is specified, the “meshcentral-data” folder up pushed into the database. --configkey is required. |
603
-| **`--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. |
604
-| **`--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. |
605
-
606
-Once we have MeshCentral running as expected using the `meshcentral-data` folder, we can simply push that configuration into the database and run using the database alone like this:
607
-
608
-```bash
609
-node ./node_modules/meshcentral --dbpushconfigfiles '*' --configkey mypassword
610
-```
611
-
612
-```bash
613
-node ./node_modules/meshcentral --loadconfigfromdb mypassword --mongodb "mongodb://127.0.0.1:27017/meshcentral"
614
-```
615
-
616
-This first line will load many of the “meshcentral-data” files into the database. At this point, we can back up the `meshcentral-data` folder and remove it. Then run the second line to start the server. Here we use MongoDB, but if one uses NeDB, the `meshcentral.db` file in the “meshcentral-data” folder will still be needed.
617
-
618
-Note that MeshCentral does not currently support placing a Let’s Encrypt certificate in the database. Generally, one would use a reverse proxy with Let’s Encrypt support and TLS offload in the reverse proxy and then run MeshCentral in state-less mode in a Docket container.
619
-
620
-## ⌨️ Commandline Options
621
-
622
-In general, doing `--option value` is the same as adding `"option": value` in the settings section of the config.json.
623
-
624
-Here are the most common options found by running `meshcentral --help`
625
-
626
-```text
627
-Run as a background service
628
- --install/uninstall Install MeshCentral as a background service.
629
- --start/stop/restart Control MeshCentral background service.
630
-
631
-Run standalone, console application
632
- --user [username] Always login as [username] if account exists.
633
- --port [number] Web server port number.
634
- --redirport [number] Creates an additional HTTP server to redirect users to the HTTPS server.
635
- --exactports Server must run with correct ports or exit.
636
- --noagentupdate Server will not update mesh agent native binaries.
637
- --nedbtodb Transfer all NeDB records into current database.
638
- --listuserids Show a list of a user identifiers in the database.
639
- --cert [name], (country), (org) Create a web server certificate with [name] server name.
640
- country and organization can optionally be set.
641
-
642
-Server recovery commands, use only when MeshCentral is offline.
643
- --createaccount [userid] Create a new user account.
644
- --resetaccount [userid] Unlock an account, disable 2FA and set a new account password.
645
- --adminaccount [userid] Promote account to site administrator.
646
-```
647
-
648
-## 🔒 TLS Offloading
649
-
650
-A good way for MeshCentral to handle a high traffic is to setup a TLS offload device at front of the server that takes care of doing all the TLS negotiation and encryption so that the server could offload this. There are many vendors who offer TLS or SSL offload as a software module (Nginx* or Apache*) so please contact your network administrator for the best solution that suits your setup.
651
-
652
-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.
653
-
654
-
655
-
656
-To make this work, it is important the server is setup with `--tlsoffload`. This indicates the server that TLS is already being taken care of and MeshCentral does not have to deal with it. MeshCentral will continue to listen to port 80, 443 and 4433.
657
-
658
-However, incoming port 443 (main web port) and 4433 (Intel® AMT MPS port) will not have TLS but MeshCentral will still put many HTTPS flags in its responses on port 443. By default, if a user accesses http://127.0.0.1:443 without TLS offloader setting, the browser is expected to display warnings. To make this work, TLS offloader device’s ports and functions should be configured correctly like below
659
-
660
-| **Port** | **Function Description** |
661
-| ---- | ---------------------------------------------------------------------- |
662
-| **80** | Directly forwards port 80 to MeshCentral port 80 |
663
-| **443** | Handle TLS using a web certificate and forward to MeshCentral port 443 |
664
-| **4433** | Handle TLS using MPS certificate and forward to MeshCentral port 4433 |
665
-
666
-If possible, port 443 should be configured with a legitimate trusted certificate and the public part of the certificate named as `webserver-cert-public.crt` must be placed inside of `meshcentral-data` folder of the server. When the server is executed in tlsoffload mode, only the public part of the web certificate is used by the server.
667
-
668
-For Intel® AMT MPS port 4433, the certificate files “mpsserver-cert-public.crt” and “mpsserver-cert-public.key” must be copied from the “meshcentral-data” folder and loaded into the TLS offload module.
669
-
670
-!!! note
671
- Please consult the TLS offloader user manual from the respective vendor to configure TLS offloading feature correctly.
672
-
673
-## 📜 Let’s Encrypt support
674
-
675
-MeshCentral makes use of HTTPS to authenticate and encrypt management traffic over the network. By default, a self-signed certificate is used for the MeshCentral HTTPS server. That certificate is not trusted by browsers and so, you get a warning message when visiting the web site. You can solve this but obtaining a free trusted certificate from [Let's Encrypt](https://letsencrypt.org/). There are some limitations and so, it’s best to get familiar with this service before starting. You will also need a valid domain name that you own and that points to your MeshCentral server.
676
-
677
-
678
-
679
-Before moving forward with this section, make sure your MeshCentral server is working correctly, has a domain name pointing to it and that the HTTP redirection server on port 80 is enabled and working. MeshCentral’s HTTP port 80 server will be used in the process to prove to Let’s Encrypt that we have control over the domain. At any point, you may try to use [letsdebug.net](https://letsdebug.net/) to see if your domain is setup correctly and/or debug any issues. When ready, add the “letsencrypt” section to the config.json file like this:
680
-
681
-```json
682
-{
683
- "settings": {
684
- "RedirPort": 80,
685
- },
686
- "letsencrypt": {
687
- "email": "myemail@myserver.com",
688
- "names": "domain1.com,domain2.com",
689
- "rsaKeySize": 3072,
690
- "production": false
691
- },
692
-}
693
-```
694
-
695
-The only mandatory field is the email address, please enter a valid one.
696
-
697
-The names section is a list of domain names the requested certificate will be valid for. This must be a list of DNS names that are already pointing to your server. It’s important to understand you are not requesting these DNS names, rather, Let’s Encrypt will makes requests to prove control over all of these domain name before issuing the certificate. All the domain names you enter must point to the server and HTTP port 80 must be reachable over the internet. If you don’t specify names, the default MeshCentral certificate name is used, that is the configured `--cert [name]`.
698
-
699
-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.
700
-
701
-Lastly the production key, by default this is false. When set to false, MeshCentral will query the Let’s Encrypt staging server for a certificate. It’s highly recommended to try this first and make sure everything works before getting a real certificate. Keep production to false, run through the process at least once and make sure everything works. You will get a new certificate installed on the HTTPS server signed by a staging Let’s Encrypt certificate authority.
702
-
703
-The Let’s Encrypt certificates and files will be created in the “meshcentral-data” folder. Make sure to keep regular backups of the “meshcentral-data” folder and all sub-folders.
704
-
705
-
706
-
707
-Once you placed the “letsencrypt” section in config.json, restart the server. The request to the Let’s Encrypt server may take a few minutes to a few hours. It’s best to have your DNS server name pointing to your server for over a day before doing this. Once the new certificate is received, the server will automatically restart and browsing to HTTPS on your server will show the new certificate. Here is what it looks like on FireFox:
708
-
709
-
710
-
711
-If you successfully setup a Let’s Encrypt certificate using the Let’s Encrypt staging server (“production”: false) and everything looks good, stop the server, remove the “letsencrypt” folder in “meshcentral-data”, change production to “true” and start the server again. You should get a real certificate in a few minutes to a few hours. MeshCentral will automatically renew the certificate a few days before it expires. The MeshCentral self-signed certificate will still be present in the “meshcentral-data” folder, this is normal and there is no need to manually copy the Let’s Encrypt certificate to the “meshcentral-data” folder. If something goes wrong with the Let’s Encrypt certificate, the server will fall back to using the self-signed one.
712
-
713
-!!! note
714
- Please be patient with Let’s Encrypt certificate requests and make sure you correctly get a staging certificate before setting production to true.
715
-
716
-If Let’s Encrypt works for you, please consider donating to them as they provide a critical service to the Internet community.
717
-
718
-## 🛡️ Server IP filtering
719
-
720
-For improved security, it’s good to limit access to MeshCentral with IP address. For example, we want to allow mesh agents and Intel AMT computers to connect from anywhere, but whitelist IP address for users that we allow to access MeshCentral.
721
-
722
-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.
723
-
724
-```json
725
- {
726
- "domains": {
727
- "": {
728
- "userallowedip" : "1.2.3.4,1.2.3.5",
729
- }
730
- }
731
- }
732
-```
733
-
734
-IP addresses are separated by a comma. As a result, only users coming these IP addresses will be able to see the server’s login page as illustrated below. Other IP addresses will be blocked effectively.
735
-
736
-
737
-
738
-!!! note
739
- When an IP address whitelist is in effect, MeshAgent's connection from any IP address will be not affected.
740
-
741
-You can also use files for IP lists
742
-
743
-```json
744
-"userAllowedIp": "file:userallowedips.txt",
745
-"userBlockedIp": "file:userblockedips.txt",
746
-"agentAllowedIp": "file:agentallowedips.txt"
747
-```
748
-
749
-Place the file in the `meshcentral-data` folder.
750
-
751
-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.
752
-
753
-```txt
754
-# My list of blocked IP's
755
-185.101.70.0/24
756
-185.46.85.0/24
757
-37.9.44.0/24
758
-37.9.45.0/24
759
-5.189.205.0/24
760
-5.189.206.0/24
761
-5.189.207.0/24
762
-5.62.153.0/24
763
-5.62.156.0/24
764
-5.62.158.0/24
765
-
766
-# One more list
767
-5.8.44.0/24
768
-5.8.45.0/24
769
-5.8.46.0/24
770
-79.110.28.0/24
771
-79.110.31.0/24
772
-91.204.14.0/24
773
-95.181.218.0/24
774
-95.85.81.0/24
775
-```
776
-
777
-
778
-## 🧩 Embedding MeshCentral
779
-
780
-One interesting way to use MeshCentral is to embed its features into another web site. In other words, certain feature of MeshCentral can be selectively embedded into another website such as Remote Desktop or File Transfer.
781
-
782
-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.
783
-
784
-
785
-
786
-To make this work, a following key alignment is required :
787
-
788
-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.
789
-
790
-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.
791
-
792
-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.
793
-
794
-In this section we will review both the login token and embedding options mentioned above.
795
-
796
-### Login Token
797
-
798
-With MeshCentral, it’s possible to login to the main web page without even seeing the login screen. Of course, you can do this by specifying `--nousers` or `--user admin` when you run the server, but these approach are not secure as it removes user authentication for those accessing the server.
799
-
800
-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.
801
-
802
-To enable this feature, configure `config.json` file to allow login tokens.
803
-
804
-```json
805
-{
806
- "settings": {
807
- "allowLoginToken": true,
808
- "allowFraming": true
809
- }
810
-}
811
-```
812
-
813
-Set both allowLoginToken and allowFraming to `true` to use login tokens along with framing MeshCentral within another web page.
814
-
815
-Next, create a token. Execute MeshCentral with the `--logintoken [userid]` switch and userid value with the example below:
816
-
817
-
818
-
819
-The `userid` is actually a combination of three values - user, domain, and username in a single string `user/domain/username`. The example above is using a default domain which is empty hence, the userid will be just `user//admin” to request for login token. Domains are only used if the server in multi-tenancy mode as discussed in previous chapters.
820
-
821
-The resulting hashed base64 encoded blob can be used as a login token for 1 hour. Simply add the “?login=” followed by the token value generated to the URL of the webserver. For an e.g. https://localhost/?login=23tY7@wNbPoPLDeXVMRmTKKrqVEJ3OkJ. The login page is expected to be skipped and automatically login the user admin. This is just a manual attempt to token based login.
822
-
823
-Now, to have this work seamlessly with a different website, we should generate a login token key. A token key can be used to generate login tokens whenever needed for MeshCentral. Generate this key with `--loginTokenKey` switch as shown below
824
-
825
-
826
-
827
-The generated masker key must be placed in a secure location within the business website.
828
-
829
-
830
-
831
-As illustrated above, we see the business site using the token key to generate a login token and embed it into the response web page. The user’s browser then loads the iframe that includes both the URL with the login token for MeshCentral. MeshCentral can then verify the token and allow the web page to load as expected.
832
-
833
-### Embedding Options
834
-
835
-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. IMPORTANT: ALL VALUES ARE CASE SENSITIVE!
836
-
837
-| Embedding Options / URL Argument | Description | Values |
838
-| -------------------------------- | ----------- | ------ |
839
-| **viewmode** | Indicates the information to show. (always required!) This is an integer value, possible values are: | 1 = Devices tab<br>2 = Account tab<br>3 = Events Live<br>4 = Users General<br>5 = Server files tab<br>6 = Server General<br>10 = Device general information<br>11 = Device remote desktop<br>12 = Device terminal<br>13 = Device files<br>14 = Device Intel AMT console<br>15 = Device Mesh Agent console<br>16 = Device events<br>17 = Device info<br>19 = Device plugins<br>20 = Mesh General<br>21 = Mesh Summary<br>30 = User General<br>31 = User Events<br>40 = Server Stats<br>41 = Server Trace<br>42 = Server Plugins<br>50 = Users Groups<br>52 = Users Recordings<br>60 = Events Report<br>115 = Server Console<br><br>**Note**: For values 10-19, a node identifier must be specified. For values 20-29, a mesh identifier must be specified. For values 30-39, a user identifier must be specified. For values 50-59, a user group identifier may be required. |
840
-| **hide** | Indicates which portion of the web page to hide. This is a bitmask integer hence it will need the sum of values. For example: To hide all of the values, add 1+2+4+8 and use 15 as the value. | 1 = Hide the page header<br>2 = Hide the page tab<br>4 = Hide the page footer<br>8 = Hide the page title<br>16 = Hide the left tool bar<br>32 = Hide back buttons |
841
-| **gotonode** | Optional unless Viewmode is set to value of 10-19. Indicates which node to show on the screen. For example, if we want to embed the remote desktop page for a given node and hide the header, tabs, footer and page title, we could have this URL: `https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15` | Node or NodeID is a long base64 encoded SHA384 value |
842
-| **gotodevicename** | Same like gotonode but go directly to a node with its name (nickname, NOT OS name) | Node or NodeID is a long base64 encoded SHA384 value |
843
-| **gotodevicername** | Same like gotonode but go directly to a node with its OS name (generally same as name/nickname) | Node or NodeID is a long base64 encoded SHA384 value |
844
-| **gotodeviceip** | Same like gotonode but go directly to a device with a certain IP. (this wont work for devices with external ip addreses, its meant for internal ips and amt for example) | Node or NodeID is a long base64 encoded SHA384 value |
845
-| **gotomesh** | go directly to the mesh general page of the device group | Node or NodeID is a long base64 encoded SHA384 value |
846
-
847
-!!! example
848
- Typically, the URL for the website is followed by `?` then a set of name=value pairs separated by `&`.
849
-
850
-Based on the URL https://localhost/?node=UkSNlz7t...2Sve6Srl6FltDd&viewmode=11&hide=15 , the nodeID starts with “UkSNlz7t”. We shortened the value in this example, but it’s normally a long base64 encoded SHA384 value. The Viewmode set to 11 which is the remote desktop page and Hide set to 15 to hide everything. Hence the user may see as illustrated below.
851
-
852
-
853
-
854
-Only the remote desktop viewer will be displayed embedded within an iframe.
855
-
856
-!!! note
857
- You must set `allowFraming` to true in the `config.json` of the server. This is in addition to the Node, Viewmode and Hide arguments, the login token must be specified to add complex features into another website.
858
-
859
-## 🔀 Server port aliasing
860
-
861
-In some cases, you may be setting up a server on a private network that uses non-standard ports, but use a router or firewall in front to perform port mapping. So, even if the server privately uses non-standard ports, the public ports are the standard ports 80 and 443. You have to tell MeshCentral to bind to private ports but pretend it’s using the other standard ports when communicating publicly. To make this work, MeshCentral supports port aliasing.
862
-
863
-For example you can run :
864
-
865
-```bash
866
- node meshcentral --redirport 2001 --port 2002 --aliasport 443
867
-```
868
-
869
-
870
-
871
-Here, the server binds the HTTP and HTTPS ports to 2001 and 2002, but the server will externally indicate to MeshAgents and browsers that they must connect to port 443.
872
-
873
-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.
874
-
875
-In the following picture we have a usual server running with :
876
-
877
-```bash
878
-node meshcentral --cert Server1 --port 443 --mpsport 4433
879
-```
880
-
881
-
882
-
883
-We can setup the server so that MeshAgent and Intel AMT will connect on port 443 of two different IP address or names like this:
884
-
885
-```bash
886
-node meshcentral --cert Server1 --mpscert Server2 --port 443 --mpsport 4433 --mpsaliasport 443
887
-```
888
-
889
-
890
-
891
-In the second example, the server on the right is running HTTPS on port 443 and MPS on port 4433 as usual, but the MPS is now presenting a certificate that has the name `Server2` on it. The server will also configure Intel AMT CIRA to connect to `Server2:443`.
892
-
893
-A router or firewall that is located in front of the MeshCentral server needs to be configured correctly to forwarding :
894
-
895
-```bash
896
-Server1:443 -> 443 on MeshCentral
897
-```
898
-```bash
899
-Server2:443 -> 4433 on MeshCentral
900
-```
901
-
902
-The routing of IP and ports by the firewall shown on the picture must be configured separately from MeshCentral using separate software. Typically, routers or firewalls have the proper controls to configure this type of traffic routes.
903
-
904
-## 📡 Web relay using DNS names and multiple web relays
905
-
906
-MeshCentral has a web relay feature that allows a user to access remote web sites through 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.
907
-
908
-## 🎬 Video Walkthroughs
909
-
910
-<div class="video-wrapper">
911
- <iframe width="320" height="180" src="https://www.youtube.com/embed/GU7MQjkPSd8" frameborder="0" allowfullscreen></iframe>
912
-</div>
913
-<div class="video-wrapper">
914
- <iframe width="320" height="180" src="https://www.youtube.com/embed/INOvsHXNOKY" frameborder="0" allowfullscreen></iframe>
915
-</div>
916
-
917
-## 🖧 Device Groups with Relay Agent
918
-
919
-MeshCentral supports the local device group allowing devices that do not have an agent to be managed through 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.
920
-
921
-
922
-
923
-
924
-
925
-To enable SSH support, add this line to the domain section of your `config.json`:
926
-
927
-```json
928
-"ssh": true
929
-```
930
-
931
-### Video Walkthrough
932
-
933
-<div class="video-wrapper">
934
- <iframe width="320" height="180" src="https://www.youtube.com/embed/TtW5-g6SeZQ" frameborder="0" allowfullscreen></iframe>
935
-</div>
936
-
937
-
938
-### Raritan and WebPowerSwitch with Relay
939
-
940
-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.
941
-
942
-
943
-
944
-
945
-
946
-
947
-
948
-## 🧭 NGINX Reverse-Proxy Setup
949
-
950
-### Video Walkthrough
951
-
952
-<div class="video-wrapper">
953
- <iframe src="https://www.youtube.com/embed/YSmiLyKSX2I" frameborder="0" allowfullscreen></iframe>
954
-</div>
955
-
956
-Sometimes it’s useful to setup MeshCentral with a reverse-proxy in front of it. This is useful if you need to host many services on a single public IP address, if you want to offload TLS and perform extra web caching. In this section we will setup NGINX, a popular reverse-proxy, in front of MeshCentral. NGNIX is available at: [Nginx](https://www.nginx.com/)
957
-
958
-
959
-
960
-In this example, we will :
961
-
962
-- Run MeshCentral on non-standard ports, but alias HTTPS to port 443.
963
-- NGINX will be using standard ports 80 and 443.
964
-- We will have NGINX perform all TLS authentication & encryption.
965
-- MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.
966
-- NGINX will be setup with long timeouts, because agents have long standard web socket connections.
967
-
968
-!!! note
969
- With SELinux, NGINX reverse proxy requires 'setsebool -P httpd_can_network_relay 1'
970
- Caution: httpd_can_network_relay only allows certain ports
971
- Confirm you are using ports from this subset in MeshCentral
972
- If you want to use a different port then you will need to add it to http_port_t
973
-
974
-Let’s get started by configuring MeshCentral with the following values in `config.json`:
975
-
976
-```json
977
-{
978
- "settings": {
979
- "Cert": "myservername.domain.com",
980
- "Port": 4430,
981
- "AliasPort": 443,
982
- "RedirPort": 800,
983
- "AgentPong": 300,
984
- "TlsOffload": "127.0.0.1"
985
- },
986
- "domains": {
987
- "": {
988
- "certUrl": "https://127.0.0.1:443/"
989
- }
990
- }
991
-}
992
-```
993
-
994
-With this configuration, MeshCentral will be using port 4430 instead of port 443, but because “TlsOffload” is set, TLS will not be performed on port 4430. The server name is set to `myservername.domain.com`, so that is the name that MeshCentral will give to agents to connect to. Also, the alias port is set to 443. So agents will be told to connect to “myservername.domain.com:443”.
995
-
996
-The “AgentPong” line instructs the server to send data to the agent each 300 seconds and the agent by default will send data to the server every 120 seconds. As long as NGINX timeouts are longer than this, connections should remain open.
997
-
998
-When agents connect, they will see the NGINX TLS certificate on port 443. MeshCentral needs to know about the NGINX certificate so that it can tell the agents this is the correct certificate they should expect to see. So, “certUrl” is used to tell MeshCentral where to get the certificates that agents will see when connecting.
999
-
1000
-When NGINX forwards connections to MeshCentral, extra X-Forwarded headers will be added to each request. MeshCentral needs to know if these headers can be trusted or not. By setting “TlsOffload” to “127.0.0.1”, MeshCentral is told to trust these headers when requests come from “127.0.0.1”.
1001
-
1002
-In this example, make sure to change “127.0.0.1” to the IP address of NGINX and “Cert” to the external DNS name of the NGINX server.
1003
-
1004
-Next, we need to configure and launch NGINX. Here is an ngnix.conf to get started:
1005
-
1006
-```json
1007
-worker_processes 1;
1008
-
1009
-events {
1010
- worker_connections 1024;
1011
-}
1012
-
1013
-http {
1014
- # HTTP server. In this example, we use a wildcard as server name.
1015
- server {
1016
- listen 80;
1017
- server_name _;
1018
-
1019
- location / {
1020
- proxy_pass http://127.0.0.1:800/;
1021
- proxy_http_version 1.1;
1022
-
1023
- # Inform MeshCentral about the real host, port and protocol
1024
- proxy_set_header X-Forwarded-Host $host:$server_port;
1025
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
1026
- proxy_set_header X-Forwarded-Proto $scheme;
1027
- }
1028
- }
1029
-
1030
- # HTTPS server. In this example, we use a wildcard as server name.
1031
- server {
1032
- listen 443 ssl;
1033
- server_name _;
1034
-
1035
- # MeshCentral uses long standing web socket connections, set longer timeouts.
1036
- proxy_send_timeout 330s;
1037
- proxy_read_timeout 330s;
1038
-
1039
- # We can use the MeshCentral generated certificate & key
1040
- ssl_certificate webserver-cert-public.crt;
1041
- ssl_certificate_key webserver-cert-private.key;
1042
- ssl_session_cache shared:WEBSSL:10m;
1043
- ssl_ciphers HIGH:!aNULL:!MD5;
1044
- ssl_prefer_server_ciphers on;
1045
-
1046
- location / {
1047
- proxy_pass http://127.0.0.1:4430/;
1048
- proxy_http_version 1.1;
1049
-
1050
- # Allows websockets over HTTPS.
1051
- proxy_set_header Upgrade $http_upgrade;
1052
- proxy_set_header Connection "upgrade";
1053
- proxy_set_header Host $host;
1054
-
1055
- # Inform MeshCentral about the real host, port and protocol
1056
- proxy_set_header X-Forwarded-Host $host:$server_port;
1057
- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
1058
- proxy_set_header X-Forwarded-Proto $scheme;
1059
- }
1060
- }
1061
-}
1062
-```
1063
-
1064
-As indicated in the comments of this NGINX configuration file, we set timeouts to be really long. We forward HTTP port 80 and HTTPS port 443 to the corresponding ports on MeshCentral. In this example, we happen to use the web certificates that where generated by MeshCentral, but any certificate is ok. We also add extra “X-Forward” headers, this tells MeshCentral information that would normally be hidden by NGINX, like the client’s IP address and more.
1065
-
1066
-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:
1067
-
1068
-```bash
1069
-MeshCentral HTTP redirection web server running on port 800.
1070
-Loaded RSA web certificate at https://127.0.0.1:443/, SHA384: d9de9e27a229b5355708a3672fb23237cc994a680b3570d242a91e36b4ae5bc96539e59746e2b71eef3dbdabbf2ae138.
1071
-MeshCentral Intel(R) AMT server running on myservername.domain.com:4433.
1072
-MeshCentral HTTP web server running on port 4430, alias port 443.
1073
-```
1074
-
1075
-Notice on the second line, MeshCentral will have loaded the web certificate from NGNIX and display a matching hash. That is it, navigating to port 80 and 443 on NGINX should show the MeshCentral web page and agents should connect as expected.
1076
-
1077
-### CIRA Setup with NGINX
1078
-
1079
-We can add on the section above and support reverse proxy for Intel® AMT Client Initiated more Access (CIRA) connecting that come to the server. Normally, CIRA connections come on port 4433 and use TLS.
1080
-
1081
-
1082
-
1083
-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:
1084
-
1085
-```json
1086
-stream {
1087
- # Internal MPS servers, in this case we use one MeshCentral MPS server is on our own computer.
1088
- upstream mpsservers {
1089
- server 127.0.0.1:44330 max_fails=3 fail_timeout=30s;
1090
- }
1091
-
1092
- # We can use the MeshCentral generated MPS certificate & key
1093
- ssl_certificate mpsserver-cert-public.crt;
1094
- ssl_certificate_key mpsserver-cert-private.key;
1095
- ssl_session_cache shared:MPSSSL:10m;
1096
- ssl_ciphers HIGH:!aNULL:!MD5;
1097
- ssl_prefer_server_ciphers on;
1098
-
1099
- # MPS server.
1100
- server {
1101
- listen 4433 ssl;
1102
- proxy_pass mpsservers;
1103
- proxy_next_upstream on;
1104
- }
1105
-}
1106
-
1107
-NGINX will listen on port 4433, decrypt the connection and forward it to 44330 on the loopback interface. We are going to be used the “mpsserver” certificate that was created by MeshCentral as the TLS server certificate for port 4433. Now, we just have to make a few changes to the MeshCentral config.json file.
1108
-
1109
-{
1110
- "settings": {
1111
- "Cert": "myservername.domain.com"
1112
- "Port": 4430,
1113
- "AliasPort": 443,
1114
- "RedirPort": 800,
1115
- "TlsOffload": "127.0.0.1"
1116
- "MpsPort": 44330,
1117
- "MpsAliasPort": 4433,
1118
- "MpsTlsOffload": true
1119
- },
1120
- "domains": {
1121
- "": {
1122
- "certUrl": "https://127.0.0.1:443/"
1123
- }
1124
- }
1125
-}
1126
-```
1127
-
1128
-In this new config.json, we added 3 lines. First, the MeshCentral Management Presence Server (MPS) is now on port 44330. However, the MpsAliasPort value indicates that externally, port 4433 will be used, so we need to configure Intel AMT to connect to port 4433. Lastly, we want to disable TLS support on port 44330 by setting “MpsTlsOffload” to true.
1129
-
1130
-With this configuration, Intel AMT CIRA connections will come in and TLS will be handled by NGINX. With this setup, it’s not possible to configure Intel AMT CIRA to connect using mutual-TLS authentication, only username/password authentication is used.
1131
-
1132
-
1133
-##🚦Traefik Reverse-Proxy Setup
1134
-
1135
-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/
1136
-
1137
-This section covers a really simple Traefik configuration. Traefik is capable of a lot more complex configurations.
1138
-
1139
-
1140
-
1141
-In this example, we will:
1142
-
1143
-- MeshCentral on non-standard ports, but alias HTTPS to port 443.
1144
-- Traefik will be using standard ports 80 and 443.
1145
-- We will have Traefik perform all TLS authentication & encryption.
1146
-- MeshCentral will read the NGINX web certificate so agents will perform correct server authentication.
1147
-
1148
-First we will start with the MeshCentral configuration, here is a minimal configuration that will work:
1149
-
1150
-```json
1151
-{
1152
- "settings": {
1153
- "Cert": "myservername.domain.com",
1154
- "Port": 4430,
1155
- "AliasPort": 443,
1156
- "RedirPort": 800,
1157
- "TlsOffload": "127.0.0.1"
1158
- },
1159
- "domains": {
1160
- "": {
1161
- "certUrl": "https://127.0.0.1:443/"
1162
- "AgentConfig": [ "webSocketMaskOverride=1" ]
1163
- }
1164
- }
1165
-}
1166
-```
1167
-
1168
-!!! note
1169
- Relating to the `agentConfig` line, due to Traefik not supporting web socket connections that aren't “masked”, we have to tell MeshAgents to mask web socket connections using this line. Once set, any new agent will be installed with websocket masking turned on. Also note that we will be running MeshCentral on port HTTPS/4430 and HTTP/800. However, we also indicate to MeshCentral that HTTPS will really be on port 443 using the `AliasPort` line.
1170
-
1171
-The `TlsOffload` line indicates that MeshCentral should not perform TLS on port 4430. And the `certUrl` line indicates what URL can be used to load the external certificate that will be presented on port 443 in front of MeshCentral.
1172
-
1173
-Now that we have MeshCentral setup, let’s take a look at a sample Traefik configuration file. In this case, we will manually configure the entrypoints, frontends and backends within the Traefik configuration file. There is a basic configuration file for Traefik 1.7:
1174
-
1175
-```json
1176
-[global]
1177
- checkNewVersion = false
1178
- sendAnonymousUsage = false
1179
-
1180
-[entryPoints]
1181
- [entryPoints.http]
1182
- address = ":80"
1183
- [entryPoints.http.redirect]
1184
- entryPoint = "https"
1185
- [entryPoints.https]
1186
- address = ":443"
1187
- [entryPoints.https.tls]
1188
- [[entryPoints.https.tls.certificates]]
1189
- certFile = "webserver-cert-public.crt"
1190
- keyFile = "webserver-cert-private.key"
1191
-
1192
-[file]
1193
-
1194
-[backends]
1195
- [backends.backend1]
1196
- [backends.backend1.healthcheck]
1197
- path = "/health.ashx"
1198
- interval = "30s"
1199
-
1200
- [backends.backend1.servers.server1]
1201
- url = "http://127.0.0.1:4430"
1202
- weight = 1
1203
-
1204
-[frontends]
1205
- [frontends.frontend1]
1206
- entryPoints = ["https"]
1207
- backend = "backend1"
1208
- passHostHeader = true
1209
- [frontends.frontend1.routes]
1210
- [frontends.frontend1.routes.main]
1211
- rule = "Host:myserver.domain.com,localhost"
1212
-
1213
-[api]
1214
- entryPoint = "traefik"
1215
- dashboard = true
1216
-```
1217
-
1218
-The enterPoints section shows we have two entry points, port 80 will be redirected to port 443. Traefik will perform this redirection so MeshCentral will never see port 80 connections. Port 443 will be setup using the given TLS certificates. In this example, we just used the certificate files generated by MeshCentral in the “meshcentral-data” folder. You can use the two certificate files as-is.
1219
-
1220
-The backends section configures one MeshCentral server on port “4430”. Traefik will additionally check the health of the MeshCentral server periodically, every 30 seconds.
1221
-
1222
-The frontends section is what routes the connections coming in the entry points to the backend servers. In this case, the HTTPS entry point is routed to the MeshCentral server is the hostname matches `myserver.domain.com` or `localhost`.
1223
-
1224
-Finally, the API section creates a web portal on port 8080 for monitoring of Traefik.
1225
-
1226
-## ⚡ HAProxy Reverse-Proxy Setup
1227
-
1228
-In this section, we will setup MeshCentral with HAProxy, a small popular reverse proxy software. This section will be much like the previous sections setting up NGNIX and Traefik but with a different software and configuration file. HAProxy is free and available at: [HAProxy Official Website](https://www.haproxy.org/)
1229
-
1230
-
1231
-
1232
-This section covers a really simple configuration. HAProxy is capable of a lot more complex configurations. In the following example, HAProxy will perform TLS and forward the un-encrypted traffic to MeshCentral on port 444. HAProxy will add extra “X-Forwarded-Host” headers to the HTTP headers so that MeshCentral will know from the IP address the connection comes from.
1233
-
1234
-
1235
-
1236
-In the following configuration file, we have browser connections on port 80 being redirected to HTTPS port 443. We also have Let’s Encrypt cert bot for getting a real TLS certificate and “mesh.sample.com” being redirected to 127.0.0.1:444.
1237
-
1238
-```yaml
1239
-global
1240
- log /dev/log local0
1241
- log /dev/log local1 notice
1242
- chroot /var/lib/haproxy
1243
- stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners
1244
- stats timeout 30s
1245
- user haproxy
1246
- group haproxy
1247
- daemon
1248
-
1249
-defaults
1250
- log global
1251
- mode http
1252
- option httplog
1253
- option dontlognull
1254
- option forwardfor
1255
- option http-server-close
1256
-
1257
-frontend http
1258
- bind *:80
1259
- redirect scheme https code 301 if !{ ssl_fc }
1260
-
1261
-frontend https
1262
- bind *:443 ssl crt /etc/haproxy/cert.pem
1263
- http-request add-header X-Forwarded-Proto https
1264
- acl acmepath path_beg /.well-known/acme-challenge/
1265
- acl meshcentralhost hdr(host) -i mesh.sample.com
1266
- acl meshcentralhost hdr(host) -i mesh.sample.com:443
1267
- use_backend acme if acmepath
1268
- use_backend meshcentral if meshcentralhost
1269
-
1270
-backend acme
1271
- server certbot localhost:54321
1272
-
1273
-backend meshcentral
1274
- http-request add-header X-Forwarded-Host %[req.hdr(Host)]
1275
- server meshcentral 127.0.0.1:444
1276
-```
1277
-
1278
-On the MeshCentral side, we are not going to use port 80 and need the main HTTPS port to not perform TLS and listen on port 444.
1279
-
1280
-
1281
-```json
1282
-{
1283
- "settings": {
1284
- "Cert": "myservername.domain.com",
1285
- "Port": 444,
1286
- "AliasPort": 443,
1287
- "RedirPort": 0,
1288
- "TlsOffload": "127.0.0.1"
1289
- },
1290
- "domains": {
1291
- "": {
1292
- "certUrl": "https://127.0.0.1:443/"
1293
- }
1294
- }
1295
-}
1296
-```
1297
-
1298
-We also specify “127.0.0.1” in TLS offload since we want MeshCentral to make use of the X-Forwarded-Host header that is set by HAProxy.
1299
-
1300
-## 🏭 Running in a Production Environment
1301
-
1302
-When running MeshCentral is a production environment, administrators should set NodeJS to run in production mode. There is a good article here (http://www.hacksparrow.com/running-express-js-in-production-mode.html) on what this mode is and how to set it. This mode will also boost the speed of the web site on small devices like the Raspberry Pi. To run in production mode, the environment variable “NODE_ENV” must be set to “production”.
1303
-
1304
-- On Linux, this is done like this:
1305
-
1306
-```bash
1307
-export NODE_ENV=production
1308
-```
1309
-
1310
-- On Windows, it’s done like this:
1311
-
1312
-```shell
1313
-SET NODE_ENV=production
1314
-```
1315
-
1316
-Special care must be taken to set the environment variable in such a way that if the server is rebooted, this value is still set. Once set, if you run MeshCentral manually, you will see :
1317
-
1318
-```bash
1319
-MeshCentral HTTP redirection web server running on port 80.
1320
-MeshCentral v0.2.2-u, Hybrid (LAN + WAN) mode, Production mode.
1321
-MeshCentral Intel(R) AMT server running on devbox.mesh.meshcentral.com:4433.
1322
-MeshCentral HTTPS web server running on devbox.mesh.meshcentral.com:443.
1323
-```
1324
-
1325
-In production mode, ExpressJS will cache some files in memory making the web server much faster and any exceptions thrown by the ExpressJS will not result in the stack trace being sent to the browser.
1326
-
1327
-## 📲 Two step authentication
1328
-
1329
-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.
1330
-
1331
-To get this features setup, users will need to go to the “My Account” tab or the “My Account” menu in the mobile application. They then select, “Add 2-stop login” and follow the instructions.
1332
-
1333
-
1334
-
1335
-Note that if a user performs a password recovery using email, the 2-step authentication is then turned off and will need to be turned on again. This is not idea as someone being able to intercept the user’s email could still log into the web site. Users should make sure to properly protect their email account.
1336
-
1337
-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.
1338
-
1339
-<div class="video-wrapper">
1340
- <iframe width="320" height="180" src="https://www.youtube.com/embed/FvDHlcdNepQ" frameborder="0" allowfullscreen></iframe>
1341
-</div>
1342
-
1343
-And taking authentication to the next step is removing the login page entirely. Use LoginKey 3FA with MeshCentral.
1344
-
1345
-<div class="video-wrapper">
1346
- <iframe width="320" height="180" src="https://www.youtube.com/embed/-WKY8Wy0Huk" frameborder="0" allowfullscreen></iframe>
1347
-</div>
1348
-
1349
-You can also setup [Duo 2FA](https://github.com/Ylianst/MeshCentral/blob/master/docs/docs/meshcentral/security.md#duo-2fa-setup) which is a commertial offering.
1350
-
1351
-## 💾 Server Backup & Restore
1352
-
1353
-It’s very important that the server be backed up regularly and that a backup be kept offsite. Luckily, performing a full backup of the MeshCentral server is generally easy to do. For all installations make sure to back up the following two folders and all sub-folders.
1354
-
1355
- 1. `meshcentral-data`
1356
- 2. `meshcentral-files`
1357
-
1358
-If using NeDB that is built into MeshCentral, you are done. If you are running MongoDB, you will need to perform an extra step. In the command shell, run mongodump to archive all of the MongoDB databases.
1359
-
1360
-```bash
1361
-mongodump --archive=backup.archive
1362
-```
1363
-
1364
-Then, keep the backup.archive file in a safe place. It’s critical that the content of meshcentral-data be backed up in a secure location and preferably using encryption, this is because it contains certificates that give this server its unique personality. Once agents are installed, they will only connect to this server and no other. If you reinstall MeshCentral, even if it is with the same domain name, agents will not connect to the new server since the server certificates are different. Also, someone with access to a backup of “meshcentral-data” could impersonate the server.
1365
-
1366
-To restore back backup, just install a MeshCentral server, make sure it works correctly. Stop it, wipe the old `meshcentral-data` and `meshcentral-files` and put the backup version instead. If using MongoDB, copy the backup.archive back, make sure to clean up any existing “meshcentral” database, run `mongo` and type:
1367
-
1368
-```bash
1369
-use meshcentral
1370
-```
1371
-
1372
-```bash
1373
-db.dropDatabase()
1374
-```
1375
-
1376
-Then exit with Ctrl-C and run:
1377
-
1378
-```bash
1379
-mongorestore --archive=backup.archive
1380
-```
1381
-
1382
-This will re-import the database from the backup. You can then start MeshCentral again.
1383
-
1384
-!!! note
1385
- The two values for `backup` and `restore` in the json are only valid for databases backed by NeDB
1386
-
1387
-### Backup to Google Drive
1388
-
1389
-```bash
1390
-sudo systemctl stop meshcentral.service
1391
-```
1392
-
1393
-```bash
1394
-nano /opt/meshcentral/meshcentral-data/config.json
1395
-```
1396
-
1397
-Remove underscored items
1398
-
1399
-
1400
-
1401
-```bash
1402
-sudo systemctl start meshcentral.service
1403
-```
1404
-
1405
-```bash
1406
-sudo systemctl status meshcentral.service
1407
-```
1408
-
1409
-Log into your MC:
1410
-
1411
-
1412
-
1413
-
1414
-
1415
-Create desktop app
1416
-
1417
-
1418
-
1419
-Enter the Client ID and Client Secret into MC
1420
-
1421
-
1422
-
1423
-
1424
-
1425
-## 🗝️ HashiCorp Vault support
1426
-
1427
-MeshCentral has built-in support for HashiCorp Vault so that all configuration and certificates used by MeshCentral are retrieved from a Vault server. Vault is a secret store server and when used with MeshCentral, the MeshCentral server will not be storing any secrets locally. You can get started with Vault here: [HashiCorp Vault Official Site](https://www.vaultproject.io/)
1428
-
1429
-Once you got a MeshCentral server working correctly, you can start a simple demonstration Vault server by typing:
1430
-
1431
-```bash
1432
-vault server -dev
1433
-```
1434
-
1435
-When you run the server in developer mode, you will see a secret token and unseal key on the screen. These two values will be used in the commands to follow. You can load the configuration file and all certificates from “meshcentral-data” into Vault by typing this:
1436
-
1437
-```
1438
-node node_modules/meshcentral --vaultpushconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral
1439
-```
1440
-
1441
-Once all of the files have been written into Vault, you can take a look at the Vault web user interface to see all of the secrets. It will be in “secret/meshcentral”:
1442
-
1443
-
1444
-
1445
-The `config.json` and `terms.txt` files and files in `meshcentral-data` that end with `.key`, `.crt`, `.jpg` and `.png` will be stored in Vault. You can then run MeshCentral like this:
1446
-
1447
-```bash
1448
-node node_modules/meshcentral --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral
1449
-```
1450
-
1451
-MeshCentral will first read all of the files from Vault and get started. An alternative to this is to create a very small `config.json` file in “meshcentral-data” that contains only the Vault configuration like this:
1452
-
1453
-```json
1454
-{
1455
- "settings": {
1456
- "vault": {
1457
- "endpoint": "http://127.0.0.1:8200",
1458
- "token": "s.cO4Q…",
1459
- "unsealkey": "7g4wFC…",
1460
- "name": "meshcentral"
1461
- }
1462
- }
1463
-}
1464
-```
1465
-
1466
-Once the config.json file is setup, you can just run MeshCentral without any arguments.
1467
-
1468
-```bash
1469
-node node_modules/meshcentral
1470
-```
1471
-
1472
-Lastly you can all pull all of the files out of Vault using this command line:
1473
-
1474
-```bash
1475
-node node_modules/meshcentral --vaultpullconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral
1476
-```
1477
-
1478
-And delete the Vault secrets using this:
1479
-
1480
-```bash
1481
-node node_modules/meshcentral --vaultdeleteconfigfiles --vault http://127.0.0.1:8200 --token s.cO4… --unsealkey 7g4w… --name meshcentral
1482
-```
1483
-
1484
-## 🔏 Database Record Encryption
1485
-
1486
-Regardless if using the default NeDB database or MongoDB, MeshCentral can optionally encrypt sensitive data that is stored in the database. When enabled, this encryption is applied to user credentials and Intel AMT credentials.
1487
-
1488
-
1489
-
1490
-The additional encryption does the affect database operations and can be used in addition to additional database security. In the following image, we see on the left a normal user record including user credential hashes and data required for two-factor authentication. On the right side, these values are encrypted using AES-256-GCM in the `_CRYPT` field.
1491
-
1492
-
1493
-
1494
-Only some data fields are encrypted and the “_CRYPT” entry will only be present when one or more fields are present that need to be secured. To enable this feature, add the “DbRecordsEncryptKey” with a password string to the “settings” section of the config.json like this:
1495
-
1496
-```json
1497
-{
1498
- "settings": {
1499
- "Port": 4430,
1500
- "RedirPort": 800,
1501
- "DbRecordsEncryptKey": "MyReallySecretPassword"
1502
- }
1503
-}
1504
-```
1505
-
1506
-The provided password will be hashed using SHA384 and the result with be used as an encryption key. When DbRecordsEncryptKey is set, any new or updated records that are written will be encrypted when needed. Existing encrypted records will be read and decrypted as needed. You can force the all entries to be re-written by running:
1507
-
1508
-```bash
1509
-node node_modules/meshcentral --recordencryptionrecode
1510
-```
1511
-
1512
-This command will re-write entries in the database that could require added security and force the application of record encryption. You can also specify a key for decryption only like this:
1513
-
1514
-```json
1515
-{
1516
- "settings": {
1517
- "Port": 4430,
1518
- "RedirPort": 800,
1519
- "DbRecordsDecryptKey": "MyReallySecretPassword"
1520
- }
1521
-}
1522
-```
1523
-
1524
-When set, the key will only be used for decryption and any new or updated records in the database will not be written with record encryption. You can then run this command again to force all records to be rewritten without encryption:
1525
-
1526
-```bash
1527
-node node_modules/meshcentral --recordencryptionrecode
1528
-```
1529
-
1530
-It’s really important to keep the encryption key in a safe place along with database backups. If the database is backed up but the record encryption key is lost, it will not be possible to recover the secured data in the database.
1531
-
1532
-!!! note
1533
- Also note that database record encryption can and should be used along with other data protection systems.
1534
-
1535
-## 📊 MongoDB free server monitoring
1536
-
1537
-If running with MongoDB version 4.x, there is a free database monitoring service that is provided. Just run “mongo” and you may see the following:
1538
-
1539
-
1540
-
1541
-Type `db.enableFreemonitoring()` if you want to enable this. You will be given a URL to access the data and can turn it back off at any time. The web page will look something like this:
1542
-
1543
-
1544
-
1545
-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.
1546
-
1547
-## 🔓 MeshCentral Single Sign-On (SSO)
1548
-
1549
-As with any web application deployed in organization, it’s convenient and more secure for users to have a single set of credentials that can be used across many services. In this section we take a look at how to configure MeshCentral so that you can sign-in using credentials from other services. This allows users to completely skip creating a user account on MeshCentral or having to remember usernames and password for one more web site. There are two single sign-on protocols that are supported in MeshCentral, OAuth2 and SAML. We will take a look at an example for each one.
1550
-
1551
-Before you get started, your MeshCentral server must be publicly facing on the internet and have a valid TLS certificate. For example, by setting up Let’s Encrypt. After the web site is working correctly user the steps below.
1552
-
1553
-
1554
-### LDAP
1555
-
1556
-<div class="video-wrapper">
1557
- <iframe width="320" height="180" src="https://www.youtube.com/embed/UQMbNQk85g8" frameborder="0" allowfullscreen></iframe>
1558
-</div>
1559
-
1560
-You can integrate LDAP using [these](https://github.com/Ylianst/MeshCentral/blob/f05eb9a198bed249c2b1a969ce17a41404ef70a6/meshcentral-config-schema.json#L505-L513) configuration options
1561
-
1562
-
1563
-
1564
-### Twitter Authentication
1565
-
1566
-Like many other services, Twitter allows its users to login to other web site using Twitter credentials using OAuth2. Start by creating an account on Twitter and logging in. Then navigate to [Twitter Developer Apps](https://developer.twitter.com/en/apps), this is where you can create new applications that are compatible with Twitter.
1567
-
1568
-Start by creating a new application and fill in the application form. Give your application and name, description, server URL and more.
1569
-
1570
-
1571
-
1572
-Make sure to select “Enable Sign in with Twitter” and set the callback URL to `https://(server.domain.com)/auth-twitter-callback`. This is the URL that Twitter will redirect users to once they are logged in. For example this is what a sample application would look like:
1573
-
1574
-
1575
-
1576
-Once the new application is created, go to the `Keys and tokens` tab. You will need the `API Key` and `API secret key` values. In the MeshCentral `config.json`, place these two values as `clientid` and `clientsecret` of the Twitter section of the `AuthStrategies`.
1577
-
1578
-
1579
-
1580
-Once done, your config.json should look a bit like this:
1581
-
1582
-```json
1583
-{
1584
- "settings": {
1585
- "Cert": "myserver.mydomain.com",
1586
- "Port": 443,
1587
- "RedirPort": 80
1588
- },
1589
- "domains": {
1590
- "": {
1591
- "Title": "MyServer",
1592
- "Title2": "Servername",
1593
- "NewAccounts": true,
1594
- "authStrategies": {
1595
- "twitter": {
1596
- "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
1597
- "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
1598
- }
1599
- }
1600
- }
1601
- }
1602
-}
1603
-```
1604
-
1605
-!!! note
1606
- Note that if you do not allow new accounts, any new users that use Twitter credentials will not be able to login to MeshCentral. One trick is to allow new account, login and change this setting again. Once the config.json is correct, restart the server and you should see the Twitter icon on the login screen. When restarting the MeshCentral server, new modules will need to be installed to support this new feature. Depending on how your server is setup, you may need to restart the server manually to allow the new modules to be installed.
1607
-
1608
-
1609
-
1610
-### Google, GitHub, Reddit Authentication
1611
-
1612
-The exact same process as shown in the previous section can be repeated for Google, GitHub and Reddit. In each case, you need to go to each respective credential provider and get a `ClientID` and `ClientSecret` for each service. You also need to register the correct callback URL for each service.
1613
-
1614
-Take a look at the `config.json` below and note the callback URL that will need to be registered for each service provider.
1615
-
1616
-```json
1617
-{
1618
- "settings": {
1619
- "Cert": "myserver.mydomain.com",
1620
- "Port": 443,
1621
- "RedirPort": 80
1622
- },
1623
- "domains": {
1624
- "": {
1625
- "Title": "MyServer",
1626
- "Title2": "Servername",
1627
- "NewAccounts": true,
1628
- "authStrategies": {
1629
- "twitter": {
1630
- "__callbackurl": "https://server/auth-twitter-callback",
1631
- "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
1632
- "clientsecret": " xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
1633
- },
1634
- "google": {
1635
- "__callbackurl": "https://server/auth-google-callback",
1636
- "clientid": "xxxxxxxxxxxxxxxxxxxxxxxxxx.apps.googleusercontent.com",
1637
- "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxx"
1638
- },
1639
- "github": {
1640
- "__callbackurl": "https://server/auth-github-callback",
1641
- "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
1642
- "clientsecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
1643
- },
1644
- "reddit": {
1645
- "__callbackurl": "https://server/auth-reddit-callback",
1646
- "clientid": "xxxxxxxxxxxxxxxxxxxxxxx",
1647
- "clientsecret": " xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx "
1648
- }
1649
- }
1650
- }
1651
- }
1652
-}
1653
-```
1654
-
1655
-It’s possible to enable all four of these service providers at the same time to offer the most flexibility for users. Note that when using an OAuth service provider, MeshCentral does not offer two-factor authentication since it will be handled by the provider depending on user configuration.
1656
-
1657
-### Microsoft Azure Active Directory
1658
-
1659
-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.
1660
-
1661
-
1662
-
1663
-
1664
-
1665
-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.
1666
-
1667
-
1668
-
1669
-Next, we need to create a secret that will be shared between Azure and MeshCentral. Go to the `Certificates & secrets` section and click `New client secret`. You then enter a name and for our example, we will opt to never make it expire.
1670
-
1671
-
1672
-
1673
-
1674
-
1675
-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:
1676
-
1677
-```json
1678
-{
1679
- "settings": {
1680
- "Cert": "myserver.mydomain.com",
1681
- "Port": 443,
1682
- "RedirPort": 80
1683
- },
1684
- "domains": {
1685
- "": {
1686
- "Title": "MyServer",
1687
- "Title2": "Servername",
1688
- "NewAccounts": false,
1689
- "authStrategies": {
1690
- "azure": {
1691
- "newAccounts": true,
1692
- "clientid": "be4aadd3-77b8-4e55-af8a-4b8e2d994cb5",
1693
- "clientsecret": "NP0XXXXXXXXXXXXXXXXXXX",
1694
- "tenantid": "18910a48-e492-4c49-8043-3449f7964bd6"
1695
- }
1696
- }
1697
- }
1698
- }
1699
-}
1700
-```
1701
-
1702
-The `Application ID` value is placed as `Client ID` in the configuration file. You can also see that in the example above, we have `NewAccounts` set to false in the default MeshCentral domain, but set to true in the Azure section. This indicates that new accounts are not allowed in this domain except if it’s a new user that is authenticating through 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.
1703
-
1704
-
1705
-
1706
-### JumpCloud Authentication using SAML
1707
-
1708
-While using OAuth may be interesting, it’s more likely that MeshCentral servers used in an enterprise environment will want to use SAML (Security Assertion Markup Language). This is a widely deployed sign-on protocol used in enterprises so that, for example, employees can login to many different web sites using a single set of company credentials. MeshCentral can be one of many web sites that some users may want to log into.
1709
-
1710
-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.
1711
-
1712
-Before getting started with this section, make sure your server is on the Internet and publicly available and that it has a valid TLS certificate. You can use Let’s Encrypt to get a valid TLS certificate. Then, start by going to [JumpCloud](https://jumpcloud.com) and creating an administrator account. Once setup, go to `Applications` and click on the big plug sign to create a new application.
1713
-
1714
-
1715
-
1716
-You will need to create a custom SAML application by clicking the `Custom SAML App`.
1717
-
1718
-
1719
-
1720
-Then, you can fill in the form with an application name and logo.
1721
-
1722
-- For the IdP Entity ID, put `jumpcloud`.
1723
-- For the SP Entity ID put `meshcentral`.
1724
-- For the ACS URL, put the callback URL of your server. In this case it will be `https://(yourservername)/auth-jumpcloud-callback`
1725
-- Lastly in the attributes section, add 3 user attribute mapping.
1726
- - `firstname` to `firstname`
1727
- - `lastname` to `lastname`
1728
- - `email` to `email`
1729
-
1730
-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.
1731
-
1732
-
1733
-
1734
-Once setup, you will need to allow one or more users to use the new application. One way to do this is to just add your new application to the `All Users` group.
1735
-
1736
-
1737
-
1738
-We are now almost done with JumpCloud. The last thing we need to do is download the certificate that JumpCloud will be using to sign the SAML assertions. You can get this certificate by going in the `Applications` tab, click on your new application and select `Download Certificate` as shown here.
1739
-
1740
-
1741
-
1742
-Save the certificate as `jumpcloud-saml.pem` and place it in the `meshcentral-data` folder. You are now ready to configure MeshCentral.
1743
-
1744
-Edit the `config.json` and make it look like this:
1745
-
1746
-```json
1747
-{
1748
- "settings": {
1749
- "Cert": "myserver.mydomain.com",
1750
- "Port": 443,
1751
- "RedirPort": 80
1752
- },
1753
- "domains": {
1754
- "": {
1755
- "Title": "MyServer",
1756
- "Title2": "Servername",
1757
- "NewAccounts": false,
1758
- "authStrategies": {
1759
- "jumpcloud": {
1760
- "__callbackurl": "https://server/auth-jumpcloud-callback",
1761
- "NewAccounts": true,
1762
- "entityid": "meshcentral",
1763
- "idpurl": "https://sso.jumpcloud.com/saml2/saml2",
1764
- "cert": "jumpcloud-saml.pem"
1765
- }
1766
- }
1767
- }
1768
- }
1769
-}
1770
-```
1771
-
1772
-Take note that the `entityid`, `idpurl` and `cert` are values taken from JumpCloud. The callback URL should be configured in JumpCloud as we have done in previous steps. You can see that in the example above, we have `NewAccounts` set to false in the default MeshCentral domain, but set to true in the JumpCloud section. This indicates that new accounts are not allowed in this domain except if it’s a new user that is authenticating through JumpCloud.
1773
-
1774
-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.
1775
-
1776
-
1777
-
1778
-Users can sign-in using the regular username and password or using JumpCloud.
1779
-
1780
-### Generic SAML setup
1781
-
1782
-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.
1783
-
1784
-A generic SAML setup will look like this:
1785
-
1786
-```json
1787
-{
1788
- "settings": {
1789
- "Cert": "myserver.mydomain.com",
1790
- "Port": 443,
1791
- "RedirPort": 80
1792
- },
1793
- "domains": {
1794
- "": {
1795
- "Title": "MyServer",
1796
- "Title2": "Servername",
1797
- "NewAccounts": 1,
1798
- "authStrategies": {
1799
- "saml": {
1800
- "__callbackurl": "https://server/auth-saml-callback",
1801
- "entityid": "meshcentral",
1802
- "idpurl": "https://server/saml2",
1803
- "cert": "saml.pem"
1804
- }
1805
- }
1806
- }
1807
- }
1808
-}
1809
-```
1810
-
1811
-The callback URL will be of the form `https://(servername)/auth-saml-callback`. You should set the entityid, idpurl as given by the identity provider. Lastly, place the identity provider certificate file in the `meshcentral-data` folder and indicate the name of the file in `cert`.
1812
-
1813
-Once setup, restart the server and you should see a Single Sign-on button on the login screen.
1814
-
1815
-
1816
-
1817
-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.
1818
-
1819
-!!! note
1820
- MeshCentral only supports "POST". [For example Authentik's](https://github.com/Ylianst/MeshCentral/issues/4725) default setting is to use `Redirect` as a `Service Provider Binding`.
1821
-
1822
-### Generic OpenID Connect Setup
1823
-
1824
-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.
1825
-
1826
-``` json
1827
-{
1828
- "settings": {
1829
- "cert": "mesh.your.domain",
1830
- "port": 443,
1831
- "sqlite3": true
1832
- },
1833
- "domains": {
1834
- "": {
1835
- "title": "Mesh",
1836
- "title2": ".Your.Domain",
1837
- "authStrategies": {
1838
- "oidc": {
1839
- "issuer": "https://sso.your.domain",
1840
- "clientid": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
1841
- "clientsecret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
1842
- "newAccounts": true
1843
- }
1844
- }
1845
- }
1846
- }
1847
-}
1848
-```
1849
-
1850
-As you can see, this is roughly the same as all the other OAuth2 based authentication strategies. These are the basics you need to get started using OpenID Connect because it's still authenticating with OAuth2. If you plan to take advantage of some of the more advanced features provided by this strategy you should consider reading the [additional strategy documentation](./openidConnectStrategy.md).
1851
-
1852
-!!! note
1853
- MeshCentral will use `https://mesh.your.domain/auth-oidc-callback` as the default redirect uri.
1854
-
1855
-## ✨ Improvements to MeshCentral
1856
-
1857
-In 2007, the first version of MeshCentral was built. We will refer to it as “MeshCentral1”. When MeshCentral1 was designed, HTML5 did not exist and web sockets where not implemented in any of the major browsers. Many design decisions were made at the time that are no longer optimal today. With the advent of the latest MeshCentral, MeshCentral1 is no longer supported and MeshCentral v2 has been significantly redesigned and mostly re-written based of previous version. Here is a list of improvements made in MeshCentral when compared with MeshCentral1 :
1858
-
1859
-- **Quick Installation –**
1860
- > By having MeshCentral published on NPM (www.npmjs.com) it’s now easy to download and install MeshCentral on both Linux and Windows*. On Linux* you can use NPM directly (`npm install meshcentral`) and on Windows you can use the `.MSI installer`.
1861
-- **Cross-Platform Support –**
1862
- > Contrary to MeshCentral1 that only runs on Windows*, MeshCentral can run on any environment that supports NodeJS. This includes Windows*, Linux* and *OSX*. Because MeshCentral runs on Linux, it often lowers hosting costs and makes it possible to run MeshCentral in a Docker* container environment.
1863
-- **Runs with Little Compute Resources –**
1864
- > Typical MeshCentral1 installation requires a large disk space foot print (approx* 30G of disk space) and is compute intensive even for small deployments. MeshCentral requires little resources to host (70MB) and able to deliver reasonable performance on a 900Mhz CPU with 1GB RAM.
1865
-- **Multi-Tenancy and Load Balancing Support –**
1866
- > MeshCentral can handle hosting many server instances at once. Each instance or `domain` has it’s own administrators, users and computers to manage. The server can handle each instance using a url path `server.com/customer1` or a DNS name `customer1.server.com`. Many customers can be handled by having all the DNS names point to the same server IP address. MeshCentral will take care of serving the right TLS certificate for each connection.
1867
-- **Single Executable –**
1868
- > MeshCentral is a single-module or single executable server. All of the components of MeshCentral1 including IIS, Swarm, AJAX, Social, Manageability Servers are all build into one single executable. This makes it super easy to setup and run, it also minimizes problems and overhead caused by having many components communicate to each other. When the server is updated, all of the components are updated at once and effective.
1869
-- **Web Application Design –**
1870
- > MeshCentral1 has 100’s of web pages and often times a click on a web page causes the browser to load a different web page and this creates more load on the server. With MeshCentral there are only two main web pages: The login page and the main web application. This design is much more responsive since the server now delegates most of the UI workload to the client’s web browser.
1871
-- **Real-Time User Interface –**
1872
- > In MeshCentral, the user never has to hit the `refresh` button to update the web page. The web interface is completely real-time and updates as things change. MeshCentral uses websockets to connect to the server and get real-time events.
1873
-- **Single Programming Language –**
1874
- > MeshCentral1 used JavaScript on the browser, C# on the server and C for the agent. Use of 3 different programming languages means that developers wanting to implement a new use-case needs to have sufficient skills to change between these 3 languages during the coding session. Makes the code significantly more difficult to understand and maintain.
1875
-- **Support for LAN only Mode –**
1876
- > MeshCentral is capable of being setup as “LAN only” mode. In fact, this is the default mode when no static name or IP address is provided. In this mode, MeshAgents perform a multicast search on the network for the server making a static DNS/IP unnecessary.
1877
-- **Support for TLS Offloaders –**
1878
- > TLS offloaders are now fully supported. This means that MeshCentral can handle way more network connections and traffic significantly.
1879
-- **Support for CIRA User/Pass Login –**
1880
- > MeshCentral now supports both Intel AMT CIRA user/pass login and certificate login. Compared to MeshCentral1 that only supported certificate login, user/pass login is easier to setup and it can also be used for TLS offloaders and CIRA authentication.
1881
-- **No Live State Stored in the Database –**
1882
- > One if the big problems with MeshCentral1 is that a lot of the live states (Agent, User and AMT connections and disconnections) needed to be stored in the database. This caused a few problems, first the extra load on the database that was un-necessary, but also that servers did not have real-time state information about other servers (they had to query the database). This resulted in more load on the database and scaling issues. In MeshCentral, all live states are kept in the RAM which boosts performance significantly.
1883
-- **Agentless Intel AMT Support –**
1884
- > With MeshCentral1, administrators have to install the MeshAgent software on all computers, even if it was only for used for Intel AMT. MeshCentral supports a new agent-less mesh type that allows administrators to just setup the server strictly for Intel AMT only.
1885
-- **Latest Security & Crypto algorithms –**
1886
- > MeshCentral uses all the latest cryptographic algorithm, notably SHA384 and RSA3072 making it more resistant to future quantum computer attacks. This would be very difficult to retrofit into MeshCentralv1 since it would require change of database schema and 1000’s of line of code thus making the server incompatible with the current version version, making migration difficult.
1887
-- **Support for Email Verification and Password Recovery –**
1888
- > MeshCentral can be configured with an SMTP server to send out e-mail confirmation messages and password recovery message. This is an important feature that was missing in MeshCentral1.
1889
-- **MeshInterceptor Support –**
1890
- > MeshCentral can insert HTTP and Intel AMT redirection credential into a live data stream. This is useful to allow an administrator to securely pass Intel AMT password and control over an Intel AMT computer via web browser without the additional administrator login UI.
1891
-
1892
-It’s possible to perform migration to MeshCentral from MeshCentral1 server using a migration package. The MeshCentral Migration Tool will convert your existing user database into a format that can be imported into MeshCentral.
1893
-
1894
-
1895
-
1896
-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.
1897
-
1898
-## 💡 Additional Resources
1899
-
1900
-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](https://www.meshcommander.com/meshcentral2/tutorials)
1901
-. The tutorial includes videos on how to perform server installation using both the Windows MSI installer and NPM methods.
1902
-
1903
-
1904
-
1905
-## 🏁 Conclusion
1906
-
1907
-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.
1908
-
1909
-## License
1910
-
1911
-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>.
1912
-
1913
-## Annex 1: Sample Configuration File
1914
-
1915
-In this annex, we present a complete sample config.json file. You would put this file in the “meshcentral-data” folder that is created when MeshCentral is first run. The config.json is completely optional and the server will run with default values with it. All key names in this file are case insensitive.
1916
-
1917
-```json
1918
-{
1919
- "settings": {
1920
- "MongoDb": "mongodb://127.0.0.1:27017/meshcentral",
1921
- "MongoDbCol": "meshcentral",
1922
- "Port": 4430,
1923
- "AliasPort": 443,
1924
- "RedirPort": 800,
1925
- "TlsOffload": "127.0.0.1",
1926
- "MpsPort": 44330,
1927
- "MpsAliasPort": 4433,
1928
- "MpsTlsOffload": true,
1929
- "SessionTime": 30,
1930
- "SessionKey": "MyReallySecretPassword",
1931
- "AllowLoginToken": true,
1932
- "AllowFraming": true,
1933
- "WebRTC": true,
1934
- "ClickOnce": true
1935
- },
1936
- "domains": {
1937
- "": {
1938
- "Title": "MyServer",
1939
- "Title2": "Servername",
1940
- "TitlePicture": "title-sample.png",
1941
- "UserQuota": 1048576,
1942
- "MeshQuota": 248576,
1943
- "NewAccounts": true,
1944
- "Footer": "<a href='https://twitter.com/mytwitter'>Twitter</a>",
1945
- "PasswordRequirements": { "min": 8, "max": 128, "upper": 1, "lower": 1, "numeric": 1, "nonalpha": 1 }
1946
- },
1947
- "customer1": {
1948
- "Dns": "customer1.myserver.com",
1949
- "Title": "Customer1",
1950
- "Title2": "TestServer",
1951
- "NewAccounts": 1,
1952
- "Auth": "sspi",
1953
- "Footer": "Test"
1954
- },
1955
- "info": {
1956
- "share": "C:\\ExtraWebSite"
1957
- }
1958
- },
1959
- "letsencrypt": {
1960
- "email": "myemail@myserver.com ",
1961
- "names": "myserver.com,customer1.myserver.com",
1962
- "rsaKeySize": 3072,
1963
- "production": false
1964
- },
1965
- "peers": {
1966
- "serverId": "server1",
1967
- "servers": {
1968
- "server1": { "url": "wss://192.168.2.133:443/" },
1969
- "server2": { "url": "wss://192.168.1.106:443/" }
1970
- }
1971
- },
1972
- "smtp": {
1973
- "host": "smtp.myserver.com",
1974
- "port": 25,
1975
- "from": "myemail@myserver.com",
1976
- "tls": false
1977
- }
1978
-}
1979
-```
1980
-
1981
-All these values are examples only, this config.json should just be used as an example and none of the values here are real.
1982
-
1983
-## Annex 2: Tips & Tricks
1984
-
1985
-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>
1986
-
1987
-### Remote Terminal
1988
-
1989
-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:
1990
-
1991
-```bash
1992
-su -s /bin/bash myOtherUser
1993
-```
1994
-
1995
-However, because bash is not run in interactive mode, the command line prompt may be empty and history keys (up and down), tab and backspace will not work right. The correct command is:
1996
-
1997
-```bash
1998
-su -c '/bin/bash -i' myOtherUser
1999
-```
2000
-
2001
-This will run bash in interactive mode and work correctly.
2002
-
2003
-#### SSH and SFTP integration to the Terminal
2004
-
2005
-MeshCentral has built-in web-based integration of SSH in the "Terminal" tab and SFTP in the "Files" tab.
2006
-
2007
-<div class="video-wrapper">
2008
- <iframe src="https://www.youtube.com/embed/7qAbl2OuZEU" frameborder="0" allowfullscreen></iframe>
2009
-</div>
2010
-
2011
-## PDF and ODT handout(s).
2012
-
2013
-[MeshCentral Guide](https://meshcentral.com/docs/MeshCentral2UserGuide.pdf)
2014
-
2015
-MeshCmd Guide [as .pdf](https://meshcentral.com/docs/MeshCmdUserGuide.pdf) [as .odt](../documents/MeshCentral%20User's%20Guide%20v0.2.9.odt)
docs/docs/meshcentral/openidConnectStrategy.md
deleted
-730
@@ -1,730 +0,0 @@
1
-# Using the OpenID Connect Strategy on MeshCentral
2
-
3
-## Overview
4
-
5
-### Introduction
6
-
7
-There is a lot of information to go over, but first, why OpenID Connect?
8
-
9
-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.
10
-
11
-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.
12
-
13
-> 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.
14
-
15
-### Chart of Frequently Used Terms and Acronyms
16
-| Term | AKA | Descriptions |
17
-| --- | --- | --- |
18
-| OAuth 2.0 | OAuth2 | OAuth 2.0 is the industry-standard protocol for user *authorization*. |
19
-| OpenID Connect | OIDC | Identity layer built on top of OAuth2 for user *authentication*. |
20
-| Identity Provider | IdP | The *service used* to provide authentication and authorization. |
21
-| Preset Configs | Presets | Set of *pre-configured values* to allow some specific IdPs to connect correctly. |
22
-| OAuth2 Scope | Scope | A flag *requesting access* to a specific resource or endpoint |
23
-| OIDC Claim | Claim | A *returned property* in the user info provided by your IdP |
24
-| User Authentication | AuthN | Checks if you *are who you say you are*. Example: Username and password authentication |
25
-| User Authorization | AuthZ | Check if you have the *permissions* required to access a specific resource or endpoint |
26
-
27
-### OpenID Connect Technology Overview
28
-
29
-OpenID Connect is a simple identity layer built on top of the OAuth2 protocol. It allows Clients to verify the identity of the End-User based on the authentication performed by an “Authorization Server”, as well as to obtain basic profile information about the End-User in an interoperable and REST-like manner.
30
-
31
-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.
32
-
33
-That description was straight from [OpenID Connect Documentation](https://openid.net/connect/), 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.
34
-
35
-### Annotations
36
-
37
-#### Own IDP, CA and Docker
38
-
39
-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.
40
-
41
-The following errors can be found in the log file:
42
-> OIDC: Discovery failed.
43
-
44
-> UNABLE_TO_GET_ISSUER_CERT_LOCALLY
45
-
46
-To solve this problem, the certificate chain in PEM format must be placed in the data directory and the following entry must be added to the docker-compose.yml file in the “environment” section:
47
-```
48
- environment:
49
- - NODE_EXTRA_CA_CERTS=/opt/meshcentral/meshcentral-data/chain.pem
50
-```
51
-
52
-## Basic Config
53
-
54
-### *Introduction*
55
-
56
-Generally, if you are using an IdP that supports OIDC, you can use a very basic configuration to get started, and if needed, add more specific or advanced configurations later. Here is what your config file will look like with a basic, generic, configuration.
57
-
58
-### *Basic Config File Example*
59
-
60
-``` json
61
-{
62
- "settings": {
63
- "cert": "mesh.your.domain",
64
- "port": 443,
65
- "sqlite3": true
66
- },
67
- "domains": {
68
- "": {
69
- "title": "MeshCentral",
70
- "title2": "Your sub-title",
71
- "authStrategies": {
72
- "oidc": {
73
- "issuer": "https://sso.your.domain",
74
- "clientid": "2d5685c5-0f32-4c1f-9f09-c60e0dbc948a",
75
- "clientsecret": "7PiGSLSLL4e7NGi67KM229tfK7Z7TqzQ",
76
- "newAccounts": true
77
- }
78
- }
79
- }
80
- }
81
-}
82
-```
83
-
84
-As you can see, this is roughly the same as all the other OAuth2 based authentication strategies. These are the basics you need to get started, however, if you plan to take advantage of some of the more advanced features provided by this strategy, you'll need to keep reading.
85
-
86
-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.
87
-
88
-> WARNING: The redirect endpoint must EXACTLY match the value provided to your IdP or your will deny the connection.
89
-
90
-> 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.
91
-
92
-## Advanced Options
93
-
94
-### Overview
95
-
96
-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](https://github.com/panva/node-openid-client) 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](https://github.com/Ylianst/MeshCentral/blob/master/meshcentral-config-schema.json), and if you have a complicated config maybe check out the [openid-client readme](https://github.com/panva/node-openid-client/blob/main/docs/README.md). Theres a list of resources at the end if you want more information on any specific topics. In the meantime, let’s take a look at an example of what your config file could look with a slightly more complicated configuration, including multiple manually defined endpoints.
97
-
98
-#### *Advanced Config File Example*
99
-
100
-``` json
101
-{
102
- "settings": {
103
- "cert": "mesh.your.domain",
104
- "port": 443,
105
- "redirPort": 80,
106
- "AgentPong": 300,
107
- "TLSOffload": "192.168.1.50",
108
- "SelfUpdate": false,
109
- "AllowFraming": false,
110
- "sqlite3": true,
111
- "WebRTC": true
112
- },
113
- "domains": {
114
- "": {
115
- "title": "Mesh",
116
- "title2": ".Your.Domain",
117
- "orphanAgentUser": "~oidc:e48f8ef3-a9cb-4c84-b6d1-fb7d294e963c",
118
- "authStrategies": {
119
- "oidc": {
120
- "issuer": {
121
- "issuer": "https://sso.your.domain",
122
- "authorization_endpoint": "https://auth.your.domain/auth-endpoint",
123
- "token_endpoint": "https://tokens.sso.your.domain/token-endpoint",
124
- "end_session_endpoint": "https://sso.your.domain/logout",
125
- "jwks_uri": "https://sso.your.domain/jwks-uri"
126
- },
127
- "client": {
128
- "client_id": "110d5612-0822-4449-a057-8a0dbe26eca5",
129
- "client_secret": "4TqST46K53o3Z2Q88p39YwR6YwJb7Cka",
130
- "redirect_uri": "https://mesh.your.domain/auth-oidc-callback",
131
- "post_logout_redirect_uri": "https://mesh.your.domain/login",
132
- "token_endpoint_auth_method": "client_secret_post",
133
- "response_types": "code"
134
- },
135
- "custom": {
136
- "scope": [ "openid", "profile", "read.EmailAlias", "read.UserProfile" ],
137
- "preset": null
138
- },
139
- "groups": {
140
- "recursive": true,
141
- "required": ["Group1", "Group2"],
142
- "siteadmin": ["GroupA", "GroupB"],
143
- "revokeAdmin": true,
144
- "sync": {
145
- "filter": ["Group1", "GroupB", "OtherGroup"]
146
- },
147
- "claim": "GroupClaim",
148
- "scope": "read.GroupMemberships"
149
- },
150
- "logouturl": "https://sso.your.domain/logout?r=https://mesh.your.domain/login",
151
- "newAccounts": true
152
- },
153
- {...}
154
- }
155
- }
156
- }
157
-}
158
-```
159
-
160
-### "Issuer" Options
161
-
162
-#### *Introduction*
163
-
164
-In the advanced example config above, did you notice that the issuer property has changed from a *string* to an *object* compared to the basic example? This not only allows for much a much smaller config footprint when advanced issuer options are not required, it successfully fools you in to a false sense of confidence early on in this document. If you are manually configuring the issuer endpoints, keep in mind that MeshCentral will still attempt to discover **ALL** issuer information. Obviously if you manually configure an endpoint, it will be used even if the discovered information is different from your config.
165
-
166
-> NOTE: If you are using a preset, you dont need to define an issuer. If you do, the predefined information will be ignored.
167
-
168
-#### *Common Config Chart*
169
-
170
-| Name | Description | Default | Example | Required |
171
-| --- | --- | --- | --- | --- |
172
-| `issuer` | The primary URI that represents your Identity Providers authentication endpoints. | N/A | `"issuer": "https://sso.your.domain"`<br/>`"issuer": { "issuer": "https://sso.your.domain" }` | Unless using preset. |
173
-
174
-#### *Advanced Config Example*
175
-
176
-``` json
177
-"issuer": {
178
- "issuer": "https://sso.your.domain",
179
- "authorization_endpoint": "https://auth.your.domain/auth-endpoint",
180
- "token_endpoint": "https://tokens.sso.your.domain/token-endpoint",
181
- "end_session_endpoint": "https://sso.your.domain/logout",
182
- "jwks_uri": "https://sso.your.domain/jwks-uri"
183
-},
184
-```
185
-
186
-#### *Required and Commonly Used Configs*
187
-
188
-The `issuer` property in the `issuer` object is the only one required, and its only required if you aren't using a preset. Besides the issuer, these are mostly options related to the endpoints and their configuration. The schema below looks intimidating but it comes down to being able to support any IdP. Setting the issuer, and end_session_endpoint are the two main ones you want to setup.
189
-
190
-#### *Schema*
191
-
192
-``` json
193
-"issuer": {
194
- "type": ["string","object"],
195
- "format": "uri",
196
- "description": "Issuer options. Requires issuer URI (issuer.issuer) to discover missing information unless using preset",
197
- "properties": {
198
- "issuer": { "type": "string", "format": "uri", "description": "URI of the issuer." },
199
- "authorization_endpoint": { "type": "string", "format": "uri" },
200
- "token_endpoint": { "type": "string", "format": "uri" },
201
- "jwks_uri": { "type": "string", "format": "uri" },
202
- "userinfo_endpoint": { "type": "string", "format": "uri" },
203
- "revocation_endpoint": { "type": "string", "format": "uri" },
204
- "introspection_endpoint": { "type": "string", "format": "uri" },
205
- "end_session_endpoint": {
206
- "type": "string",
207
- "format": "uri",
208
- "description": "URI to direct users to when logging out of MeshCentral.",
209
- "default": "this.issuer/logout"
210
- },
211
- "registration_endpoint": { "type": "string", "format": "uri" },
212
- "token_endpoint_auth_methods_supported": { "type": "string" },
213
- "token_endpoint_auth_signing_alg_values_supported": { "type": "string" },
214
- "introspection_endpoint_auth_methods_supported": { "type": "string" },
215
- "introspection_endpoint_auth_signing_alg_values_supported": { "type": "string" },
216
- "revocation_endpoint_auth_methods_supported": { "type": "string" },
217
- "revocation_endpoint_auth_signing_alg_values_supported": { "type": "string" },
218
- "request_object_signing_alg_values_supported": { "type": "string" },
219
- "mtls_endpoint_aliases": {
220
- "type":"object",
221
- "properties": {
222
- "token_endpoint": { "type": "string", "format": "uri" },
223
- "userinfo_endpoint": { "type": "string", "format": "uri" },
224
- "revocation_endpoint": { "type": "string", "format": "uri" },
225
- "introspection_endpoint": { "type": "string", "format": "uri" }
226
- }
227
- }
228
- },
229
- "additionalProperties": false
230
-},
231
-```
232
-
233
-### "Client" Options
234
-
235
-#### *Introduction*
236
-
237
-There are just about as many option as possible here since openid-client also provides a Client class, because of this you are able to manually configure the client how ever you need. This includes setting your redirect URI to any available path, for example, if I was using the "google" preset and wanted to have Google redirect me back to "https://mesh.your.domain/oauth2/oidc/redirect/givemebackgooglemusicyoujerks", MeshCentral will now fully support you in that. One of the other options is the post logout redirect URI, and it is exactly what it sounds like. After MeshCentral logs out a user using the IdPs end session endpoint, it send the post logout redirect URI to your IdP to forward the user back to MeshCentral or to an valid URI such as a homepage.
238
-
239
-> NOTE: The client object is required, however an exception would be with using old configs, which will be discussed later.
240
-
241
-#### *Common Configs*
242
-
243
-| Name | Description | Default | Example | Required |
244
-| --- | --- | --- | --- | --- |
245
-| `client_id` | The client ID provided by your Identity Provider (IdP) | N/A | `bdd6aa4b-d2a2-4ceb-96d3-b3e23cd17678` | `true` |
246
-| `client_secret` | The client secret provided by your Identity Provider (IdP) | N/A | `vUg82LJ322rp2bvdzuVRh3dPn3oVo29m` | `true` |
247
-| `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` |
248
-| `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` |
249
-
250
-#### *Advanced Config Example*
251
-
252
-``` json
253
-"client": {
254
- "client_id": "00b3875c-8d82-4238-a8ef-25303fa7f9f2",
255
- "client_secret": "7PP453H577xbFDCqG8nYEJg8M3u8GT8F",
256
- "redirect_uri": "https://mesh.your.domain/auth-oidc-callback",
257
- "post_logout_redirect_uri": "https://mesh.your.domain/login",
258
- "token_endpoint_auth_method": "client_secret_post",
259
- "response_types": "code"
260
-},
261
-```
262
-
263
-#### *Required and Commonly Used Configs*
264
-
265
-There are many available options you can configure but most of them go unused. Although there are a few *commonly used* properties. The first two properties, `client_id` and `client_secret` are required. The next one `redirect_uri` is used to setup a custom URI for the redirect back to MeshCentral after being authenicated by your IdP. The `post_logout_redirect_uri` property is used to tell your IdP where to send you after being logged out. These work in conjunction with the issuers `end_session_url` to automatically fill in any blanks in the config.
266
-
267
-#### *Schema*
268
-``` json
269
-"client": {
270
- "type": "object",
271
- "description": "OIDC Client Options",
272
- "properties": {
273
- "client_id": {
274
- "type": "string",
275
- "description": "REQUIRED: The client ID provided by your Identity Provider (IdP)"
276
- },
277
- "client_secret": {
278
- "type": "string",
279
- "description": "REQUIRED: The client secret provided by your Identity Provider (IdP)"
280
- },
281
- "redirect_uri": {
282
- "type": "string",
283
- "format": "uri",
284
- "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)"
285
- },
286
- "post_logout_redirect_uri": {
287
- "type": [
288
- "string",
289
- "boolean"
290
- ],
291
- "format": "uri",
292
- "description": "URI for your IdP to send you after logging out of IdP via MeshCentral OR set to false to not send a post logout redirect_uri"
293
- "default": "https:[currentHost][currentPath]/login"
294
- },
295
- "id_token_signed_response_alg": { "type": "string", "default": "RS256" },
296
- "id_token_encrypted_response_alg": { "type": "string" },
297
- "id_token_encrypted_response_enc": { "type": "string" },
298
- "userinfo_signed_response_alg": { "type": "string" },
299
- "userinfo_encrypted_response_alg": { "type": "string" },
300
- "userinfo_encrypted_response_enc": { "type": "string" },
301
- "response_types": { "type": ["string", "array"], "default": ["code"] },
302
- "default_max_age": { "type": "number" },
303
- "require_auth_time": { "type": "boolean", "default": false },
304
- "request_object_signing_alg": { "type": "string" },
305
- "request_object_encryption_alg": { "type": "string" },
306
- "request_object_encryption_enc": { "type": "string" },
307
- "token_endpoint_auth_method": {
308
- "type": "string",
309
- "default": "client_secret_basic",
310
- "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
311
- },
312
- "introspection_endpoint_auth_method": {
313
- "type": "string",
314
- "default": "client_secret_basic",
315
- "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
316
- },
317
- "revocation_endpoint_auth_method": {
318
- "type": "string",
319
- "default": "client_secret_basic",
320
- "enum": [ "none", "client_secret_basic", "client_secret_post", "client_secret_jwt", "private_key_jwt" ]
321
- },
322
- "token_endpoint_auth_signing_alg": { "type": "string" },
323
- "introspection_endpoint_auth_signing_alg": { "type": "string" },
324
- "revocation_endpoint_auth_signing_alg": { "type": "string" },
325
- "tls_client_certificate_bound_access_tokens": { "type": "boolean" }
326
- },
327
- "required": [ "client_id", "client_secret" ],
328
- "additionalProperties": false
329
-},
330
-```
331
-
332
-### "Custom" Options
333
-
334
-#### *Introduction*
335
-
336
-These are all the options that dont fit with the issuer or client, including the presets. The presets define more than just the issuer URL used in discovery, they also define API endpoints, and specific ways to assemble your data. You are able to manually override most of the effects of the preset, but not all. You are able to manually configure the *scope* of the authorization request though, as well as choose which claims to use if your IdP uses something other than the defaults.
337
-
338
-> NOTE: The scope must be a string, an array of strings, or a space separated list of scopes as a single string.
339
-
340
-#### *Common Config Chart*
341
-
342
-| Name | Description | Default | Example | Required |
343
-| -------- | ------------------------------------------------ | --------------------------------------------------------- | ----------------------------------- | -------- |
344
-| `scope` | A list of scopes to request from the issuer. | `"openid profile email"` | `["openid", "profile"]` | `false` |
345
-| `claims` | A group of claims to use instead of the defaults | Defaults to name of property except that `uuid` used `sub` | `"claims": {"uuid": "unique_name"}` | `false` |
346
-| `buttonText` | Custom tooltip for the OIDC login button. Min 1 character. Max 128 characters. | `Sign-in using OpenID Connect` | `"buttonText": "Login to Custom SSO Brand"` | `false` |
347
-
348
-#### *Advanced Config Example*
349
-
350
-``` json
351
-"custom": {
352
- "scope": [ "openid", "profile", "read.EmailAlias", "read.UserProfile" ],
353
- "preset": null,
354
- "claims": {
355
- "name": "nameOfUser",
356
- "email": "publicEmail"
357
- },
358
- "buttonText": "Login to Custom SSO Brand"
359
-},
360
-```
361
-
362
-> NOTE: You can `preset` to null if you want to explicitly disable presets.
363
-
364
-#### *Required and Commonly Used Configs*
365
-
366
-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.
367
-
368
-#### *Schema*
369
-``` json
370
-"custom": {
371
- "type": "object",
372
- "properties": {
373
- "scope": {
374
- "type": ["string", "array"],
375
- "description": "A list of scopes to request from the issuer.",
376
- "default": "openid profile email",
377
- "examples": ["openid", ["openid", "profile"], "openid profile email", "openid profile email groups"]
378
- },
379
- "claims": {
380
- "type": "object",
381
- "properties": {
382
- "email": { "type": "string" },
383
- "name": { "type": "string" },
384
- "uuid": { "type": "string" }
385
- }
386
- },
387
- "preset": { "type": "string", "enum": ["azure", "google"]},
388
- "tenant_id": { "type": "string", "description": "REQUIRED FOR AZURE PRESET: Tenantid for Azure"},
389
- "customer_id": { "type": "string", "description": "REQUIRED FOR GOOGLE PRESET IF USING GROUPS: Customer ID from Google, should start with 'C'."},
390
- "buttonText": { "type": "string", "description": "Custom text for the OIDC login button. Default: 'Sign-in using OpenID Connect'."}
391
- },
392
- "additionalProperties": false
393
-},
394
-```
395
-
396
-#### *Custom Login Button*
397
-
398
-MeshCentral allows customizing the tooltip/label text shown on OpenID Connect login buttons via the `authStrategies.oidc.custom` object. These settings are optional and can be defined per-domain and are part of the `custom` object described above.
399
-
400
-| Preset | Default button text |
401
-| --- | --- |
402
-| Generic (no preset) | `Sign-in using OpenID Connect` |
403
-| Google preset | `Sign-in with Google using OpenID Connect` |
404
-| Azure preset | `Sign-in with Azure using OpenID Connect` |
405
-
406
-Example:
407
-
408
-```json
409
-"authStrategies": {
410
- "oidc": {
411
- "custom": {
412
- "buttonText": "Login to Custom SSO Brand"
413
- }
414
- }
415
-}
416
-```
417
-
418
-These properties only affect the login page UI (button tooltip) and are safe to set for branding or clarity. If using a custom button text, it will not be translated when changing languages.
419
-
420
-#### *Custom Icon*
421
-
422
-The OIDC login button icon can be customized by setting a remote image URL in the domain config under `authStrategies.oidc.custom`. MeshCentral will validate the image at startup and use it for the login button. Example:
423
-
424
-```json
425
-"authStrategies": {
426
- "oidc": {
427
- "custom": {
428
- "buttonIconUrl": "https://cdn.example.com/icons/oidc32.png",
429
- "buttonIconUrl2x": "https://cdn.example.com/icons/oidc64.png",
430
- "buttonText": "Login to Custom SSO Brand"
431
- }
432
- }
433
-}
434
-```
435
-
436
-- **Server-side validation:** remote URLs are validated before use (timeouts, size limits, content-type checks and magic-byte inspection). If validation fails the UI falls back to the built-in local icons.
437
-- **Allowed formats:** PNG, JPEG, WEBP, GIF, ICO, and SVG.
438
-- **2x icon:** if `buttonIconUrl2x` is not set, `buttonIconUrl` is used for both standard and high-DPI displays.
439
-- **Fallback behavior:** if a remote image is not provided or validation fails, MeshCentral uses the default local icons (or any local overrides, see note below).
440
-
441
-!!! note "Alternative: local file replacement"
442
- You can also replace the login icons on disk instead of using a remote URL. Create `meshcentral-web/public/images/login` in the MeshCentral installation root and copy the original icons from `node_modules/meshcentral/public/images/login` into it. Replace the files you want to change while keeping the same filenames and sizes:
443
-
444
- | Icon | Filenames | Size / Notes |
445
- | --- | --- | --- |
446
- | Generic OIDC | `oidc32.png`, `oidc64.png` | 32x32, 64x64 (@2x) |
447
- | Google preset | `google32.png`, `google64.png` | 32x32, 64x64 (@2x) |
448
- | Azure preset | `azure32.png`, `azure64.png` | 32x32, 64x64 (@2x) |
449
-
450
- Restart MeshCentral (or hard-refresh your browser) after replacing files. For full whitelabeling guidance see the Web Branding section: [customization.md](customization.md#customizing-web-icons).
451
-
452
-### "Groups" Options
453
-
454
-#### *Introduction*
455
-
456
-The groups option allows you to use the groups you already have with your IdP in MeshCentral in a few ways. First you can set a group that the authorized user must be in to sign in to MeshCentral. You can also allow users with the right memberships automatic admin privlidges, and there is even an option to revoke privlidges if the user is NOT in the admin group. Besides these filters, you can filter the sync property to mirror only certain groups as MeshCentral User Groups, dynamically created as the user logs in. You can of course simply enable sync and mirror all groups from your IdP as User Groups. Additionally you can define the scope and claim of the groups for a custom setup, again allowing for a wide range of IdPs to be used, even without a preset.
457
-
458
-#### *Common Config Chart*
459
-
460
-| Name | Description | Default | Example | Required |
461
-| --- | --- | --- | --- | --- |
462
-| `sync` | Allows you to mirror user groups from your IdP. | `false` | `"sync": { "filter": ["Group1", "Group2"] }`<br/>`"sync": true` | `false` |
463
-| `required` | Access is only granted to users who are a member<br/>of at least one of the listed required groups. | `undefined` | `"required": ["Group1", "Group2"]` | `false` |
464
-| `siteadmin` | Full site admin priviledges will be granted to users<br/>who are a member of at least one of the listed admin groups | `undefined` | `"siteadmin": ["Group1", "Group2"]` | `false` |
465
-| `revokeAdmin` | If true, admin privileges will be revoked from users<br/>who arent a member of at least one of the listed admin groups. | `true` | `"revokeAdmin": false` | `false` |
466
-
467
-#### *Advanced Config Example*
468
-
469
-``` json
470
-"groups": {
471
- "recursive": true,
472
- "required": ["Group1", "Group2"],
473
- "siteadmin": ["GroupA", "GroupB"],
474
- "revokeAdmin": false,
475
- "sync": {
476
- "filter": ["Group1", "GroupB", "OtherGroup"]
477
- },
478
- "claim": "GroupClaim",
479
- "scope": "read.GroupMemberships"
480
-},
481
-```
482
-
483
-#### *Required and Commonly Used Configs*
484
-
485
-As you can see in the schema below, there aren't any required properties in the groups object, however there are some commonly used ones. The first, and maybe most commonly used one, is the sync property. The sync property mirrors IdP provided groups into MeshCentral as user groups. You can then configure access as required to those groups, and as users log in, they will be added to the now existing groups if they are a member. You also have other options like using a custom *scope* or *claim* to get your IdP communicating with MeshCentral properly, without the use of preset configs. You also can set the required property if you need to limit authorization to users that are a member of at least one of the groups you set. or the siteadmin property to grant admin privilege, with the revokeAdmin property available to allow revoking admin rights also.
486
-
487
-#### *Schema*
488
-
489
-``` json
490
-"groups": {
491
- "type": "object",
492
- "properties": {
493
- "recursive": {
494
- "type": "boolean",
495
- "default": false,
496
- "description": "When true, the group memberships will be scanned recursively."
497
- },
498
- "required": {
499
- "type": [ "string", "array" ],
500
- "description": "Access is only granted to users who are a member of at least one of the listed required groups."
501
- },
502
- "siteadmin": {
503
- "type": [ "string", "array" ],
504
- "description": "Full site admin priviledges will be granted to users who are a member of at least one of the listed admin groups."
505
- },
506
- "revokeAdmin": {
507
- "type": "boolean",
508
- "default": false,
509
- "description": "If true, admin privileges will be revoked from users who are NOT a member of at least one of the listed admin groups."
510
- },
511
- "sync": {
512
- "type": [ "boolean", "object" ],
513
- "default": false,
514
- "description": "If true, all groups found during user login are mirrored into MeshCentral user groups.",
515
- "properties": {
516
- "filter": {
517
- "type": [ "string", "array" ],
518
- "description": "Only groups listed here are mirrored into MeshCentral user groups."
519
- }
520
- }
521
- },
522
- "scope": { "type": "string", "default": "groups", "description": "Custom scope to use." },
523
- "claim": { "type": "string", "default": "groups", "description": "Custom claim to use." }
524
- },
525
- "additionalProperties": false
526
-}
527
-```
528
-
529
-## Preset OpenID Connect Configurations
530
-
531
-### Overview
532
-
533
-#### *Common Config Chart*
534
-
535
-> NOTE: All settings directly related to presets are in the custom section of the config.
536
-
537
-| Name | Description | Example | Required |
538
-| --- | --- | --- | --- |
539
-| `preset` | Manually enable the use of a preset. | `"preset": "google"`<br/>`"preset": "azure"` | `false` |
540
-| `customer_id` | Customer ID of the Google Workspaces instace you<br/>plan to use with the groups feature.| `"customer_id": ["Group1", "Group2"]` | If `google` preset is used with `groups` feature. |
541
-| `tenant_id` | Tenant ID from Azure AD, this is required to use<br/>the `azure` preset as it is part of the issuer url. | `"tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"` | If `Azure` preset is being used. |
542
-
543
-### Google Preset
544
-
545
-#### *Prerequisites*
546
-
547
-> Check out this [documentation](https://developers.google.com/identity/protocols/oauth2/openid-connect) to get ready before we start.
548
-
549
-#### *Basic Config Example*
550
-
551
-``` json
552
-"oidc": {
553
- "client": {
554
- "client_id": "268438852161-r8xa7qxwf3rr0shp1xnpgmm70bnag21p.apps.googleusercontent.com",
555
- "client_secret": "ETFWBX-gFEaxfPXs1tWmAOkuWDFTgoL3nwh"
556
- }
557
-}
558
-```
559
-
560
-#### *Specifics*
561
-
562
-If you notice above I forgot to add any preset related configs, however because google tags the client ID we can detect that and automatically use the google preset. The above config is tested, the sentive data has been scrambled of course. That said, you would normally use this preset in more advaced setups, let take a look at an example.
563
-
564
-#### *Advanced Example with Groups*
565
-
566
-``` json
567
-"oidc": {
568
- "client": {
569
- "client_id": "424555768625-k7ub3ovqs0yp7mfo0usvyyx51nfii61c.apps.googleusercontent.com",
570
- "client_secret": "QLBCQY-nRYmjnFWv3nKyHGmwQEGLokP6ldk"
571
- },
572
- "custom": {
573
- "preset": "google",
574
- "customer_id": "C46kyhmps",
575
- "buttonText": "Custom Button Text"
576
- },
577
- "groups": {
578
- "siteadmin": ["GroupA", "GroupB"],
579
- "revokeAdmin": true,
580
- "sync": true
581
- },
582
- "callbackURL": "https://mesh.your.domain/auth-oidc-google-callback"
583
-},
584
-```
585
-
586
-#### *Customer ID and Groups*
587
-
588
-As always, the client ID and secret are required, the customer ID on the other hand is only required if you plan to take advantage of the groups function *and* the google preset. This also requires you have a customer ID, if you have do, it is available in the Google Workspace Admin Console under Profile->View. Groups work the same as they would with any other IdP but they are pulled from the Workspace groups.
589
-
590
-#### *Schema*
591
-
592
-```json
593
-"custom": {
594
- "type": "object",
595
- "properties": {
596
- "preset": { "type": "string", "enum": ["azure", "google"]},
597
- "customer_id": { "type": "string", "description": "Customer ID from Google, should start with 'C'."}
598
- },
599
- "additionalProperties": false
600
-},
601
-```
602
-
603
-### Azure Preset
604
-
605
-#### *Prerequisites*
606
-
607
-To configure OIDC-based SSO, you need an Azure account with an active subscription. [Create an account](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) 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.
608
-
609
-> Check this [documentation](https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/add-application-portal-setup-oidc-sso) for more information.
610
-
611
-#### *Basic Config Example*
612
-
613
-``` json
614
-"oidc": {
615
- "client": {
616
- "client_id": "a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r",
617
- "client_secret": "AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"
618
- },
619
- "custom": {
620
- "preset": "azure",
621
- "tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"
622
- }
623
-}
624
-```
625
-
626
-#### *Specifics*
627
-
628
-As with all other types of configuration for the OIDC strategy, the Azure preset requires a client ID and secret.The tenant ID is used as part of the issuer URI to make even the most basic AuthN requests so it is also required for the azure preset. besides that groups are available to the Azure preset as well as the recursive feature of groups. This allows you to search user groups recursively for groups they have membership in through other groups.
629
-
630
-> NOTE: The Azure AD preset uses the Tenant ID as part of the issuer URI:<br>`"https://login.microsoftonline.com/"` + `strategy`.custom.tenant_id + `"/v2.0"`
631
-
632
-#### *Advanced Example with Groups*
633
-
634
-``` json
635
-"oidc": {
636
- "client": {
637
- "client_id": "a1gkl04i-40g8-2h74-6v41-2jm2o2x0x27r",
638
- "client_secret": "AxT6U5K4QtcyS6gF48gndL7Ys22BL15BWJImuq1O"
639
- },
640
- "custom": {
641
- "preset": "azure",
642
- "tenant_id": "46a6022g-4h33-1451-h1rc-08102ga3b5e4"
643
- },
644
- "groups": {
645
- "recursive": true,
646
- "siteadmin": ["GroupA", "GroupB"],
647
- "revokeAdmin": true,
648
- "sync": true
649
- },
650
- "callbackURL": "https://mesh.your.domain/auth-oidc-azure-callback"
651
-},
652
-```
653
-
654
-#### *Schema*
655
-
656
-```json
657
-"custom": {
658
- "type": "object",
659
- "properties": {
660
- "preset": { "type": "string", "enum": ["azure", "google"]},
661
- "tenant_id": { "type": "string", "description": "Tenant ID from Azure AD."}
662
- },
663
- "additionalProperties": false
664
-},
665
-```
666
-
667
-## Depreciated Properties
668
-
669
-### Overview
670
-
671
-#### Introduction
672
-
673
-As of MeshCentral `v1.1.22` and the writing of this documentation, the node module that handles everything was changed from [passport-openid-connect](https://github.com/jaredhanson/passport-openidconnect) to [openid-client](https://github.com/panva/node-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.
674
-
675
-#### *Migrating Old Configs*
676
-
677
-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.
678
-
679
-#### *Old Config Example*
680
-```json
681
-"oidc": {
682
- "newAccounts": true,
683
- "clientid": "421326444155-i1tt4bsmk3jm7dri6jldekl86rfpg07r.apps.googleusercontent.com",
684
- "clientsecret": "GNLXOL-kEDjufOCk6pIcTHtaHFOCgbT4hoi"
685
-}
686
-```
687
-
688
-This example was chosen because I wanted to highlight an advantage of supporting these old configs long term, even in a depreciated status. That is, the ability to copy your existing config from one of the related strategies without making any changes to your config by using the presets. This allows you to test out the oidc strategy without commiting to anything, since the user is always appended with the strategy used to login. In this example, the config was originally a google auth strategy config, changing the `"google"` to `"oidc"` is all that was done to the above config, besides obsfuscation of course.
689
-
690
-#### *Advcanced Old Config Example*
691
-
692
-``` json
693
-"oidc": {
694
- "authorizationURL": "https://sso.your.domain/api/oidc/authorization",
695
- "callbackURL": "https://mesh.your.domain/oauth2/oidc/callback",
696
- "clientid": "tZiPTMDNuSaQPapAQJtwDXVnYjjhQybc",
697
- "clientsecret": "vrQWspJxdVAxEFJdrxvxeQwWkooVcqdU",
698
- "issuer": "https://sso.your.domain",
699
- "tokenURL": "https://sso.your.domain/api/oidc/token",
700
- "userInfoURL": "https://sso.your.domain/api/oidc/userinfo",
701
- "logoutURL": "https://sso.your.domain/logout?rd=https://mesh.your.domain/login",
702
- "groups": {
703
- "recursive": true,
704
- "required": ["Group1", "Group2"],
705
- "siteadmin": ["GroupA", "GroupB"],
706
- "sync": {
707
- "filter": ["Group1", "GroupB", "OtherGroup"]
708
- }
709
- },
710
- "newAccounts": true
711
-},
712
-```
713
-
714
-#### *Upgrading to v1.1.22*
715
-
716
-If you were already using a meticulusly configured oidc strategy, all of your configs will still be used. You will simply see a warning in the logs if any depreciated properties were used. If you check the authLog there are additional details about the old config and provide the new place to put that information. In this advanced config, even the groups will continue to work just as they did before without any user intervention when upgrading from a version of MeshCentral pre v1.1.22. There are no step to take and no action is needed, moving the configs to the new locations is completely optional at the moment.
717
-
718
-# Links
719
-
720
-https://cloud.google.com/identity/docs/reference/rest/v1/groups/list
721
-
722
-https://www.onelogin.com/learn/authentication-vs-authorization
723
-
724
-https://auth0.com/docs/authenticate/protocols/openid-connect-protocol
725
-
726
-https://github.com/panva/node-openid-client
727
-
728
-https://openid.net/connect/
729
-
730
-> You just read `openidConnectStrategy.ms v1.0.1` by [@mstrhakr](https://github.com/mstrhakr)
docs/docs/meshcentral/plugins.md
deleted
-140
@@ -1,140 +0,0 @@
1
-# Plugins - Installation & Usage
2
-
3
-!!!note
4
- 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**!
5
-
6
-## Use Cases
7
-
8
-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.
9
-
10
-## List of publically available plugins
11
-
12
-<https://github.com/topics/meshcentral-plugin>
13
-
14
-## Installation of a plugin
15
-
16
-1. First please make sure that you enable plugins in the configuration
17
- >"plugins": {
18
- > "enabled": true
19
- >},
20
-2. Restart MeshCentral if you needed to change the configuration.
21
-2. Log into MeshCentral as full administrator.
22
-3. Go my `My Server` -> `Plugins`, then hit the Download plugin button.
23
-4. A dialog opens requesting a URL, e.g. put in: <https://github.com/ryanblenis/MeshCentral-ScriptTask>
24
-5. The plugin pops up in the plugin list below the download button, you can now configure and enable/disable it.
25
-
26
-# Plugins - Development & Hooks
27
-
28
-!!!note
29
- 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**!
30
-
31
-## Overview
32
-
33
-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.
34
-
35
-## Anatomy of a plugin:
36
-
37
- - plugin_name/
38
- -- config.json
39
- -- plugin_name.js
40
- -- modules_meshcore/ // optional
41
- --- plugin_name.js // optional
42
-
43
-## Plugin Configuration File
44
-
45
-A valid JSON object within a file named `config.json` in the root folder of your project. An example:
46
-
47
- {
48
- "name": "Plugin Name",
49
- "shortName": "plugin_name",
50
- "version": "0.0.0",
51
- "author": "Author Name",
52
- "description": "Short Description of the plugin",
53
- "hasAdminPanel": false,
54
- "homepage": "https://www.example.com",
55
- "changelogUrl": "https://raw.githubusercontent.com/User/Project/master/changelog.md",
56
- "configUrl": "https://raw.githubusercontent.com/User/Project/master/config.json",
57
- "downloadUrl": "https://github.com/User/Project/archive/master.zip",
58
- "repository": {
59
- "type": "git",
60
- "url": "https://github.com/User/Project.git"
61
- },
62
- "versionHistoryUrl": "https://api.github.com/repos/User/Project/tags",
63
- "meshCentralCompat": ">0.4.3"
64
- }
65
-
66
-## Configuration File Properties
67
-
68
-| Field | Required | Type | Description |
69
-| ----------------- | -------- | ----------- | ------------------------------------------------------------ |
70
-| name | Yes | string | a human-readable name for the plugin |
71
-| shortName | Yes | string | an alphanumeric, unique short identifier for the plugin (will be used to access your functions throughout the project |
72
-| version | Yes | string | the current version of the plugin |
73
-| author | No | string | the author's name |
74
-| description | Yes | string | a short, human-readable description of what the plugin does |
75
-| hasAdminPanel | Yes | boolean | `true` or `false`, indicates whether or not the plugin will offer its own administrative interface |
76
-| homepage | Yes | string | the URL of the projects homepage |
77
-| changelogUrl | Yes | string | the URL to the changelog of the project |
78
-| configUrl | Yes | string | the URL to the config.json of the project |
79
-| downloadUrl | Yes | string | the URL to a ZIP of the project (used for installation/upgrades) |
80
-| repository | Yes | JSON object | contains the following attributes |
81
-| repository.type | Yes | string | valid values are `git` and in the future, `npm` will also be supported. |
82
-| repository.url | Yes | string | the URL to the project's repository |
83
-| versionHistoryUrl | No | string | the URL to the project's versions/tags |
84
-| 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. |
85
-
86
-## Plugin Hooks
87
-
88
-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.
89
-
90
-These are separated into the following categories depending on the type of functionality the plugin should offer.
91
-
92
-- Web UI, to modify the MeshCentral admin interface
93
-- Back End, to modify core functionality of the server and communicate with the Web UI layer as well as the Mesh Agent (Node) layer to send commands and data
94
-- Mesh Agent (Node), to introduce functionality to each agent
95
-
96
-### Web UI Hooks
97
-
98
-- `onDeviceRefreshEnd`: called when a device is selected in the MeshCentral web interface
99
-- `registerPluginTab`: callable when a device is selected in the MeshCentral web interface to register a new tab for plugin data, if required. Accepts an object, or function that returns an object, with the following properties: { tabId: "yourShortNameHere", tabTitle: "Your Display Name"}. A tab and div with the associated ID and title will be created for your use
100
-- `onDesktopDisconnect`: called when a remote desktop session is disconnected
101
-- `onWebUIStartupEnd`: called when the page has loaded for the first time after a login / refresh
102
-- `goPageStart`: called before page changes take effect. Passes 2 arguments (<page number> : int, <event> : Event)
103
-- `goPageEnd`: called after page changes take effect. Passes 2 arguments (<page number> : int, <event> : Event)
104
-
105
-#### Exports
106
-
107
-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.
108
-
109
-### Back End Hooks
110
-
111
-- `server_startup`: called once when the server starts (or when the plugin is first installed)
112
-- `hook_agentCoreIsStable`: called once when an agent initially checks in
113
-- `hook_processAgentData`: called each time an agent transmits data back to the server
114
-- `hook_userLoggedIn`: called when a user has logged into the web interface
115
-- `hook_setupHttpHandlers`: called before all http handlers are setup
116
-
117
-### Mesh Agent
118
-
119
-Use of the optional file `plugin_name.js` in the optional folder `modules_meshcore` will include the file in the default meshcore file sent to each endpoint. This is useful to add functionality on each of the endpoints.
120
-
121
-## Structure
122
-
123
-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.
124
-
125
-
126
-## Ping-Pong
127
-
128
-If you build a plugin which makes use of `meshrelay.ashx`, keep in mind to either handle ping-pong messages (`serverPing`, `serverPong`) on the control channel or to request MeshCentral to not send such messages through sending the `noping=1` parameter in the connection URL. For a deeper sight search for "PING/PONG" in `meshrelay.js`.
129
-
130
-## Versioning
131
-
132
-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.
133
-
134
-## Changelog
135
-
136
-A changelog is highly recommended so that your users know what's changed since their last version.
137
-
138
-## Sample Plugin
139
-
140
-[MeshCentral-Sample](https://github.com/ryanblenis/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.
docs/docs/meshcentral/security.md
deleted
-55
@@ -1,55 +0,0 @@
1
-# Security
2
-
3
-## Rate Limiting login attempts
4
-
5
-You can use the MeshCentral Server Console with the command `badlogins` to see the current settings.
6
-
7
-Adjust these items in your `config.json`
8
-
9
-```json
10
-"settings": {
11
- "_maxInvalidLogin": {
12
- "time": 10,
13
- "count": 10,
14
- "coolofftime": 10
15
- },
16
-}
17
-```
18
-
19
-
20
-
21
-## Disabling TLS 1.0/1.1 for AMT
22
-
23
-```json
24
-{
25
- "settings": {
26
- "mpshighsecurity": true
27
- }
28
-}
29
-```
30
-
31
-## Duo 2FA setup
32
-
33
-MeshCentral supports Duo as a way for users to add two-factor authentication and Duo offers free accounts for user 10 users. To get started, go to [Duo.com](https://duo.com/) and create a free account. Once logged into Duo, select "Applications" and "Protect an Application" on the left side. Search for "Web SDK" and hit the "Protect" button. You will see a screen with the following information:
34
-
35
- - Client ID
36
- - Client secret
37
- - API hostname
38
-
39
-Copy these three values in a safe place and do not share these values with anyone. Then, in your MeshCentral config.json file, add the following in the domains section:
40
-
41
-```json
42
-{
43
- "domains": {
44
- "": {
45
- "duo2factor": {
46
- "integrationkey": "ClientId",
47
- "secretkey": "ClientSecret",
48
- "apihostname": "api-xxxxxxxxxxx.duosecurity.com"
49
- }
50
- }
51
- }
52
-}
53
-```
54
-
55
-Restart MeshCentral and your server should now be Duo capable. Users will see an option to enable it in the "My Account" tab. When enabling it, users will be walked through the process of downloading the mobile application and going through a trial run on 2FA. Users that get setup will be added to your Duo account under the "Users" / "Users" screen in Duo. Note that the "admin" user is not valid in Duo, so, if you have a user with the name "Admin" in MeshCentral, they will get an error trying to setup Duo.
docs/docs/meshcentral/tipsntricks.md
deleted
-45
@@ -1,45 +0,0 @@
1
-# Tips n' Tricks
2
-
3
-## Colors in SSH
4
-
5
-The SSH terminal does support color. The issue is going to be the terminal configuration of the shell. Try typing this:
6
-
7
-```bash
8
-ls -al --color /tmp
9
-```
10
-
11
-## Fancy config editing with VS Code
12
-
13
-A common problem in the issues is an incorrect config.json. What makes a config incorrect? How can you verify your config is correct?
14
-
15
-Easy! Use Visual Studio Code to edit your config.json and add the schema at the top.
16
-
17
-If you haven't already, download VS code.
18
-Download or copy the config.json to your computer.
19
-Open config.json in code and add the schema as the top line. This schema is the raw JSON file in the MeshCentral repo.
20
-
21
-```json
22
-{
23
- "$schema": "https://raw.githubusercontent.com/Ylianst/MeshCentral/master/meshcentral-config-schema.json",
24
- "settings": {
25
- "your settings go here": "..."
26
- }
27
-}
28
-```
29
-
30
-Now you have autocomplete, auto-format and validation for your config.json! If you start typing, Code will show the values that are valid for the location you are editing. Words with a red squiggle line are errors. Words with a orange squiggle line are warnings. Hover over both to see the error message and possible fixes. Code can even format your config.
31
-
32
-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).
33
-
34
-Hopefully this will help verify your config is syntactically correct and prevent needless formatting errors, misspellings, etc.
35
-
36
-
37
-
38
-## Downloading Folders
39
-
40
-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.
41
-
42
-## Share device groups with AD logins
43
-If you would like to share device groups with different AD users.
44
-
45
-In the config.json set "ldapuserkey" to "sAMAccountName".
docs/docs/meshcentral/tokens.md
deleted
-25
@@ -1,25 +0,0 @@
1
-# 14.1 Tokens
2
-
3
-## User Tokens
4
-
5
-
6
-
7
-
8
-
9
-## Software Integration Tokens
10
-
11
-!!!warning
12
- You can only have a SINGLE loginTokenKey for your meshcentral server!<br>
13
- So if you regenerate a loginTokenKey, the old one will be revoked/deleted!
14
-
15
-You can create/view the Login Token Key with the following:
16
-
17
-```bash
18
-node node_modules/meshcentral --loginTokenKey
19
-```
20
-
21
-You can then reset/revoke/renew the Login Token Key with the following to create a new one:
22
-
23
-```bash
24
-node node_modules/meshcentral --loginTokenKey --loginTokenGen
25
-```
docs/docs/meshcmd/images/2022-05-15-15-11-39.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-11-39.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-21-12.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-21-12.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-22-07.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-22-07.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-23-45.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-23-45.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-24-12.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-24-12.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-27-41.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-27-41.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-30-02.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-30-02.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-30-41.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-30-41.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-32-15.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-32-15.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-37-16.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-37-16.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-39-40.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-39-40.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-40-05.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-40-05.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-41-20.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-41-20.png and /dev/null differ
docs/docs/meshcmd/images/2022-05-15-15-42-01.png
Binary files a/docs/docs/meshcmd/images/2022-05-15-15-42-01.png and /dev/null differ
docs/docs/meshcmd/index.md
deleted
-492
@@ -1,492 +0,0 @@
1
-# MeshCmd
2
-
3
----
4
-Access the official MeshCmd user guide in your preferred format
5
-
6
-> - [📄 PDF version](https://meshcentral.com/docs/MeshCmdUserGuide.pdf)
7
-> - [📝 ODT version](../documents/MeshCmd%20User's%20Guide%20v0.0.3.odt)
8
----
9
-
10
-## 🎬 Video Walkthrough
11
-
12
-<div class="video-wrapper">
13
- <iframe width="320" height="180" src="https://www.youtube.com/embed/AzdKyzqmpIs" frameborder="0" allowfullscreen></iframe>
14
-</div>
15
-
16
-
17
-
18
-## 🧾 Abstract
19
-
20
-This user guide contains all essential information for the user to make full use of MeshCmd, a command line tool used to perform tasks on MeshCentral and for Intel® AMT. This tool run on Windows and Linux and perform a wide array of different tasks. From routing traffic over the Internet to activating Intel AMT, MeshCmd is a great do it all tool for computer management.
21
-
22
-## 📘 Introduction
23
-
24
-MeshCmd, called “Mesh Command”, is a command line tool that runs on both Windows and Linux and used to perform many tasks related to computer management. As the tool continues to evolve, it will continue to be improved and acquire more features.
25
-
26
-Broadly, the tool is intended to perform three sets of tasks :
27
-
28
-- `MeshCentral2 command line operations`
29
-> 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 through a MeshCentral2 server.
30
-
31
-- `Intel AMT local actions`
32
-> 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.
33
-
34
-- `Intel AMT remote actions`
35
-> 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.
36
-
37
-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](http://www.meshcommander.com/meshcommander/meshcmd)
38
-
39
-
40
-
41
-If you have access to a MeshCentral2 server, the download link to MeshCmd is at the bottom left of the main device page.
42
-
43
-
44
-
45
-Once you click on the `MeshCmd` link, a dialog box will allow you to select the operating system you want to get a link to MeshCmd. MeshCentral will also provide an action file called meshaction.txt that contains information on how MeshCmd can connect back to that MeshCentral server. This is optional, and only used for some operations.
46
-
47
-Once downloaded, just run it from the command prompt or terminal window.
48
-
49
-```bash
50
-C:\Temp>meshcmd
51
-MeshCentral Command (MeshCmd)
52
-No action specified, use MeshCmd like this:
53
-
54
- meshcmd [action] [arguments...]
55
-
56
-Valid MeshCentral actions:
57
- Route - Map a local TCP port to a remote computer.
58
-
59
-Valid local actions:
60
- SMBios - Display System Management BIOS tables for this computer.
61
- RawSMBios - Display RAW System Management BIOS tables for this computer.
62
- MicroLMS - Run MicroLMS, allowing local access to Intel AMT.
63
- AmtInfo - Show Intel AMT version and activation state.
64
- AmtVersions - Show all Intel ME version information.
65
- AmtHashes - Show all Intel AMT trusted activation hashes.
66
- AmtCCM - Activate Intel AMT into Client Control Mode.
67
- AmtACM - Activate Intel AMT into Admin Control Mode.
68
- AmtDeactivate - Deactivate Intel AMT if activated in Client Control mode.
69
- AmtAcmDeactivate - Deactivate Intel AMT if activated in Admin Control mode.
70
-
71
-Valid local or remote actions:
72
- MeshCommander - Launch a local MeshCommander web server.
73
- AmtUUID - Show Intel AMT unique identifier.
74
- AmtAuditLog - Show the Intel AMT audit log.
75
- AmtLoadWebApp - Load MeshCommander in Intel AMT 11.6+ firmware.
76
- AmtClearWebApp - Clear everything from Intel AMT web storage.
77
- AmtStorageState - Show contents of the Intel AMT web storage.
78
- AmtSaveState - Save all Intel AMT WSMAN object to file.
79
- AmtPresence - Heartbeat a local Intel AMT watchdog agent.
80
- AmtScript - Run .mescript on Intel AMT.
81
- AmtIDER - Mount local disk image to remote computer.
82
-
83
-Help on a specific action using:
84
-
85
- meshcmd help [action]
86
-```
87
-
88
-By default you will get the help screen with all of the different actions you can take with the tool. You can also get help by typing `help` followed by the action name. In this document we will cover the main actions that MeshCmd can perform. If you don’t use Intel AMT at all, then only the MeshCentral actions are interesting for you. If you use Intel AMT, the rest of the actions will be of interest to you.
89
-
90
-## 🔌 MeshCentral TCP port mapping
91
-
92
-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 through proxies and firewalls.
93
-
94
-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 through the server to port 123 on a remote device.
95
-
96
-
97
-
98
-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.
99
-
100
-One typical use of this is to route local port `1234` to port Microsoft RDP port 3389 on a remote device. Once routed, you can start a RDP session on `localhost:1234` and get a RDP session to the remote device. The RDP protocol is feature rich and efficient, so you get a great user experience regardless of where in the world the remote computer is at.
101
-
102
-To get started, click on a device in MeshCentral and click on the `Router` link on the bottom left of the device page.
103
-
104
-
105
-
106
-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 :
107
-
108
-```json
109
-{
110
- "action": "route",
111
- "localPort": 1234, Change this
112
- "remoteName": "AmtMachine7",
113
- "remoteNodeId": "node//@yw$s5jLUivpzZ49laprt4T0sBaOKImbDAiniothQwccZPukCB696$BvPWAW0Bg2",
114
- "remotePort": 3389, Change this
115
- "username": "admin",
116
- "password": "", Note that the password is empty
117
- "serverId": "D99362D5ED8BAEA8BF9E743B34B242256370C460FD66CB62373C6CFCB204D6D70
118
-7403E396CF0EF6DC2B3A42F735135FD",
119
- "serverHttpsHash": "D9DE9E27A229B5355708A3672FB23237CC994A680B3570D242A91E36B4AE5BC
120
-96539E59746E2B71EEF3DBDABBF2AE138",
121
- "debugLevel": 0,
122
- "serverUrl": "wss://devbox.mesh.meshcentral.com:443/meshrelay.ashx"
123
-}
124
-```
125
-
126
-The action file contains almost all the parameters needed to perform the route. It indicates the local and remote ports, the remote computer unique identifier, server location and authentication information and more. You can just put the action file in the same folder as MeshCmd and run MeshCmd, it will automatically pick up the arguments from the meshaction.txt file.
127
-
128
-You may want to change the local and remote port in the action file to suite your needs. By default, the Microsoft RDP port is the target. If the password is not specified in the `meshaction.txt` file, you can also specify it as a meshcmd argument.
129
-
130
-```bash
131
-C:\MeshCmd>meshcmd --pass xxxxxxxx
132
-Redirecting local port 1234 to AmtMachine7:3389. Press ctrl-c to exit.
133
-Now, the traffic router is ready. You can now RDP to localhost:1234 and login to the remote computer.
134
-```
135
-
136
-## 🧭 MeshCommander
137
-
138
-MeshCommander is a web based Intel AMT management console. MeshCmd has no less then three different versions of MeshCommander built-in, so if you are using Intel AMT, it’s worth a moment to get some knowledge about MeshCommander which is available as a standalone tool along with a full user’s guide at:[http://www.meshcommander.com/](http://www.meshcommander.com/)and also included as part of MeshCentral.
139
-
140
-The three versions included in MeshCmd are :
141
-
142
-- **MeshCommander as a local web server**.
143
-- **MeshCommander for LMS** .
144
-- **MeshCommander for firmware**.
145
-
146
-In this section, we review the three versions, how they are used and what can be done with them.
147
-
148
-### 1. MeshCommander local web server
149
-
150
-You can start MeshCommander on a local web server by typing `meshcmd meshcommander`. By default, local port `3000` is used, but you can optionally specify the port using `--localport [port]`. Running it with look like this:
151
-
152
-```bash
153
-C:\MeshCmd>meshcmd meshcommander
154
-MeshCommander running on HTTP port 3000. Ctrl-C to exit.
155
-```
156
-
157
-Once running, use a web browser and go to `http://localhost:3000` to see the MeshCommander web page. The page will start out without any computers in it and you will have to add some.
158
-
159
-
160
-
161
-In this mode, the local computers that are added will be stored in the browser’s storage cache. So, clearing the browser’s cache will also clear the list of computers. You can however load and save the list of computers using the `Open…` and `Save…` buttons. This version of MeshCommander will have some limitations when compared to the full version installed using the *Windows .MSI installer*. Notably :
162
-
163
-- No certificate management or validation.
164
-- Mutual-Authenticated TLS is not supported.
165
-- Kerberos authentication is not supported.
166
-- IDE-R is not supported.
167
-
168
-This said, features like KVM, Terminal and most Intel AMT configuration options are available which makes this a fairly powerful Intel AMT management console.
169
-
170
-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:
171
-
172
-```bash
173
-C:\MeshCmd>meshcmd meshcommander install
174
-Installing to "C:\Program Files (x86)\Open Source\MeshCmd\MeshCommander.exe" MeshCommander installed.
175
-```
176
-
177
-```bash
178
-C:\MeshCmd>meshcmd meshcommander start
179
-MeshCommander starting.
180
-```
181
-
182
-On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.
183
-
184
-### 2. LMS & MeshCommander
185
-
186
-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 through the MEI driver. One way to check if the LMS service is installed on your computer is to try *[http://localhost:16992](http://localhost:16992/)* or *[https://localhost:16993](https://localhost:16993/)* in a browser. A page should generally show up.
187
-
188
-!!! note
189
- On Windows, LMS is a Windows service that must be downloaded and installed as part of the OEM drivers for a computer.
190
- On Linux, it's generally never installed and users normally have to download the source code and compile it themselves.
191
-
192
----
193
-
194
-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:
195
-
196
-```bash
197
-C:\MeshCmd>meshcmd microlms
198
-MicroLMS started, MeshCommander on HTTP/16994.
199
-```
200
-
201
-This will start MicroLMS and as indicated, start MeshCommander on local port `16994` at the same time.
202
-
203
-In total, traffic redirection looks like this :
204
-
205
-
206
-
207
-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.
208
-
209
-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.
210
-
211
-Because it’s in this mode, you can use the web interface to de-activate Intel AMT or login to perform additional configuration.
212
-
213
-
214
-
215
-MicroLMS along with MeshCommander for LMS is very useful, especially on Linux as it offers a single tool to setup and configuration Intel AMT. If you wish you run MicroLMS without MeshCommander being available on port 16994, run MeshCmd with `--noconsole`:
216
-
217
-```bash
218
-C:\MeshCmd>meshcmd microlms --noconsole
219
-MicroLMS started.
220
-```
221
-
222
-You can run MicroLMS as a background server on both Windows and Linux. To do this, use the MicroLMS install, uninstall, start and stop commands like this :
223
-
224
-```bash
225
-C:\MeshCmd>meshcmd microlms install
226
-Installing to "C:\Program Files (x86)\Open Source\MeshCmd\MicroLMS.exe"
227
-MicroLMS installed.
228
-```
229
-
230
-```bash
231
-C:\MeshCmd>meshcmd microlms start
232
-MicroLMS starting.
233
-```
234
-
235
-On Linux computers, both systemd and initd are supported. When installing, the MeshCmd executable will be copied to a different installation folder.
236
-
237
-### 3. MeshCommander for firmware
238
-
239
-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.
240
-
241
-
242
-
243
-The firmware version of MeshCommander has support for remote desktop, terminal and all sorts of Intel AMT usages and configuration. Probably the most surprising is that this entire page is between 40k and 100k depending on the version you select. It’s notable that with MeshCommander loaded into Intel AMT firmware, one does not need any other tool except for a browser to perform most Intel AMT maintenance operations.
244
-
245
-```bash
246
-C:\MeshCmd>meshcmd amtloadwebapp --host 192.168.2.144 --pass xxxxxxxx
247
-Uploading MeshCommander...
248
-Verifying MeshCommander...
249
-Done.
250
-```
251
-
252
-To get the current state of Intel AMT web storage, type this :
253
-
254
-```bash
255
-C:\MeshCmd>meshcmd amtstoragestate --host 192.168.2.144 --pass xxxxxxxx
256
-Storage State: {
257
- "information": {
258
- "version": 1,
259
- "realms": 7765759,
260
- "user": "admin"
261
- },
262
- "content": {
263
- "index.htm": {
264
- "size": 57246 Replacement index.htm with size.
265
- }
266
- }
267
-}
268
-```
269
-
270
-Here, a 57k index.htm replacement is present in the Intel AMT flash. You can clear the web storage, revering the web page back to the original like this:
271
-
272
-```bash
273
-C:\MeshCmd>meshcmd amtclearwebapp --host 192.168.2.144 --pass xxxxxxxx
274
-Done.
275
-```
276
-
277
-When MeshCommander is loaded into Intel AMT, you can access it from a different computer using *[http://computername:16992 ](http://computername:16992/)* or *[https://computername:16993](https://computername:16993/)* You will need to authenticate first before getting access to the web page.
278
-
279
-## 🔧 Intel AMT state & activation
280
-
281
-MeshCmd can easily be used to read the local state of the computer and Intel AMT. There are many commands available to do this. The `SMBios` action works on most computers and is used to get basic information about your current system. The output is JSON format.
282
-
283
-```json
284
-C:\MeshCmd>meshcmd smbios
285
-{
286
- processorInfo: {
287
- 0: {
288
- Processor: "CPU"
289
- MaxSpeed: "3800 Mhz"
290
- Cores: 4
291
- Threads: 8
292
- Populated: 1
293
- Status: "Enabled"
294
- Socket: "CPU 1"
295
- Manufacturer: "Intel(R) Corporation"
296
- Version: "Intel(R) Core(TM) i7-3770 CPU @ 3.40GHz"
297
- }
298
- }
299
- memoryInfo: {
300
- location: "System Board"
301
- maxCapacityKb: 33554432
302
- }
303
- systemInfo: {
304
- uuid: "C57B83D9A94E11E18BA1505054503030"
305
- wakeReason: "Power Switch"
306
- }
307
- systemSlots: {
308
- uuid: "C57B83D9A94E11E18BA1505054503030"
309
- wakeReason: "Power Switch"
310
- }
311
- amtInfo: {
312
- AMT: true
313
- enabled: true
314
- storageRedirection: true
315
- serialOverLan: true
316
- kvm: true
317
- TXT: false
318
- VMX: true
319
- MEBX: "66.0.0.8"
320
- ManagementEngine: "8.1.0.57353"
321
- }
322
-}
323
-```
324
-
325
-If you have Intel AMT on your system, you can use the `amtinfo`, `amtversions` and `amthashes` to get lots of information about Intel AMT current state. These commands use the Intel AMT MEI driver to get this information and require MeshCmd be run as root or administrator :
326
-
327
-> `meshcmd amtinfo`
328
- ```bash
329
- C:\MeshCmd>meshcmd amtinfo
330
- Intel AMT v8.1.71, activated in client control mode.
331
- Wired Enabled, DHCP, 00:1E:8C:F5:4F:ED, 192.168.2.10.
332
- ```
333
-
334
-> `meshcmd amtversions`
335
- ```bash
336
- C:\MeshCmd>meshcmd amtversions
337
- MEI Version = MKQ7710H.86A.0072.2017.0519.1347
338
- Flash = 8.1.71
339
- Netstack = 8.1.71
340
- AMTApps = 8.1.71
341
- AMT = 8.1.71
342
- Sku = 24584
343
- VendorID = 8086
344
- Build Number = 3608
345
- Recovery Version = 8.1.71
346
- Recovery Build Num = 3608
347
- Legacy Mode = False
348
- ```
349
-
350
-> `meshcmd amthashes`
351
-```bash
352
-C:\MeshCmd>meshcmd amthashes
353
-VeriSign Class 3 Primary CA-G1, (Default, Active)
354
- SHA256: E7685634EFACF69ACE939A6B255B7B4FABEF42935B50A265ACB5CB6027E44E70
355
-VeriSign Class 3 Primary CA-G3, (Default, Active)
356
- SHA256: EB04CF5EB1F39AFA762F2BB120F296CBA520C1B97DB1589565B81CB9A17B7244
357
-…
358
-```
359
-
360
-In addition to getting Intel AMT state, MeshCmd can activate Intel AMT in client control mode (CCM) and de-activate Intel AMT if it’s in this mode. Doing this is very simple, starting with Intel AMT not being activated, you use the `amtccm` and `amtdeactivate` actions.
361
-
362
-> `meshcmd amtinfo`
363
-```bash
364
-C:\MeshCmd>meshcmd amtinfo
365
-Intel AMT v8.1.71, pre-provisioning state.
366
-```
367
-> `meshcmd amtccm --pass xxxxxxxx`
368
-```bash
369
-C:\MeshCmd>meshcmd amtccm --pass xxxxxxxx
370
-Success
371
-```
372
-> `meshcmd amtinfo`
373
-```bash
374
-C:\MeshCmd>meshcmd amtinfo
375
-Intel AMT v8.1.71, activated in client control mode.
376
-```
377
-> `meshcmd amtdeactivate`
378
-```bash
379
-C:\MeshCmd>meshcmd amtdeactivate
380
-Success
381
-```
382
-
383
-!!! note
384
- Note that when using the `amtccm` action, you'll 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 letter, an upper-case letter, a numeric value and a non-alpha-numeric value.
385
-
386
-## 📋 Intel AMT Audit Log
387
-
388
-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 through Intel AMT. MeshCmd can pull the audit log on a local computer without any credentials, as long as it’s running as root or administrator, or pull the audit log remotely if usual credentials are provided.
389
-
390
-
391
-
392
-The Intel AMT audit log will show when a computer’s Intel AMT was activated, when remote desktop sessions where initiated and more. To get the local audit log, just use the “AmtAuditLog” action.
393
-
394
-```shell
395
-C:\MeshCmd>meshcmd amtauditlog
396
-2004-01-01 19:17:58.000-08:00 - Local: Provisioning Started
397
-2018-01-26 14:03:16.000-08:00 - Local: Unprovisioning Started
398
-2018-01-26 14:03:31.000-08:00 - Local: Provisioning Started
399
-2018-02-01 12:13:14.000-08:00 - admin: KVM Enabled
400
-2018-02-01 12:16:01.000-08:00 - admin: KVM Session Started
401
-2018-02-01 12:16:07.000-08:00 - admin: KVM Session Ended
402
-2018-02-02 10:56:06.000-08:00 - admin: KVM Session Started
403
-2018-02-02 10:56:08.000-08:00 - admin: KVM Session Ended
404
-```
405
-
406
-To get a remote audit log :
407
-
408
-```shell
409
-C:\MeshCmd>meshcmd amtauditlog --host 192.168.2.144 --user admin --pass xxxxxxxx
410
-2003-12-31 23:06:58.000-08:00 - $$OsAdmin: Intel(r) ME Time Set
411
-2017-08-15 06:53:31.000-07:00 - $$OsAdmin: Intel(r) ME Time Set
412
-2017-10-13 17:55:11.000-07:00 - Local: Provisioning Started
413
-2017-10-13 17:55:54.000-07:00 - Local: Opt-In Policy Change
414
-2017-10-15 06:44:38.000-07:00 - admin: KVM Enabled
415
-```
416
-
417
-You can also save the audit log to file using the `--output` option.
418
-
419
-## 💻 Running Intel AMT script
420
-
421
-MeshCmd has a full WSMAN stack built-in and can be used to run `.mescript` file on a target Intel AMT computer. Script file are useful when you want to run a set of actions on one or more Intel AMT computers at once. You can build a .mescript file using the script editor within MeshCommander.
422
-
423
-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.
424
-
425
-
426
-
427
-In addition to building your own scripts, you can download a CIRA setup script from a MeshCentral server. When running this script, Intel AMT will be setup to call back to the server using an encrypted connection. This enables remote management of Intel AMT over the Internet. The CIRA setup script is available in the `Add CIRA` link for meshes that are Intel AMT only (no agent).
428
-
429
-
430
-
431
-Once you got the script, run it with MeshCmd like this. You specify the host if it’s not localhost, the password and the script file.
432
-
433
-```shell
434
-C:\MeshCmd>meshcmd amtscript --host 192.168.2.106 --pass xxxxxxxx --script cira_setup.mescript
435
-Script Started
436
-Policies removed successfully
437
-Adding root certificate...
438
-Management Presence Server (MPS) successfully added
439
-Found matching (primary) mps: Intel(r) AMT:Management Presence Server 0
440
-Setting policy...
441
-Policy added successfully
442
-Remote Access user interfaces set to: BIOS & OS Enabed
443
-Parsing block parameters
444
-Setting Environment Detection
445
-Environment Detection set successfully
446
-Script Completed
447
-```
448
-
449
-In this example, the CIRA setup script was run on a remote computer. After the script is run, the computer got configured and connected back to the server. MeshCentral show the new connection state for this computer.
450
-
451
-
452
-
453
-## ➡️ IDE Redirection
454
-
455
-## 🎬 Video Walkthrough
456
-
457
-<div class="video-wrapper">
458
- <iframe width="320" height="180" src="https://www.youtube.com/embed/iG73j7Toz1c" frameborder="0" allowfullscreen></iframe>
459
-</div>
460
-
461
-MeshCmd has all the code needed to perform Intel AMT IDE Redirection from the command line. This allows disk images on the administrator’s computer to be remotely mounted to an Intel AMT computer. You need to start with a floppy disk .img file and/or an .iso CDROM file.
462
-
463
-
464
-
465
-Then use the `AmtIDER` command of MeshCMD to start an IDER session. The help command for AmtIDER looks like this:
466
-
467
-```shell
468
-C:\Temp>meshcmd help amtider
469
-AmtIDER will mount a local disk images to a remote Intel AMT computer. Example usage:
470
-
471
- meshcmd amtider --host 1.2.3.4 --user admin --pass mypassword --tls --floppy disk.img --cdrom disk.iso
472
-
473
-Possible arguments:
474
-
475
- --host [hostname] The IP address or DNS name of Intel AMT.
476
- --user [username] The Intel AMT login username, admin is default.
477
- --pass [password] The Intel AMT login password.
478
- --tls Specifies that TLS must be used.
479
- --floppy [file] Specifies .img file to be mounted as a flppy disk.
480
- --cdrom [file] Specifies .img file to be mounted as a CDROM disk.
481
- --timeout [seconds] Optional, disconnect after number of seconds without disk read.
482
-```
483
-
484
- The command is fairly simple. It takes as input a remote host, username/password for Intel AMT login, the disk images and TLS option. One can also specify the timeout option so that MeshCMD will automatically disconnect when no disk read operations are performed for a set number of seconds.
485
-
486
-## 🏁 Conclusion
487
-
488
-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.
489
-
490
-## License
491
-
492
-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](https://www.apache.org/licenses/LICENSE-2.0)
docs/docs/meshctrl/images/2022-05-16-21-33-47.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-21-33-47.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-21-40-21.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-21-40-21.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-21-47-32.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-21-47-32.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-21-50-39.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-21-50-39.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-21-54-38.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-21-54-38.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-22-04-06.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-22-04-06.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-22-06-35.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-22-06-35.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-22-20-44.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-22-20-44.png and /dev/null differ
docs/docs/meshctrl/images/2022-05-16-22-23-40.png
Binary files a/docs/docs/meshctrl/images/2022-05-16-22-23-40.png and /dev/null differ
docs/docs/meshctrl/images/amt_commands.png
Binary files a/docs/docs/meshctrl/images/amt_commands.png and /dev/null differ
docs/docs/meshctrl/index.md
deleted
-497
@@ -1,497 +0,0 @@
1
-# MeshCtrl
2
-
3
-MeshCmd Guide [as .pdf](https://meshcentral.com/docs/MeshCtrlUsersGuide.pdf) [as .odt](../documents/MeshCtrl%20User's%20Guide%20v0.0.1.odt)
4
-
5
-## Video Walkthrough
6
-
7
-<div class="video-wrapper">
8
- <iframe width="320" height="180" src="https://www.youtube.com/embed/p_jdtYJyuBQ" frameborder="0" allowfullscreen></iframe>
9
-</div>
10
-
11
-
12
-
13
-
14
-## Abstract
15
-
16
-This user guide contains all essential information for the user to make full use of MeshCtrl, a command line tool used to perform tasks on the MeshCentral server. This tool is built in NodeJS and can be run on the same computer as the server, or on a different computer. It’s typically used by administrators to perform various management operations on the MeshCentral server.
17
-
18
-## Introduction
19
-
20
-MeshCtrl, also called “Mesh Control”, is a command line tool built in NodeJS that comes with MeshCentral and allows command line management operation of the MeshCentral server. It can be run both on the same computer as the MeshCentral server, or on a different computer. This tool allows an administrator to list user accounts, create and remove user accounts, list device groups and much more. All of the operations performed by this tool can also be performed using the MeshCentral website, however it’s sometimes useful to automate and script some management operations from the command line and this tool can do this.
21
-
22
-
23
-
24
-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.
25
-
26
-## Running MeshCtrl
27
-
28
-MeshCtrl.js is a file that is installed with MeshCentral and is located in the “./node\_modules/meshcentral” folder. You can normally run MeshCtrl like this:
29
-
30
-```
31
-node ./node\_modules/meshcentral/meshctrl
32
-```
33
-
34
-In this case, when the above command is run without parameters, you should see something like this:
35
-
36
-```
37
-MeshCtrl performs command line actions on a MeshCentral server.
38
-Information at: https://meshcommander.com/meshcentral
39
-No action specified, use MeshCtrl like this:
40
-
41
- meshctrl [action] [arguments]
42
-
43
-Supported actions:
44
- Help [action] - Get help on an action.
45
- ServerInfo - Show server information.
46
- UserInfo - Show user information.
47
- ListUsers - List user accounts.
48
- ListDevices - List devices.
49
- ListDeviceGroups - List device groups.
50
- ListUsersOfDeviceGroup - List the users in a device group.
51
- AddUser - Create a new user account.
52
- RemoveUser - Delete a user account.
53
- AddDeviceGroup - Create a new device group.
54
- RemoveDeviceGroup - Delete a device group.
55
- AddUserToDeviceGroup - Add a user to a device group.
56
- RemoveUserFromDeviceGroup - Remove a user from a device group.
57
- SendInviteEmail - Send an agent install invitation email.
58
- Broadcast - Display a message to all online users.
59
-
60
-Supported login arguments:
61
- --url [wss://server] - Server url, wss://localhost:443 is default.
62
- --loginuser [username] - Login username, admin is default.
63
- --loginpass [password] - Login password.
64
- --token [number] - 2nd factor authentication token.
65
- --loginkey [hex] - Server login key in hex.
66
- --loginkeyfile [file] - File containing server login key in hex.
67
- --domain [domainid] - Domain id, default is empty.
68
-```
69
-
70
-This indicated you have a good version of MeshCentral with support for MeshCtrl. MeshCentral and MeshCtrl will be updated together, so as changes are made to the server, MeshCtrl will also be updated to match.
71
-
72
-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.
73
-
74
-## Login
75
-
76
-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.
77
-
78
-### Login using username & password
79
-
80
-This is the easiest way to login and start issuing commands is to login using a username and password.
81
-
82
-
83
-
84
-You do this by using the "loginuser" and "loginpass" argument like this:
85
-
86
-```
87
-node ./node_modules/meshcentral/meshctrl serverinfo --loginuser "admin" --loginpass "mypassword"
88
-```
89
-
90
-In this example we are trying to run the “serverinfo” command using the “admin” user and “mypassword” as the password. Because “admin” if the default username for MeshCtrl, you can omit it and just type:
91
-
92
-```
93
-Authentication token required, use --token [number].
94
-```
95
-
96
-In this case, you need to use the Google Authenticator application or a similar application to enter your time based second factor like this:
97
-
98
-```
99
-node ./node_modules/meshcentral/meshctrl serverinfo --loginpass "mypassword" –token 123456
100
-```
101
-
102
-Once the command is run successfully, you should see a response like this:
103
-
104
-```
105
-name: devbox.meshcentral.com
106
-mpsname: devbox.meshcentral.com
107
-mpsport: 4433
108
-port: 443
109
-emailcheck: true
110
-domainauth: false
111
-tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
112
-https: true
113
-redirport: 80
114
-```
115
-
116
-This is a typical response for the “serverinfo” command and a good way to test that everything is working as expected.
117
-
118
-### Login using the server login key
119
-
120
-This technique needs some setup, but allows MeshCtrl to login as any account without knowing the password of the account, making it very powerful. Care must be taken when doing this and it’s recommended to only be done on the local server itself unless you know when you are doing.
121
-
122
-
123
-
124
-In this technique, we will get a special encryption key from the server and use this to generate a login token to the server. First, we must activate the login token feature of the server by setting “AllowLoginToken” to “true” in the “settings” section of config.json:
125
-
126
-```json
127
-{
128
- "settings": {
129
- "Port": 443,
130
- "AllowLoginToken": true
131
- }
132
-}
133
-```
134
-
135
-Then run the MeshCentral server with the --logintokenkey parameter, you should see something like this:
136
-
137
-```
138
-node ./node_modules/meshcentral --logintokenkey
139
-f3bd69a08a2dde4a3423bec8f20d8626b1e6365381f2d9919e7dfe256ace9cbbdea66bed2bdcd00b71eea9d7c727cb6eb37f3148c0c2d240d5ed44c8f3f6795a479c949159dad366571fea4db7f31c24
140
-```
141
-
142
-The hex value presented here is a sensitive secret that allows anyone to create login tokens that can be used for user impersonation. This key is used when MeshCentral does server peering and load balancing for example. You should save this key in a file, for example “key.txt”, you can do it like this:
143
-
144
-```
145
-node ./node_modules/meshcentral –logintokenkey > key.txt
146
-```
147
-
148
-Now that you have the server key, you can use MeshCtrl like this:
149
-
150
-```
151
-node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --loginuser admin
152
-```
153
-
154
-Instead of using a password, we use the key file instead. MeshCtrl will generate a time limited cookie and use that to login as “admin”. Since “admin” is the default username for MeshCtrl, we can omit this parameter:
155
-
156
-```
157
-node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt
158
-```
159
-
160
-Like the username and password example above, the result will be the server information we requested. Something like this:
161
-
162
-```
163
-name: devbox.meshcentral.com
164
-mpsname: devbox.meshcentral.com
165
-mpsport: 4433
166
-port: 443
167
-emailcheck: true
168
-domainauth: false
169
-tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
170
-https: true
171
-redirport: 80
172
-```
173
-
174
-### Login into a different domain
175
-
176
-So far, we have seen how to login to a MeshCentral server using a username/password or username/key technique for the default domain. MeshCentral supports many domains at once with each of the domain having its own set of users, groups and administrators.
177
-
178
-
179
-
180
-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:
181
-
182
-```
183
-node ./node_modules/meshcentral/meshctrl serverinfo --url wss://server/domainname --loginuser "admin" --loginpass "mypassword"
184
-```
185
-
186
-or for servers have a DNS name for a domain:
187
-
188
-```
189
-node ./node_modules/meshcentral/meshctrl serverinfo --url wss://domainname.server --loginuser "admin" --loginpass "mypassword"
190
-```
191
-
192
-Note the "--url" argument is different and so, the server will see MeshCtrl access the server using a different domain.
193
-
194
-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:
195
-
196
-```
197
-node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://server/domainname --domain mycustomer
198
-```
199
-
200
-So, we add both the url to access the correct domain and the domain name explicitly. The domain name must be exactly the one that is used in the domain section of the config.json for of MeshCentral. For example, if the MeshCentral config.json file looks like this:
201
-
202
-```json
203
-{
204
- "settings": {
205
- "Cert": "myserver.com",
206
- "Port": 443
207
- },
208
- "domains": {
209
- "": {
210
- "title": "Default domain",
211
- },
212
- "customer1": {
213
- "dns": "c1.myserver.com",
214
- "title": "Customer1 domain",
215
- }
216
- }
217
-}
218
-```
219
-
220
-The domain login for MeshCtrl with a key file would look like this:
221
-
222
-```
223
-node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://c1.myserver.com --domain customer1
224
-```
225
-
226
-In the next section, we start making use of MeshCtrl to do useful things on the server. From now on, we will omit the login arguments, but note that they are required for all commands.
227
-
228
-## Making use of MeshCtrl
229
-
230
-We can start doing useful operations with MeshCtrl. The current list of operations are:
231
-
232
-```
233
-edituser
234
-listusers
235
-listusersessions
236
-listdevicegroups
237
-listdevices
238
-listusersofdevicegroup
239
-listevents
240
-logintokens
241
-serverinfo
242
-userinfo
243
-adduser
244
-removeuser
245
-adddevicegroup
246
-removedevicegroup
247
-editdevicegroup
248
-broadcast
249
-showevents
250
-addusertodevicegroup
251
-removeuserfromdevicegroup
252
-addusertodevice
253
-removeuserfromdevice
254
-sendinviteemail
255
-generateinvitelink
256
-config
257
-movetodevicegroup
258
-deviceinfo
259
-editdevice
260
-addusergroup
261
-listusergroups
262
-removeusergroup
263
-runcommand
264
-shell
265
-upload
266
-download
267
-deviceopenurl
268
-devicemessage
269
-devicetoast
270
-addtousergroup
271
-removefromusergroup
272
-removeallusersfromusergroup
273
-devicesharing
274
-devicepower
275
-indexagenterrorlog
276
-agentdownload
277
-report
278
-```
279
-
280
-You can get this list by just running MeshCtrl without any argument and can get more information on each action by typing “meshctrl help [action]”
281
-
282
-
283
-
284
-!!!note
285
- 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".
286
-
287
-### Gathering information
288
-
289
-The following commands are really easy to use: serverinfo, userinfo, listusers, listdevices, listdevicegroups. They just request information from the server. Note that for these commands, you can optionally use “--json" to receive the response in JSON format. For example, getting the list of users will look like this:
290
-
291
-```
292
-node meshctrl.js listusers
293
-id, name, email
294
----------------
295
-"admin", "admin", "username@domain.com"
296
-"joe", "joe", "joe@domain.com"
297
-"mytestuser", "MyTestUser", "a@a.com"
298
-"test.user", "test.user", "test.user@user.com"
299
-```
300
-
301
-In the --json argument is used, it looks like this:
302
-
303
-```
304
-node meshctrl.js listusers --json
305
- {
306
- "_id": "user//admin",
307
- "name": "admin",
308
- "creation": 1417814230,
309
- "siteadmin": 4294967295,
310
- …
311
-```
312
-
313
-The JSON version is much long and contain much more information. This format can be useful if you take the output of MeshCtrl and dump it into a file for later parsing. One really useful command is “listdevices” that just displays all the devices in the account grouped by device groups. For example:
314
-
315
-```
316
-node meshctrl listdevices
317
-
318
-Device group: "Lab Computers"
319
-id, name, icon, conn, pwr, ip
320
------------------------------
321
-p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
322
-yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
323
-DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
324
-ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
325
-ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
326
-fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
327
-hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
328
-YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
329
-PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
330
-tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
331
-i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
332
-2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
333
-0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
334
-
335
-Device group: "IntelAMT only"
336
-id, name, icon, conn, pwr, ip
337
------------------------------
338
-LN8qsH634RGjDwATIOd3ICzfKrB@t@ERow8AEyDndyAs3yqwfrfhEaMPABMg53cg, "AmtMachine7", 0, 0, 0
339
-Ea3GcF$EoMnDEc9Tbz$Vu9wnmTziqqcOZ0URSdYeuVn4LU9LLMT@91P5s1WLSgVA, "DevBox", 0, 0, 0
340
-```
341
-
342
-It’s also possible to list only the display the list of devices for a single group. Just add --id followed by the group identifier. You can find the group identifier using the “DeisplayDeviceGroups” command. For example:
343
-
344
-```
345
-node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055…
346
-
347
-id, name, icon, conn, pwr, ip
348
------------------------------
349
-p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
350
-yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
351
-DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
352
-ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
353
-ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
354
-fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
355
-hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
356
-YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
357
-PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
358
-tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
359
-i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
360
-2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
361
-0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
362
-```
363
-
364
-You can also add “--count" to just return the number of devices instead of displaying them. An example of this would be:
365
-
366
-```
367
-node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055… --count
368
-13
369
-```
370
-
371
-Here we see that in a specific device group, there are 13 devices.
372
-
373
-### Adding and removing accounts
374
-
375
-MeshCtrl can be used to add and remove user accounts. This is great is you want to automate MeshCentral in some situations. Normally, an administrator can go to the “My Users” tab and press “New Account…” button to create a new account.
376
-
377
-
378
-
379
-With MeshCtrl the same process can be accomplished using the following command line:
380
-
381
-```
382
-node ./node_modules/meshcentral/meshctrl adduser --user SampleUser --pass SamplePassword
383
-```
384
-
385
-This will create a basic user account with the specified “SampleUser” username and “SamplePassword” password. In addition to the basic example above, there are plenty of additional arguments that can be used. There is a list:
386
-
387
-```
388
---email [email] - New account email address.
389
---emailverified - New account email is verified.
390
---resetpass - Request password reset on next login.
391
---siteadmin - Create the account as full site administrator.
392
---manageusers - Allow this account to manage server users.
393
---fileaccess - Allow this account to store server files.
394
---serverupdate - Allow this account to update the server.
395
---locked - This account will be locked.
396
---nonewgroups - Account will not be allowed to create device groups
397
---notools - Account not see MeshCMD download links.
398
-```
399
-
400
-Instead of specifying a password, one can specify “--randompass" to have MeshCtrl generate a random password, this is typically use along with “--resetpass" and “--email" to cause the user to perform a password reset the first time a login occurs.
401
-
402
-The permission arguments are used to grant server permissions to the new account. The “-- siteadmin" argument will grant this account full site administrator rights and all other permission arguments are ignored. The other permission arguments can be combined.
403
-
404
-To remove a user account, use the following command:
405
-
406
-```
407
-node ./node_modules/meshcentral/meshctrl removeuser --userid SampleId
408
-```
409
-
410
-Note that when creating a new user, the username is passed in. However, when removing a user account, the userid is used. One can get the list of userid’s by using the “ListUsers” command.
411
-
412
-MeshCtrl will return “ok” if the command is successful and the account will be added in real-time to the “My Users” tab on the website.
413
-
414
-### Creating and removing device groups
415
-
416
-MeshCtrl can be used to add and remove device groups. When a group is created, it’s added in the account that MeshCtrl is logged into and that account gets full rights over that device group. Typically, a new device group is created using the “Add Device Group” link in the main website.
417
-
418
-
419
-
420
-A group has a name, type and optionally a description text. To add a device group using MeshCtrl, we use the “AddDeviceGroup” command like this:
421
-
422
-```
423
-node ./node_modules/meshcentral/meshctrl adddevicegroup --name "Sample group name" --desc "Sample description"
424
-```
425
-
426
-Here we specify the name and description of the new device group. This will create a normal device group that requires agents to be installed on each computer. You can also create an agent-less Intel AMT device group by adding the "--amtonly" argument. Once done, MeshCtrl will return “ok" and the group will be created in the logged in account in real-time.
427
-
428
-You can delete a group by using the “RemoveDeviceGroup” command like this:
429
-
430
-```
431
-node ./node_modules/meshcentral/meshctrl removedevicegroup --id 7b4b43cd…dc89fe0e581c
432
-```
433
-
434
-To remove a device group, the group identifier needs to be specified. You can get that identifier using the "ListDeviceGroups" command. For device groups, the group identifier is a long hex value.
435
-
436
-### Adding and removing users from device groups
437
-
438
-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.
439
-
440
-
441
-
442
-To do this, you first have to get the user and group identifiers. You can get these using the “listusers” and “listdevicegroups” commands. Then, you can for example do this:
443
-
444
-```
445
-node ./node_modules/meshcentral/meshctrl addusertodevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob --fullrights
446
-```
447
-
448
-Typically, the group identifier is a long hex value. The command will add user “bob” to a given group with full rights. You can also add a user to a group with only some rights, the list is as follows:
449
-
450
-```
451
- --fullrights - Allow full rights over this device group.
452
- --editgroup - Allow the user to edit group information.
453
- --manageusers - Allow the user to add/remove users.
454
- --managedevices - Allow the user to edit device information.
455
- --remotecontrol - Allow device remote control operations.
456
- --agentconsole - Allow agent console operations.
457
- --serverfiles - Allow access to group server files.
458
- --wakedevices - Allow device wake operation.
459
- --notes - Allow editing of device notes.
460
- --desktopviewonly - Restrict user to view-only remote desktop.
461
- --limiteddesktop - Limit remote desktop keys.
462
- --noterminal - Hide the terminal tab from this user.
463
- --nofiles - Hide the files tab from this user.
464
- --noamt - Hide the Intel AMT tab from this user.
465
-```
466
-
467
-Note that if “fullrights” are granted, all other access right arguments are ignored. If successful, MeshCtrl will display “ok”, otherwise it will show an error message.
468
-
469
-To remove a user from a group, use the “removeuserfromdevicegroup” command. For example:
470
-
471
-```
472
-node ./node_modules/meshcentral/meshctrl removeuserfromdevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob
473
-```
474
-
475
-The syntax of this command is identical to the “addusertodevicegroup” command, but there are no rights arguments. MeshCtrl will also display “ok” if the command got processed correctly.
476
-
477
-### Message Broadcast
478
-
479
-One fun command the MeshCtrl offers is the “broadcast” command. It sends a short notification message that all connected users will see in real-time. For example, you can do this:
480
-
481
-```
482
-node ./node\_modules/meshcentral/meshctrl broadcast --msg "This is a test"
483
-```
484
-
485
-All connected users will see this:
486
-
487
-
488
-
489
-The broadcast command is great for notifying users of upcoming server downtime or other events.
490
-
491
-## Conclusion
492
-
493
-MeshCtrl is an essential tools in every MeshCentral administrator’s tool box. It allows administrators to automate various MeshCentral management tasks which can be useful for large scale management of many devices and users.
494
-
495
-## License
496
-
497
-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](https://www.apache.org/licenses/LICENSE-2.0)
docs/docs/meshrouter/images/Aspose.Words.954ea56c-626b-416a-8b2a-efde10ebd3a9.002.png
Binary files a/docs/docs/meshrouter/images/Aspose.Words.954ea56c-626b-416a-8b2a-efde10ebd3a9.002.png and /dev/null differ
docs/docs/meshrouter/images/custom_apps1.png
Binary files a/docs/docs/meshrouter/images/custom_apps1.png and /dev/null differ
docs/docs/meshrouter/images/custom_apps2.png
Binary files a/docs/docs/meshrouter/images/custom_apps2.png and /dev/null differ
docs/docs/meshrouter/images/custom_apps3.png
Binary files a/docs/docs/meshrouter/images/custom_apps3.png and /dev/null differ
docs/docs/meshrouter/images/download-link.png
Binary files a/docs/docs/meshrouter/images/download-link.png and /dev/null differ
docs/docs/meshrouter/images/login.png
Binary files a/docs/docs/meshrouter/images/login.png and /dev/null differ
docs/docs/meshrouter/images/port_maps.png
Binary files a/docs/docs/meshrouter/images/port_maps.png and /dev/null differ
docs/docs/meshrouter/images/port_maps2.png
Binary files a/docs/docs/meshrouter/images/port_maps2.png and /dev/null differ
docs/docs/meshrouter/images/port_maps3.png
Binary files a/docs/docs/meshrouter/images/port_maps3.png and /dev/null differ
docs/docs/meshrouter/index.md
deleted
-179
@@ -1,179 +0,0 @@
1
-# MeshCentral Router
2
-
3
-
4
-
5
-MeshCentral Router Guide [as .pdf](https://meshcentral.com/docs/MeshCentral2RouterUserGuide.pdf) [as .odt](../documents/MeshCentral%20Router%20User%20Guide%20v0.0.2.odt)
6
-
7
-## Video Walkthrough
8
-
9
-<div class="video-wrapper">
10
- <iframe width="320" height="180" src="https://www.youtube.com/embed/BubeVRmbCRM" frameborder="0" allowfullscreen></iframe>
11
-</div>
12
-
13
-## Abstract
14
-
15
-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 through a MeshCentral servers. This document should allow the user to Internet relay traffic through NAT routers and firewalls.
16
-
17
-## Introduction
18
-
19
-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 through the server and through 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.
20
-
21
-## Downloading
22
-
23
-MeshCentral router is a Windows application that comes built-into the MeshCentral server or can
24
-be downloaded at: <https://meshcentral.com/tools/MeshCentralRouter.exe>
25
-
26
-It’s probably best to use the MeshCentral router that comes with your version of the MeshCentral
27
-server as the two will likely be most compatible. A given MeshCentral Router version may not
28
-work with any MeshCentral server versions. On MeshCentral, you can download MeshCentral
29
-Router with this link:
30
-
31
-
32
-
33
-_The router link will only show up on Windows browsers._
34
-
35
-## Login
36
-
37
-MeshCentral router will need to login to your MeshCentral server just like any browser. You can
38
-do this by entering the server name and account username and password. Depending on your
39
-server and account situation, you may see some or all of the following screens.
40
-
41
-
42
-
43
-If the second factor authentication is required, MeshCentral Router does not support hardware
44
-keys (WebAuthn), but does support the YubiKey™ OTP.
45
-
46
-## Creating Port Maps
47
-
48
-Once logged in, you can start adding port maps using the “Add Map…” and “Add Relay Map…”
49
-buttons on the bottom right. You can then create a map and open the associated application
50
-using the “Open…” button and remote to port map using the “Remove” button.
51
-
52
-
53
-
54
-There are two different types of ports mappings. A normal port map and a relay port map. A
55
-normal port map will route packets to the selected destination computer that is running the mesh
56
-agent as shown here.
57
-
58
-
59
-
60
-A relay port map will route traffic through the server and through the remote agent to a target IP address
61
-on the remote agent’s network as shown here.
62
-
63
-
64
-
65
-Note that all traffic is encrypted using TLS from MeshCentral Router to the MeshCentral server
66
-and from the server to the MeshAgent. The server and the agent do have access the traffic so it’s
67
-recommended to use port mappings to tunnel data that is also encrypted for that end-to-end
68
-encryption is assured.
69
-
70
-## Custom Apps
71
-
72
-_Starting v1.0.21_
73
-
74
-
75
-
76
-
77
-
78
-
79
-
80
-## Command Line Arguments
81
-
82
-MeshCentral router can be run with command line arguments to make it quicker and easier to
83
-use. The arguments range from debugging to being able to quickly login and setting up port
84
-maps.
85
-
86
-```bash
87
--debug
88
-```
89
-
90
-Causes MeshCentral Router to generate a “debug.log” dump file that can be useful for
91
-debugging.
92
-
93
-```bash
94
--host:<hostname>
95
--user:<username>
96
--pass:<password>
97
--ignorecert
98
-```
99
-
100
-This set of command line arguments make logging into the MeshCentral server easier. Note that
101
-specifying the password using a command line argument may not be secure as the command
102
-shell can record the password in the command history. The “ignorecert” argument is not
103
-recommended as it’s going to cause MeshCentral Router to ignore untrusted server certificates.
104
-This should only be used for debugging.
105
-
106
-```bash
107
--map:<protocol>:<localport>:<computername>:<app>:<remoteport>
108
-```
109
-
110
-The “map” argument will automatically create a network map once MeshCentral Router is logged
111
-In. The protocol must be “TCP” or “UDP, the local port can be 0 for any. The computer name is
112
-the server-side name of the computer, if many computers have the same one, one of them will be
113
-selected. The app can be empty for a custom application, or can be “HTTP”, “HTTPS”, “RDP”,
114
-“PuTTY” or “WinSCP”. For the UDP protocol, no apps are currently supported so it should be left
115
-blank. For example you can use:
116
-
117
-```bash
118
--map:TCP:0:"MyComputer":HTTP:80
119
--map:UDP:1235:"MyComputer"::1234
120
-```
121
-
122
-The first example will map a random local port to port 80 of “MyComputer” and is expected for
123
-use with HTTP traffic. The second example maps local UDP port 1235 to port 1234 on
124
-“MyComputer”. It’s best for the computer name to be in quotes.
125
-
126
-In addition to port mapping, you can also setup relay maps where a remote computer is used as a
127
-traffic relay like this:
128
-
129
-```bash
130
--relaymap:<protocol>:<localport>:<computername>
131
- :<app>:<remoteip>:<remoteport>
132
-```
133
-
134
-This will relays a local port to through the server and through a remote agent to a target IP address and
135
-port. For example:
136
-
137
-```bash
138
--relaymap:TCP:555:"MyComputer":HTTP:192.168.1.1:80
139
-```
140
-
141
-This will relay local port 555 to a 192.168.1.1:80 for HTTP traffic. A typical use of this is to be able
142
-to remotely configure a home router from anywhere on the Internet.
143
-
144
-```bash
145
--all
146
-```
147
-
148
-The “all” switch will bind local ports to all network interfaces so that other computers on the
149
-network can use the port maps provided by MeshCentral Router. By default, local ports will be
150
-bound to the loopback interface so that only local application can use the port mappings.
151
-
152
-```bash
153
--tray
154
-```
155
-
156
-The “tray” switch will place MeshCentral Router on the Windows system tray instead of the
157
-normal application bar.
158
-
159
-## MeshCentral Router with SAML or OAuth
160
-
161
-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
162
-
163
-1. Download MCR and run it.
164
-2. In the first dialog box, there will be an "Install..." button to setup MeshCentral router with the "mcrouter://" protocol in your system registry.
165
-3. Once done, close MCR.
166
-4. Now log into the web UI of your MeshCentral server. Go in the bottom of the "My Devices" tab, hit the "Router" link and hit "Launch MeshCentral Router".
167
-5. This will launch the router and connect directly to your server using a login cookie.
168
-
169
-!!!note
170
- 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.
171
-
172
-## Conclusion
173
-
174
-MeshCentral Router is a free, open source tool for routing TCP and UDP traffic over the internet. It’s a powerful as it allows for any traffic to go through NAT routers and firewalls while being encrypted using TLS.
175
-
176
-## License
177
-
178
-MeshCentral, MeshCentral Router and this document are all opens source and licensed using
179
-Apache 2.0, the full license can be found at <https://www.apache.org/licenses/LICENSE-2.0>.
docs/docs/messaging/images/MC2-CallMeBot3.png
Binary files a/docs/docs/messaging/images/MC2-CallMeBot3.png and /dev/null differ
docs/docs/messaging/images/MC2-Discord1.png
Binary files a/docs/docs/messaging/images/MC2-Discord1.png and /dev/null differ
docs/docs/messaging/images/MC2-Ntfy1.png
Binary files a/docs/docs/messaging/images/MC2-Ntfy1.png and /dev/null differ
docs/docs/messaging/images/MC2-Pushover1.png
Binary files a/docs/docs/messaging/images/MC2-Pushover1.png and /dev/null differ
docs/docs/messaging/images/MC2-Pushover2.png
Binary files a/docs/docs/messaging/images/MC2-Pushover2.png and /dev/null differ
docs/docs/messaging/images/MC2-Telegram1.png
Binary files a/docs/docs/messaging/images/MC2-Telegram1.png and /dev/null differ
docs/docs/messaging/images/MC2-Telegram2.png
Binary files a/docs/docs/messaging/images/MC2-Telegram2.png and /dev/null differ
docs/docs/messaging/images/MC2-Telegram3.png
Binary files a/docs/docs/messaging/images/MC2-Telegram3.png and /dev/null differ
docs/docs/messaging/images/MC2-Telegram4.png
Binary files a/docs/docs/messaging/images/MC2-Telegram4.png and /dev/null differ
docs/docs/messaging/images/MC2-Telegram5.png
Binary files a/docs/docs/messaging/images/MC2-Telegram5.png and /dev/null differ
docs/docs/messaging/index.md
deleted
-291
@@ -1,291 +0,0 @@
1
-# Messaging
2
-
3
-## Table of Contents
4
-
5
-[Introduction](#introduction)
6
-[Telegram Setup](#telegram-setup)
7
-[Discord Setup](#discord-setup)
8
-[XMPP Setup](#xmpp-setup)
9
-[CallMeBot Setup](#callmebot-setup)
10
-[Pushover Setup](#pushover-setup)
11
-[ntfy Setup](#ntfy-setup)
12
-[Zulip Setup](#zulip-setup)
13
-[User Setup](#user-setup)
14
-[Administrator Management](#administrator-management)
15
-[Two-Factor Authentication](#two-factor-authentication)
16
-
17
-## Introduction
18
-
19
-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.
20
-
21
-## Telegram Setup
22
-
23
-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:
24
-
25
-```json
26
-{
27
- "settings": {
28
- "Cert": "devbox.mesh.meshcentral.com",
29
- },
30
- "domains": {
31
- "": {
32
- "title": "My Server"
33
- }
34
- },
35
- "messaging": {
36
- "telegram": {
37
- "apiid": 0,
38
- "apihash": "00000000000000000000000",
39
- "bottoken": "00000000:aaaaaaaaaaaaaaaaaaaaaaaa"
40
- }
41
- }
42
-}
43
-```
44
-
45
-Note the "messaging" section in the config.json. For Telegram user login, it looks like this:
46
-
47
-```json
48
-{
49
- "messaging": {
50
- "telegram": {
51
- "apiid": 0,
52
- "apihash": "00000000000000000000000",
53
- "session": "aaaaaaaaaaaaaaaaaaaaaaa"
54
- }
55
- }
56
-}
57
-```
58
-
59
-User login makes use of "session", while bot login uses "bottoken". One way to get started with the setup is to run `node node_modules/meshcentral --setuptelegram` and follow the instructions.
60
-
61
-
62
-
63
-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:
64
-
65
-```
66
-MeshCentral HTTP redirection server running on port 80.
67
-MeshCentral v1.0.87, Hybrid (LAN + WAN) mode.
68
-MeshCentral Intel(R) AMT server running on central.mesh.meshcentral.com:4433.
69
-MeshCentral HTTPS server running on central.mesh.meshcentral.com:443.
70
-MeshCentral HTTPS relay server running on relay1.mesh.meshcentral.com:443.
71
-MeshCentral Telegram client is bot connected.
72
-```
73
-
74
-Note the last line, indicating it's connected as a bot. If you wish to use Telegram with a proxy, here are the possible Telegram settings. You can use the proxy settings for both user or bot login modes.
75
-
76
-```
77
-{
78
- "messaging": {
79
- "telegram": {
80
- "apiid": 0,
81
- "apihash": "00000000000000000000000",
82
- "session": "aaaaaaaaaaaaaaaaaaaaaaa",
83
- "useWSS": false, // Important. Most proxies cannot use SSL.
84
- "proxy": {
85
- "ip": "123.123.123.123", // Proxy host (IP or hostname)
86
- "port": 123, // Proxy port
87
- "MTProxy": false, // Whether it's an MTProxy or a normal Socks one
88
- "secret": "00000000000000000000000000000000", // If used MTProxy then you need to provide a secret (or zeros).
89
- "socksType": 5, // If used Socks you can choose 4 or 5.
90
- "timeout": 2 // Timeout (in seconds) for connection,
91
- }
92
- }
93
- }
94
-}
95
-```
96
-
97
-## Discord Setup
98
-
99
-For Discord integration, you need to provide MeshCentral with a bot application token so that MeshCentral can login and send notifications to users. The Discord bot will need to be joined to one or more Discord servers and users will need to join at at least one Discord server that is in common with the bot to receive notifications.
100
-
101
-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](https://www.freecodecamp.org/news/create-a-discord-bot-with-javascript-nodejs/). 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.
102
-
103
-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.
104
-
105
-
106
-
107
-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:
108
-
109
-```json
110
-{
111
- "messaging": {
112
- "discord": {
113
- "serverurl": "https://discord.gg/xxxxxxxxx",
114
- "token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
115
- }
116
- }
117
-}
118
-```
119
-
120
-Once users will need to join the same Discord server as the bot, the optional "serverurl" can be used to give the users a URL link to join the server, this can be a server invitation link or some other URL with instructions.
121
-
122
-## XMPP Setup
123
-
124
-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.
125
-
126
-```json
127
-{
128
- "messaging": {
129
- "xmpp": {
130
- "service": "xmppserver.com",
131
- "credentials": {
132
- "username": "username",
133
- "password": "password"
134
- }
135
- }
136
- }
137
-}
138
-```
139
-
140
-An easy way to get setup with XMPP is to create a free account with [chatterboxtown.us](https://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.
141
-
142
-## CallMeBot Setup
143
-
144
-
145
-
146
-[CallMeBot](https://www.callmebot.com/) 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:
147
-
148
-```json
149
-{
150
- "messaging": {
151
- "callmebot": true
152
- }
153
-}
154
-```
155
-
156
-Once enabled, users see the new "CallMeBot" option when trying to enable messaging in MeshCentral. They will need to follow specific instructions to enable CallMeBot to send notifications to their messaging application.
157
-
158
- - [Signal Messenger](https://www.callmebot.com/blog/free-api-signal-send-messages/)
159
- - [Whatsapp](https://www.callmebot.com/blog/free-api-whatsapp-messages/)
160
- - [Facebook Messenger](https://www.callmebot.com/blog/free-api-facebook-messenger/)
161
- - [Telegram](https://www.callmebot.com/blog/telegram-text-messages/)
162
-
163
-Once the user has enabled their account, they can cut & paste the CallMeBot URI into MeshCentral to validate their account.
164
-
165
-## Pushover Setup
166
-
167
-[Pushover](https://pushover.net/) 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:
168
-
169
-
170
-
171
-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:
172
-
173
-```json
174
-{
175
- "messaging": {
176
- "pushover": {
177
- "token": "xxxxxxxxxxxxxxxxxxxxx"
178
- }
179
- }
180
-}
181
-```
182
-
183
-Once setup, the server will offer users the "Pushover" option when setting up messaging. Users will need to copy the Pushover user key into the dialog box to verify notifications are correct.
184
-
185
-
186
-
187
-## ntfy setup
188
-
189
-[ntfy](https://ntfy.sh/) is a completely free notification service. You can enable the ntfy integration with the following config.json section:
190
-
191
-```json
192
-{
193
- "messaging": {
194
- "ntfy": true
195
- }
196
-}
197
-```
198
-No setup is reqired to enable this. When using ntfy, make sure you use a suffisently random topic name so that others can't guess the name and subscribe to it to receive your messages.
199
-
200
-For [self-hosting your own ntfy server](https://ntfy.sh/docs/install/) with [ACL support](https://ntfy.sh/docs/config/#access-control)
201
-
202
-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
203
-
204
-```json
205
-{
206
- "messaging": {
207
- "ntfy": {
208
- "host": "myntfyserver.com",
209
- "userurl": "https://myntfyserver.com/userhelp",
210
- "authorization": "Basic cGhpbDpteXBhc3M="
211
- }
212
- }
213
-}
214
-```
215
-
216
-
217
-
218
-## Zulip setup
219
-
220
-You can enable the MeshCentral [Zulip](https://zulip.com/) integration with the following config.json section:
221
-
222
-```json
223
-{
224
- "messaging": {
225
- "zulip": {
226
- "site": "https://api.zulip.com",
227
- "email": "your-bot@zulip.com",
228
- "api_key": "your_32_character_api_key"
229
- }
230
- }
231
-}
232
-```
233
-
234
-## Slack setup
235
-
236
-[Slack](https://slack.com/) integration is achieved by the use of Incoming Webhooks.
237
-You can get started by following the Slack guide [here](https://api.slack.com/messaging/webhooks) and getting your URL
238
-
239
-Once you have your incoming webhooks url, You can enable the [Slack](https://slack.com/) integration with the following config.json section
240
-
241
-```json
242
-{
243
- "messaging": {
244
- "slack": true
245
- }
246
-}
247
-```
248
-
249
-## User Setup
250
-
251
-Once one or more messaging systems are setup with MeshCentral, users will be able to register their handle and verify that they own that account by typing in a 6 digit code.
252
-
253
-
254
-
255
-This verification is necessary so that MeshCentral does not send notifications to incorrect messaging accounts.
256
-
257
-## Administrator Management
258
-
259
-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.
260
-
261
-
262
-
263
-## Two-Factor Authentication
264
-
265
-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.
266
-
267
-
268
-
269
-As an administrator you can turn off use of messaging for 2FA using the following settings in the config.json:
270
-
271
-```json
272
-{
273
- "settings": {
274
- "Cert": "devbox.mesh.meshcentral.com",
275
- },
276
- "domains": {
277
- "": {
278
- "title": "My Server",
279
- "passwordRequirements": {
280
- "msg2factor": false
281
- }
282
- }
283
- }
284
-}
285
-```
286
-
287
-Notice the `msg2factor` is set to false. In this case, messaging can still be used for user notifications, but will not be offered as a 2FA option.
288
-
289
-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:
290
-
291
-
docs/docs/other/adfs_sso_guide.md
deleted
-90
@@ -1,90 +0,0 @@
1
-# ADFS SSO Guide
2
-
3
-## 📋 Assumptions
4
-
5
-The following guide was built under the assumptions that :
6
-
7
-1. *ADFS 4.0 running on Server 2016 using Active Directory*
8
-
9
-2. *Main ADFS setup already completed / working. SSL certs installed and port forwarded as expected.*
10
-
11
-The guide was built to deal specifically with adding mesh as a Relying Party. I’m far from an ADFS expert and some configurations may not be needed. Most of this was built by reading the code and taking guesses as to the needed values.
12
-
13
-## 📘 Guide
14
-
15
-As with anything SSO, you need 2 pieces – the IDP setup (in this case ADFS) and the SP setup (in this case Mesh).
16
-
17
-### Mesh Setup
18
-
19
-Add the following to your mesh config file in the domains part :
20
-
21
-
22
-
23
-- `Callback URL` :
24
-
25
- > Should be the FQDN for your Mesh Server, ending with /auth-saml-callback
26
-
27
-- `Entity ID` :
28
-
29
- > 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.
30
-
31
-- `IDP URL`:
32
-
33
- > This is the URL to ADFS. Ends with /adfs/ls unless you did something very weird in ADFS.
34
-
35
-- `Cert`:
36
-
37
- > 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 :
38
- ```bash
39
- openssl x509 -in mycert.crt -out mycert.pem -outform PEM
40
- ```
41
-
42
-Save the config and restart the mesh server.
43
-
44
-### Windows Server Configuration
45
-
46
-ADFS setup (in pictures) :
47
-
48
-Relying Party Trust -> New Relying Party Trust
49
-
50
-
51
-
52
-
53
-
54
-
55
-
56
-
57
-
58
-
59
-
60
-
61
-
62
-
63
-
64
-
65
-
66
-
67
-
68
-Edit the new “Relying Party Trust” Properties:
69
-
70
-
71
-
72
-
73
-
74
-Then it’s time to add Claims…
75
-
76
-
77
-
78
-
79
-
80
-
81
-
82
-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.
83
-
84
-Add another rule:
85
-
86
-
87
-
88
-
89
-
90
-For all fields, select from the dropdowns
docs/docs/other/images/adfs_sso2022-05-16-23-24-54.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-24-54.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-25-48.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-25-48.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-26-01.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-26-01.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-26-47.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-26-47.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-26-56.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-26-56.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-03.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-03.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-09.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-09.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-16.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-16.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-22.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-22.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-28.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-28.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-41.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-41.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-27-51.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-27-51.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-28-09.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-28-09.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-28-15.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-28-15.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-28-21.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-28-21.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-28-41.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-28-41.png and /dev/null differ
docs/docs/other/images/adfs_sso2022-05-16-23-28-48.png
Binary files a/docs/docs/other/images/adfs_sso2022-05-16-23-28-48.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-00-58-46.png
Binary files a/docs/docs/other/images/sat2022-05-17-00-58-46.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-00-59-21.png
Binary files a/docs/docs/other/images/sat2022-05-17-00-59-21.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-00-22.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-00-22.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-00-33.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-00-33.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-00-45.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-00-45.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-00-59.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-00-59.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-01-13.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-01-13.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-01-52.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-01-52.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-02-04.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-02-04.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-02-10.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-02-10.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-02-39.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-02-39.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-03-30.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-03-30.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-03-43.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-03-43.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-03-56.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-03-56.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-04-11.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-04-11.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-04-22.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-04-22.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-05-15.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-05-15.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-05-22.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-05-22.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-05-28.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-05-28.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-05-51.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-05-51.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-06-01.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-06-01.png and /dev/null differ
docs/docs/other/images/sat2022-05-17-01-06-10.png
Binary files a/docs/docs/other/images/sat2022-05-17-01-06-10.png and /dev/null differ
docs/docs/other/meshcentral_satellite.md
deleted
-179
@@ -1,179 +0,0 @@
1
-# MeshCentral Satellite
2
-
3
-### **_🚀 Coming Soon!_**
4
-
5
-
6
-
7
-
8
-## 🧾 Abstract
9
-
10
-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.
11
-
12
-## 📘 Introduction
13
-
14
-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.
15
-
16
-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.
17
-
18
-
19
-
20
-Currently, MeshCentral Satellite can perform four operations on behalf of the MeshCentral server :
21
-
22
-- **Create an Intel AMT domain computer**.
23
-- **Remove an Intel AMT domain computer**.
24
-- **Issue a certificate for Intel AMT**.
25
-- **Revoke an Intel AMT certificate**.
26
-
27
-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.
28
-
29
-## 🧰 Installation and Configuration
30
-
31
-Start by creating an empty folder on a computer that is part of the domain you need to interact with. For example, create a `c:\MeshCentralSatellite` then copy `MeshCentralSatellite.exe` into that folder. You can find that executable in the `node_modules/meshcentral/agents` folder of your server. If it’s not present, update your server to the latest version and look again.
32
-
33
-Once started you should see something this:
34
-
35
-
36
-
37
-Go in the file menu and select “Settings…”, this is where all of the MeshCentral Satellite setting are. It includes sections to connect to your MeshCentral server. Security groups you want device to join and Certificate settings.
38
-
39
-
40
-
41
-First, enter your MeshCentral server hostname and username and password. MeshCentral Satellite can’t use two-factor authentication (2FA) so you need to create a user account in MeshCentral for Satellite or you can create a login token in the “My Account” section of MeshCentral with an unlimited expire time and cut & paste the username and password given into MeshCentral Satellite.
42
-
43
-
44
-
45
-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.
46
-
47
-
48
-
49
-The `Device Name` has two options, `Operating System Name` or `Node Identifier`. If you opt for `Operating System Name`, Intel AMT devices will show as, for example, `iME-ComputerName` in the list of domain computers. If `node identifier` is used, Intel AMT devices will look like `iME-xxxxxxxxxxx` where xxx is the start of the MeshCentral node identifier for this device.
50
-
51
-Using the node identifier is more secure as it can’t easily be replicate by any other device. The operating system name would be impersonated by another device causing various security issues.
52
-
53
-The security groups section will list any security groups created until the `Computers` section of the domain controller. Checking one or more of these security groups will automatically going new Intel AMT devices to these groups.
54
-
55
-
56
-
57
-Lastly, we have the certificate authority and certificate settings. If a certificate authority needs to used, enter the name of the CA which is in the format `<computername>\<caname>` you can then hit the check box next to the name and select the certificate template to use.
58
-
59
-
60
-
61
-For certificate configuration, you can leave it as-is with `SAM Account Name` and the common name and all alternative names selected.
62
-
63
-Once done, you can hit ok. The settings will be saved in a file called `config.txt` in plain text in the same folder as `MeshCentralSatellite.exe`. Make sure not to grant access to this file to anyone not authorized to do so as it will have the MeshCentral login username and password.
64
-
65
-Once done, select `Local Connect` the `Files` menu to connect to the MeshCentral server.
66
-
67
-
68
-
69
-
70
-
71
-MeshCentral Satellite should be connected and ready to receive commands from the server.
72
-
73
-## ✅ Checking the connection
74
-
75
-In order to make sure the server correctly recognizes the MeshCentral Satellite connection, you can go to the server console and type `usersession`. The Satellite session should be marked.
76
-
77
-
78
-
79
-Currently, you should only have a single satellite session per user. In the future, multiple sessions could be supported for redundancy.
80
-
81
-## 🔧 Configuring Intel® AMT 802.1x
82
-
83
-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.
84
-
85
-Here is an example of an 802.1x EAP-TLS profile that will require that Intel AMT be issued a certificate :
86
-
87
-```json
88
- "AmtManager": {
89
- "802.1x": {
90
- "AuthenticationProtocol": "EAP-TLS",
91
- "SatelliteCredentials": "admin"
92
- },
93
- "WifiProfiles": [
94
- {
95
- "ssid": "Network-8021x",
96
- "authentication": "wpa2-802.1x",
97
- "encryption": "ccmp-aes"
98
- }
99
- ]
100
- }
101
-```
102
-
103
-In this following example, MSCHAPv2 is used and so, MeshCentral Satellite will need to generate a random password, save it in the active directory and send the password back to MeshCentral for Intel AMT configuration:
104
-
105
-```json
106
- "AmtManager": {
107
- "802.1x": {
108
- "AuthenticationProtocol": "PEAPv0/EAP-MSCHAPv2",
109
- "SatelliteCredentials": "admin"
110
- },
111
- "WifiProfiles": [
112
- {
113
- "ssid": "Network-8021x",
114
- "authentication": "wpa2-802.1x",
115
- "encryption": "ccmp-aes"
116
- }
117
- ]
118
- }
119
-```
120
-
121
-The second example does not require that a certificate authority be setup, the first example does. In both cases, the WIFI profile is set to `wpa2-802.1x` and so, the 802.1x profile will be setup for both the Intel AMT wired interface and the specified WIFI profile for wireless.
122
-
123
-Note that is both examples, `SatelliteCredentials` indicates the account name that MeshCentral Satellite will be connected on. In our case, we used the `admin` account that matches the account configuration we used in sections 3 and 4.
124
-
125
-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.
126
-
127
-## 🧾 Computer and certificate operations
128
-
129
-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.
130
-
131
-
132
-
133
-Computers connecting to this device group will automatically be setup with the new 802.1x and WIFI profile, but you can go in an agent console and type `amtconfig` to force the check of the Intel AMT configuration. In our case, it looks like this :
134
-
135
-
136
-
137
-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:
138
-
139
-
140
-
141
-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:
142
-
143
-
144
-
145
-The new Intel AMT device was added to the domain along with the Intel AMT version and node identifier in the description. If `Node Identifier` was selected as the computer name in MeshCentral Satellite settings, the friendly name would be in the description and the node identifier would be used as the device name.
146
-
147
-Finally, it’s worth taking a look at how Intel AMT was configured before and after this operation. Before setting up the 802.1x profile, Intel AMT looked like this :
148
-
149
-
150
-
151
-
152
-
153
-Note that there is no 802.1x profiles or WIFI profiles. After the new configuration, MeshCommander shows Intel AMT looking like this :
154
-
155
-
156
-
157
-
158
-
159
-There are now two new certificates in the `Security` tab. One if the root of the domain CA, the other is the certificate assigned to the Intel AMT device by the CA. You also see the WIFI 802.1x profile. In this example, the device did not have a wired network interface, but if it did, 802.1x would also be setup for the wired interface.
160
-
161
-## 🖥️ Running as a Background Service
162
-
163
-MeshCentral Satellite can be run as a background service. This is useful when running for lang periods on a domain server. You can use the `Service` menu in MeshCentral Satellite to install, start, stop and uninstall the Windows service. Make sure to come and run “MeshCentralSatellite.exe” from the correct location you want to install the Windows Service from.
164
-
165
-
166
-
167
-Since MeshCentral Satellite need to have domain rights to add and remove computer objects from the active directory and to have certificate authority (CA) rights, you may want to install the service, go in the service manager and change the `Log On` account to one with the proper rights.
168
-
169
-
170
-
171
-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.
172
-
173
-
174
-
175
-The lines starting with `Service:` are coming from the background service. At this point, you can close the local application and the service will keep running in the background.
176
-
177
-## License
178
-
179
-MeshCentral, MeshCentral Satellite and this document are both opens source and licensed using Apache 2.0, the full license can be found at [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
\ No newline at end of file
docs/docs/stylesheets/extra.css
deleted
-24
@@ -1,24 +0,0 @@
1
-.md-grid {
2
- max-width: 80%;
3
-}
4
-
5
-img {
6
- height: auto;
7
- width: auto;
8
- border: none;
9
- border-radius: 10px;
10
- transition: transform ease-in-out 0.3s;
11
-}
12
-img:hover {
13
- transform: scale(1.025); /* Slightly enlarges on hover */
14
-}
15
-
16
-.video-wrapper iframe {
17
- width: 100%; /* Ratio 16:9 */
18
- height: 600px; /* Ratio 16:9 */
19
- border-radius: 10px; /* Rounded Corners */
20
- transition: transform ease-in-out 0.3s;
21
-}
22
-.video-wrapper:hover iframe {
23
- transform: scale(1.025); /* Slightly enlarges on hover */
24
-}
\ No newline at end of file
docs/mkdocs.yml
deleted
-108
@@ -1,108 +0,0 @@
1
-site_name: "MeshCentral Documentation"
2
-
3
-nav:
4
- - Home:
5
- - 'Abstract': 'index.md'
6
-
7
- - 'Install':
8
- - 'Abstract': 'install/abstract.md'
9
- - 'Quickstart': 'install/quickstart.md'
10
- - 'Installation Guides':
11
- - 'Abstract': 'install/abstract.md'
12
- - 'Advanced': 'install/advanced.md'
13
- - 'Container (Docker)': 'install/container.md'
14
- - 'Windows': 'install/windows.md'
15
- - 'Databases':
16
- - 'MongoDB': 'install/database/mongodb.md'
17
- - 'PostgreSQL': 'install/database/postgresql.md'
18
- - 'MariaDB/MySQL': 'install/database/mariadb.md'
19
- - 'Local Databases': 'install/database/local.md'
20
- - 'Security':
21
- - 'Crowdsec': 'install/security/crowdsec.md'
22
- - 'Secure Installation': 'install/security/secure.md'
23
-
24
- - 'MeshCentral':
25
- - 'MeshCentral Guide': 'meshcentral/'
26
- - 'All Configuration Options': 'meshcentral/config.md'
27
- - 'SSL/TLS': 'meshcentral/SSLnletsencrypt.md'
28
- - 'Agent Information': 'meshcentral/agents.md'
29
- - 'Assistant': 'meshcentral/assistant.md'
30
- - 'Code Signing': 'meshcentral/codesigning.md'
31
- - 'Debugging': 'meshcentral/debugging.md'
32
- - 'Device Tabs': 'meshcentral/devicetabs.md'
33
- - 'Plugins': 'meshcentral/plugins.md'
34
- - 'Security': 'meshcentral/security.md'
35
- - 'Tokens': 'meshcentral/tokens.md'
36
- - 'FAQ': 'meshcentral/faq.md'
37
- - 'Tips n Tricks': 'meshcentral/tipsntricks.md'
38
- - 'Messaging': 'messaging/'
39
- - 'Customization': 'meshcentral/customization.md'
40
- - 'OpenID Connect Strategy (OIDC)': 'meshcentral/openidConnectStrategy.md'
41
-
42
- - 'Submodules and Features':
43
- - 'MeshCmd': 'meshcmd/'
44
- - 'MeshCtrl': 'meshctrl/'
45
- - 'Mesh Router': 'meshrouter/'
46
- - 'Intel AMT': 'intelamt/'
47
-
48
- - 'How to Contribute': 'how-to-contribute/'
49
-
50
- - 'Design and Architecture': 'design/'
51
-
52
- - 'Other':
53
- - 'other/adfs_sso_guide.md'
54
- - 'other/meshcentral_satellite.md'
55
-
56
-site_description: "A remote monitoring and management tool"
57
-site_author: "Ylianst and contributors"
58
-site_url: "https://ylianst.github.io/MeshCentral/"
59
-
60
-dev_addr: "0.0.0.0:8010"
61
-
62
-# Repository
63
-repo_name: "Ylianst/MeshCentral"
64
-repo_url: "https://github.com/Ylianst/MeshCentral"
65
-
66
-theme:
67
- name: "material"
68
- logo: "images/favicon.ico"
69
- favicon: "images/favicon.ico"
70
- language: en
71
- locale: en
72
- include_sidebar: false
73
- palette:
74
- - scheme: default # Palette toggle for dark mode
75
- toggle:
76
- icon: material/brightness-7
77
- name: Switch to light mode
78
- - scheme: slate # Palette toggle for light mode
79
- toggle:
80
- icon: material/brightness-4
81
- name: Switch to dark mode
82
- features:
83
- - content.code.copy
84
- - content.code.select
85
- - navigation.tabs
86
- - navigation.top
87
- - navigation.sections
88
- - navigation.instant
89
- - search.suggest
90
-extra_css:
91
- - stylesheets/extra.css
92
-extra:
93
- generator: false
94
-plugins:
95
- - search
96
- - print-site
97
-
98
-markdown_extensions:
99
- - pymdownx.emoji:
100
- emoji_index: !!python/name:material.extensions.emoji.twemoji
101
- emoji_generator: !!python/name:material.extensions.emoji.to_svg
102
- - pymdownx.superfences
103
- - pymdownx.tabbed:
104
- alternate_style: true
105
- - admonition
106
- - tables
107
-
108
-# to-do later on down the line; migrate to zensical.toml in an ideal world
\ No newline at end of file
docs/presentations/MeshCentral - 0009 - Desktop Multiplexer.pptx
Binary files a/docs/presentations/MeshCentral - 0009 - Desktop Multiplexer.pptx and /dev/null differ
docs/presentations/MeshCentral - 0027 - Overview Presentation.pptx
Binary files a/docs/presentations/MeshCentral - 0027 - Overview Presentation.pptx and /dev/null differ
docs/presentations/MeshCentral - 0028 - Multi-domain Server.pptx
Binary files a/docs/presentations/MeshCentral - 0028 - Multi-domain Server.pptx and /dev/null differ
docs/presentations/MeshCentral - 0029 - Technical - A short history of MeshCentral.pptx
Binary files a/docs/presentations/MeshCentral - 0029 - Technical - A short history of MeshCentral.pptx and /dev/null differ
docs/presentations/MeshCentral - 0030 - Technical - REST vs WebSocket.pptx
Binary files a/docs/presentations/MeshCentral - 0030 - Technical - REST vs WebSocket.pptx and /dev/null differ
docs/presentations/MeshCentral - 0031 - Technical - Agent Updates.pptx
Binary files a/docs/presentations/MeshCentral - 0031 - Technical - Agent Updates.pptx and /dev/null differ
docs/presentations/MeshCentral - 0037 - Technical - Agent Tunnels(1).pptx
Binary files a/docs/presentations/MeshCentral - 0037 - Technical - Agent Tunnels(1).pptx and /dev/null differ
docs/presentations/MeshCentral - 0037 - Technical - Agent Tunnels.pptx
docs/presentations/MeshCentral - 0038 - Server & DB Migration.pptx
Binary files a/docs/presentations/MeshCentral - 0038 - Server & DB Migration.pptx and /dev/null differ
docs/presentations/MeshCentral - 0039 - Intel AMT Configuration and CIRA.pptx
Binary files a/docs/presentations/MeshCentral - 0039 - Intel AMT Configuration and CIRA.pptx and /dev/null differ
docs/presentations/MeshCentral - 0040 - Technical - Inter-User Messaging.pptx
Binary files a/docs/presentations/MeshCentral - 0040 - Technical - Inter-User Messaging.pptx and /dev/null differ
docs/presentations/MeshCentral - 0042 - Technical - Web Applications.pptx
Binary files a/docs/presentations/MeshCentral - 0042 - Technical - Web Applications.pptx and /dev/null differ
docs/presentations/MeshCentral - 0043 - Let's Encrypt.pptx
Binary files a/docs/presentations/MeshCentral - 0043 - Let's Encrypt.pptx and /dev/null differ
docs/presentations/MeshCentral - 0044 - JumpCloud.pptx
Binary files a/docs/presentations/MeshCentral - 0044 - JumpCloud.pptx and /dev/null differ
docs/presentations/MeshCentral - 0045 - Local Device Management.pptx
Binary files a/docs/presentations/MeshCentral - 0045 - Local Device Management.pptx and /dev/null differ
docs/presentations/MeshCentral - 0047 - MongoDB.pptx
Binary files a/docs/presentations/MeshCentral - 0047 - MongoDB.pptx and /dev/null differ
docs/presentations/MeshCentral - 0048 - IP-KVM Support.pptx
Binary files a/docs/presentations/MeshCentral - 0048 - IP-KVM Support.pptx and /dev/null differ
docs/presentations/MeshCentral - 0049 - Web Power Switch.pptx
Binary files a/docs/presentations/MeshCentral - 0049 - Web Power Switch.pptx and /dev/null differ
docs/presentations/MeshCentral - 0050 - 2021 in Review.pptx
Binary files a/docs/presentations/MeshCentral - 0050 - 2021 in Review.pptx and /dev/null differ
docs/presentations/MeshCentral - 0054 - Public Server.pptx
Binary files a/docs/presentations/MeshCentral - 0054 - Public Server.pptx and /dev/null differ
docs/presentations/MeshCentral - 0057 - Technical - MeshCore & MeshCmd.pptx
Binary files a/docs/presentations/MeshCentral - 0057 - Technical - MeshCore & MeshCmd.pptx and /dev/null differ
docs/presentations/MeshCentral - 0063 - Port Aliasing.pptx
Binary files a/docs/presentations/MeshCentral - 0063 - Port Aliasing.pptx and /dev/null differ
docs/presentations/MeshCentral - 0064 - April Fools Joke - Car Automation Mesh.pptx
Binary files a/docs/presentations/MeshCentral - 0064 - April Fools Joke - Car Automation Mesh.pptx and /dev/null differ
docs/presentations/MeshCentral - 0066 - Basic AMT 802.1x with JumpCloud.pptx
Binary files a/docs/presentations/MeshCentral - 0066 - Basic AMT 802.1x with JumpCloud.pptx and /dev/null differ
docs/presentations/MeshCentral - 0067 - Satellite & Advanced AMT 802.1x.pptx
Binary files a/docs/presentations/MeshCentral - 0067 - Satellite & Advanced AMT 802.1x.pptx and /dev/null differ
docs/presentations/MeshCentral - 0068 - Local Device Management thru a Agent Relay.pptx
Binary files a/docs/presentations/MeshCentral - 0068 - Local Device Management thru a Agent Relay.pptx and /dev/null differ
docs/presentations/MeshCentral - 0070 - Intel AMT System Defense.pptx
Binary files a/docs/presentations/MeshCentral - 0070 - Intel AMT System Defense.pptx and /dev/null differ
docs/presentations/MeshCentral - 0075 - Intel AMT MEI and LMS.pptx
Binary files a/docs/presentations/MeshCentral - 0075 - Intel AMT MEI and LMS.pptx and /dev/null differ
docs/presentations/MeshCentral - 0077 - History of Intel AMT.pptx
Binary files a/docs/presentations/MeshCentral - 0077 - History of Intel AMT.pptx and /dev/null differ
docs/presentations/MeshCentral - 0078 - Intel AMT Activation.pptx
Binary files a/docs/presentations/MeshCentral - 0078 - Intel AMT Activation.pptx and /dev/null differ
docs/presentations/MeshCentral - 0078 - Web Relay.pptx
Binary files a/docs/presentations/MeshCentral - 0078 - Web Relay.pptx and /dev/null differ
docs/presentations/MeshCentral - 0079 - Intel AMT Activation.pptx
Binary files a/docs/presentations/MeshCentral - 0079 - Intel AMT Activation.pptx and /dev/null differ
docs/presentations/MeshCentral - 0080 - Web Relay with DNS.pptx
Binary files a/docs/presentations/MeshCentral - 0080 - Web Relay with DNS.pptx and /dev/null differ
docs/presentations/MeshCentral - 0081 - CrowdSec.pptx
Binary files a/docs/presentations/MeshCentral - 0081 - CrowdSec.pptx and /dev/null differ
docs/presentations/MeshCentral - 0082 - New Account CAPTCHA.pptx
Binary files a/docs/presentations/MeshCentral - 0082 - New Account CAPTCHA.pptx and /dev/null differ
docs/presentations/MeshCentral - 0083 - Yubikey OTP.pptx
Binary files a/docs/presentations/MeshCentral - 0083 - Yubikey OTP.pptx and /dev/null differ
docs/presentations/MeshCentral - 0084 - LDAP Integration.pptx
Binary files a/docs/presentations/MeshCentral - 0084 - LDAP Integration.pptx and /dev/null differ
docs/presentations/MeshCentral - 0087 - AceBase Database.pptx
Binary files a/docs/presentations/MeshCentral - 0087 - AceBase Database.pptx and /dev/null differ
docs/presentations/MeshCentral - 0088 - SQLite Database.pptx
Binary files a/docs/presentations/MeshCentral - 0088 - SQLite Database.pptx and /dev/null differ
docs/presentations/MeshCentral - 0091 - SessionKey.pptx
Binary files a/docs/presentations/MeshCentral - 0091 - SessionKey.pptx and /dev/null differ
docs/presentations/MeshCentral - 0092 - Agent Ping and Browser Pong.pptx
Binary files a/docs/presentations/MeshCentral - 0092 - Agent Ping and Browser Pong.pptx and /dev/null differ
docs/presentations/MeshCentral - 0093 - Web Relay Sharing.pptx
Binary files a/docs/presentations/MeshCentral - 0093 - Web Relay Sharing.pptx and /dev/null differ
docs/presentations/MeshCentral - 0094 - Device Pages.pptx
Binary files a/docs/presentations/MeshCentral - 0094 - Device Pages.pptx and /dev/null differ
docs/presentations/MeshCentral - 0095 - Security Password Policies.pptx
Binary files a/docs/presentations/MeshCentral - 0095 - Security Password Policies.pptx and /dev/null differ
docs/presentations/README.md
deleted
-3
@@ -1,3 +0,0 @@
1
-Powerpoints from Youtube channel:
2
-
3
-Originals located at: <https://info.meshcentral.com/downloads/meshcentral-slides/>
\ No newline at end of file
docs/requirements.txt
deleted
-3
@@ -1,3 +0,0 @@
1
-zensical>=0.0.23
2
-mkdocs-material>=9.0.0
3
-mkdocs-print-site-plugin>=2.3.0
docs/startdevzensicalonwindows.ps1
deleted
-23
@@ -1,23 +0,0 @@
1
-# This is for running Zensical locally on Windows only.
2
-# Make sure you change directory to your docs folder before starting this process
3
-# Use the "Run Selection" in VSCode to run the code blocks as-needed
4
-
5
-# Activate Python
6
-cd docs
7
-python -m venv env
8
-.\env\Scripts\activate
9
-
10
-# Install requirements (obvs first time only!)
11
-python -m pip install --upgrade pip # Additionally usable periodically to update pip modules
12
-pip install pytest
13
-pip install zensical
14
-pip install mkdocs-material
15
-pip install mkdocs-print-site-plugin
16
-pip install pymdown-extensions
17
-
18
-# Run Zensical and look at changes as you make them
19
-start-process http://localhost:8010 #Opens Browser
20
-zensical serve
21
-
22
-# Stop Python
23
-deactivate
\ No newline at end of file