Merge pull request #3994 from silversword411/master

docs - converting meshctrl pdf to mkdocs

docs/docs/intelamt/index.md

@@ -1,9 +1,175 @@
 # Intel AMT
 
-[Intel AMT Guide](https://github.com/Ylianst/MeshCentral/blob/master/docs/MeshCentral2%20Intel%20AMT%20Guide%20v0.0.1.odt)
+
+Intel AMT Guide [as .odt](https://github.com/Ylianst/MeshCentral/blob/master/docs/MeshCentral Intel AMT Guide v0.0.1.odt?raw=true)
 
 ## Video Walkthru
 
 <div class="video-wrapper">
   <iframe width="320" height="180" src="https://www.youtube.com/embed/naWKE3rT6e8" frameborder="0" allowfullscreen></iframe>
 </div>
+
+## Abstract
+
+This user guide contains all essential information for activating and using Intel® Active Management Technology (Intel® AMT) with MeshCentral. We will review how to activate, connect to and use Intel AMT features and how this benefit administrators that want to manage computers remotely. This document expect the reader to already be familiar with how to install and operate MeshCentral and have a basic understanding of how Intel® AMT works.
+
+## Introduction
+
+MeshCentral is a free open source web-based remote computer management software and it fully supports Intel® Active Management Technology (Intel® AMT). MeshCentral does not require that computers it manages support Intel AMT, but if a remote computer has this capability, MeshCentral will make use of it.
+
+Intel AMT can be seen as a hardware based management agent that is built into some Intel PC’s. Once setup, Intel AMT can be used to remotely manage a computer regardless of the operating system health. It can be used to power on a computer when it’s in soft-off state or to provide enhanced monitoring and security to remote systems.
+
+Once setup, a computer can have up to management connections to MeshCentral. One of them by the Mesh Agent that lives in the operating system and another connection from Intel AMT. When remote management is made using an operating system agent, we call this “in-band management” and when management is done using a hardware based agent like Intel AMT, we call this “out-of-band management”
+
+![](images/2022-05-16-23-08-15.png)
+
+MeshCentral can support computers that have either or both agents. So, you can setup a computer with just the Mesh Agent, just Intel AMT or both. In this document we will show how to install computers with both agent connections or with just Intel AMT. When Intel AMT is used alone, we call this “agent-less” as there will be no operating system software required to remotely manage the computer.
+
+The Mesh Agent and Intel® AMT have very different and complementary capabilities and so, it’s often beneficial to use both and one will offer features the other can’t provide. Here are some of the benefits each has to offer:
+
+Mesh Agent
+
+  - Fast remote desktop / clipboard access.
+  - Remote access to operating system files.
+  - Remote chat and other OS features.
+
+Intel® AMT
+
+  - Remote desktop even when the agent or operating system is not functional.
+  - Remote access to BIOS.
+  - Connectivity when soft-off / sleeping.
+  - Remote power actions.
+
+If you are looking into managing remote computers that would be difficult to physically get access to for remote support or maintenance, one should probably look at getting a PC with Intel AMT.
+
+## MeshCentral Group Types
+
+Once MeshCentral is installed, a user will typically create a new device group. Here is the first hint that MeshCentral supports Intel AMT. Device groups come in two types. You can manage using a software agent, or using Intel AMT only.
+
+![](images/2022-05-16-23-10-40.png)
+
+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.
+
+![](images/2022-05-16-23-10-59.png)
+
+The main benefit of “Intel AMT only” group is if someone does not want to install a background agent on remote systems or already have a remote management solution and intends to only use MeshCentral to supplement the existing solution with Intel AMT features.
+
+Once a group is created, the links MeshCentral provides to on-board devices will change depending on the group type and how the server is setup. The device on-boarding links are located in the “My Devices” page, next to the group name.
+
+![](images/2022-05-16-23-11-24.png)
+
+If the MeshCentral server is setup in “LAN mode” or “Hybrid mode”, options will be available to add computers on the local network. If you have an Intel AMT computer that is already activated, you can select the “Add Local” or “Scan Network” options in the “Intel AMT only” group type and start adding local network computers this way. If MeshCentral is in “WAN mode”, you will need to setup Intel AMT to connect back to MeshCentral using a feature called “Client Initiated Remote Access” or CIRA for short. We will cover that in a later section.
+
+## Client Initiated Remote Access & MPS server
+
+Client Initiated Remote Access (CIRA) is a feature of Intel AMT that, then configured, makes Intel AMT connect back to the server using a TLS tunneling connection similar with a SSH tunnel. Once this tunnel connection is established, the server can perform remote management operations on Intel AMT.
+
+CIRA is great when remotely managing Intel AMT devices over the Internet thru network address translator (NAT) routers where the server would not be able to connect to Intel AMT. This is similar to the Mesh Agent that initiated and keeps an idle connection to the server.
+
+By default, MeshCentral will be configured to receive Mesh Agent connections on TCP port 443 and Intel AMT connections on TCP port 4433. These port values can be configured in the config.json file of MeshCentral.
+
+![](images/2022-05-16-23-12-04.png)
+
+Once connected to port 443, the Mesh agent will using secure HTTPS WebSocket to securely communicate with the server. Intel AMT will use TLS to connect to port 4433 and use a binary tunneling protocol called the Intel AMT Port Forwarding Protocol (APF). You can find documentation on this protocol at the following URL: 
+
+<https://software.intel.com/sites/manageability/AMT_Implementation_and_Reference_Guide/HTMLDocuments/MPSDocuments/Intel%20AMT%20Port%20Forwarding%20Protocol%20Reference%20Manual.pdf>
+
+It’s not necessary to know or understand the details of this protocol, MeshCentral will take care of handling this. In Intel AMT nomenclature, the server that receives a CIRA connection is called a “Management Presence Server” or MPS for short. In other words, MeshCentral has a MPS server on port 4433 ready to receive Intel AMT CIRA connections.
+
+![](images/2022-05-16-23-12-37.png)
+
+When MeshCentral is first setup, a self-signed root certificate is created along with a MPS certificate that will be presented when a device connects on port 4433. There is typically no need to use a CA signed & trusted certificate on port 4433 was we only expect Intel AMT computers to connect to this port and we will be loading our self-signed root in Intel AMT for authentication purposes.
+
+One way to check that the MeshCentral MPS server is running correctly is to use a browser and access port 4433 using HTTPS. The browser will display a warning because the port 4433 certificate is not trusted, but this is expected.
+
+![](images/2022-05-16-23-12-58.png)
+
+The CIRA protocol is binary, but MeshCentral will detect that the request is made from a browser and return a short message:
+
+```
+MeshCentral2 MPS server.
+Intel® AMT computers should connect here.
+```
+
+This is practical to make sure connectivity with the MeshCentral MPS server is working. Now that we know the basics of Intel AMT CIRA and the MPS server, we can configure Intel AMT to connect.
+
+## Activation Certificate Setup
+
+If you have an Intel AMT activation certificate, you should configure MeshCentral to take advantage of it. Your activation certificate must have been issued by one of the certificate authorities (CA’s) that is trusted by Intel AMT and MeshCentral will need the entire certificate chain to be provided since the entire chain is needed to perform Intel AMT ACM activation.
+
+![](images/2022-05-16-23-13-44.png)
+
+The leaf certificate will have the Intel AMT activation option and a specific domain name while the hash of the trusted CA certificate must be trusted by Intel AMT. The certificate chain will have to be setup in the domain section of the MeshCentral config.json file.
+
+If you have a certificate chain in a .pfx or .p12 format, place that file in the “meshcentral-data” folder and add the “AmtAcmActivation” section in the domain section like so:
+
+```
+{
+  "settings": {
+    "Cert": "devbox.mesh.meshcentral.com",
+  },
+  "domains": {
+    "": {
+      "title": "My Server",
+      "AmtAcmActivation": {
+        "log": "amtactivation.log",
+        "certs": {
+          "myamtcert": {
+            "certpfx": "amtcert.pfx",
+            "certpfxpass": "pfxpassword"
+          }
+        }
+      }
+    }
+}
+```
+
+If you have the certificate chain in PEM format as a set of .crt files and a .key file, start by placing all of the certificate files in the “meshcentral-data” folder and setup the certificate chain like this:
+
+```
+{
+  "settings": {
+    "Cert": "devbox.mesh.meshcentral.com",
+  },
+  "domains": {
+    "": {
+      "title": "My Server",
+      "AmtAcmActivation": {
+        "log": "amtactivation.log",
+        "certs": {
+          "myvprocert": {
+            "certfiles": [ "amtacm-vprodemo.crt",
+   "amtacm-intermediate1.crt",
+   "amtacm-intermediate2.crt",
+   "amtacm-root.crt" ],
+            "keyfile": "amtacm-vprodemo.key"
+          }
+        }
+      }
+    }
+}
+```
+
+It’s important that the leaf certificate file be the first file in the “certfiles” array. The order of the other certificates is not important as MeshCentral will figure out and re-order them correctly. 
+
+Within the new “AmtAcmActivation” section, there is a “log” entry. This is a log file that will contain every activation attempt including the details of the computer being activation and what Intel AMT administrator password was used for activation. This log file should be kept securely as it will contain Intel AMT credentials. It’s also important to have this file as a backup so that Intel AMT credentials are not lost after activation. If MeshCentral can’t write to this log, the activation will not go forward and will fail.
+
+Once the config.json was modified, restart the server. There will be two indications that the server has the new certificate correctly configured. For “Intel AMT only” groups, a new “Activation” link will show up. Clicking this link will show a command that can be run to perform ACM activation.
+
+![](images/2022-05-16-23-14-42.png)
+
+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.
+
+![](images/2022-05-16-23-15-04.png)
+
+Once setup, Intel AMT will not automatically activate to Intel AMT unless the right situation is met. The Intel AMT activation certificate is for a specific domain name suffix, for example “meshcentral.com”. Intel AMT must be in a situation where this domain can be accepted. One of the following must be true:
+
+  - Intel AMT must have a wired Ethernet interface that is connected to a local network with a DHCP server responding with option 15 set to “xxx.meshcentral.com”.
+  - The name “meshcentral.com” by have been set as “Trusted FQDN” in MEBx.
+  - The name “meshcentral.com” must have been set using a USB key with a setup.bin file.
+
+Once Intel AMT is in a situation where ACM activation can occur, the activation command line can be run or the Mesh Agent will detect this situation and ask the server to perform activation.
+
+![](images/2022-05-16-23-16-05.png)
+
+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.

docs/docs/meshctrl/index.md

@@ -1,9 +1,461 @@
 # MeshCtrl
 
-[MeshCtrl Command Line Tool](https://github.com/Ylianst/MeshCentral/blob/master/docs/MeshCentral2%20Intel%20AMT%20Guide%20v0.0.1.odt)
+MeshCmd Guide [as .pdf](https://meshcentral.com/info/docs/MeshCtrlUsersGuide.pdf) [as .odt](https://github.com/Ylianst/MeshCentral/blob/master/docs/MeshCtrl User's Guide v0.0.1.odt?raw=true)
 
 ## Video Walkthru
 
 <div class="video-wrapper">
   <iframe width="320" height="180" src="https://www.youtube.com/embed/p_jdtYJyuBQ" frameborder="0" allowfullscreen></iframe>
 </div>
+
+
+![](images/2022-05-16-21-33-47.png)
+
+## Abstract 
+
+This user guide contains all essential information for the user to make full use of MeshCtrl, a command line tool used to perform tasks on the MeshCentral server. This tool is built in NodeJS and can be run on the same computer as the server, or on a different computer. It’s typically used by administrators to perform various management operations on the MeshCentral server. 
+
+## Introduction 
+
+MeshCtrl, also called “Mesh Control”, is a command line tool built in NodeJS that comes with MeshCentral and allows command line management operation of the MeshCentral server. It can be run both on the same computer as the MeshCentral server, or on a different computer. This tool allows an administrator to list user accounts, create and remove user accounts, list device groups and much more. All of the operations performed by this tool can also be performed using the MeshCentral website, however it’s sometimes useful to automate and script some management operations from the command line and this tool can do this. 
+
+![](images/2022-05-16-21-40-21.png)
+
+MeshCtrl will login to the MeshCentral server using a web socket connection, just like the web application does and so, it needs to login to the server using user or administrator credentials. In the next section, we will cover how to login using MeshCtrl, we then follow with the operations that MeshCtrl can perform. 
+
+## Running MeshCtrl 
+
+MeshCtrl.js is a file that is installed with MeshCentral and is located in the “./node\_modules/meshcentral” folder. You can normally run MeshCtrl like this: 
+
+```
+node ./node\_modules/meshcentral/meshctrl 
+```
+
+In this case, when the above command is run without parameters, you should see something like this: 
+
+```
+MeshCtrl performs command line actions on a MeshCentral server.
+Information at: https://meshcommander.com/meshcentral
+No action specified, use MeshCtrl like this:
+
+  meshctrl [action] [arguments]
+
+Supported actions:
+  Help [action]             - Get help on an action.
+  ServerInfo                - Show server information.
+  UserInfo                  - Show user information.
+  ListUsers                 - List user accounts.
+  ListDevices               - List devices.
+  ListDeviceGroups          - List device groups.
+  ListUsersOfDeviceGroup    - List the users in a device group.
+  AddUser                   - Create a new user account.
+  RemoveUser                - Delete a user account.
+  AddDeviceGroup            - Create a new device group.
+  RemoveDeviceGroup         - Delete a device group.
+  AddUserToDeviceGroup      - Add a user to a device group.
+  RemoveUserFromDeviceGroup - Remove a user from a device group.
+  SendInviteEmail           - Send an agent install invitation email.
+  Broadcast                 - Display a message to all online users.
+
+Supported login arguments:
+  --url [wss://server]      - Server url, wss://localhost:443 is default.
+  --loginuser [username]    - Login username, admin is default.
+  --loginpass [password]    - Login password.
+  --token [number]          - 2nd factor authentication token.
+  --loginkey [hex]          - Server login key in hex.
+  --loginkeyfile [file]     - File containing server login key in hex.
+  --domain [domainid]       - Domain id, default is empty.
+```
+
+This indicated you have a good version of MeshCentral with support for MeshCtrl. MeshCentral and MeshCtrl will be updated together, so as changes are made to the server, MeshCtrl will also be updated to match. 
+
+The next step is to login to the server with MeshCtrl before we can start performing commands. For this document, we will assume we are connection to the local MeshCentral server on port 443 using TLS. For connecting to a different server, use the --url argument to set a different server. 
+
+## Login 
+
+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. 
+
+### Login using username & password
+
+This is the easiest way to login and start issuing commands is to login using a username and password. 
+
+![](images/2022-05-16-21-47-32.png)
+
+You do this by using the "loginuser" and "loginpass" argument like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo --loginuser "admin" --loginpass "mypassword"
+```
+
+In this example we are trying to run the “serverinfo” command using the “admin” user and “mypassword” as the password. Because “admin” if the default username for MeshCtrl, you can omit it and just type: 
+
+```
+Authentication token required, use --token [number].
+```
+
+In this case, you need to use the Google Authenticator application or a similar application to enter your time based second factor like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo --loginpass "mypassword" –token 123456
+```
+
+Once the command is run successfully, you should see a response like this: 
+
+```
+name: devbox.meshcentral.com
+mpsname: devbox.meshcentral.com
+mpsport: 4433
+port: 443
+emailcheck: true
+domainauth: false
+tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
+https: true
+redirport: 80
+```
+
+This is a typical response for the “serverinfo” command and a good way to test that everything is working as expected. 
+
+### Login using the server login key
+
+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. 
+
+![](images/2022-05-16-21-50-39.png)
+
+In this technique, we will get a special encryption key from the server and use this to generate a login token to the server. First, we must activate the login token feature of the server by setting “AllowLoginToken” to “true” in the “settings” section of config.json: 
+
+```
+{
+  "settings": {
+    "Port": 443,
+    "AllowLoginToken": true
+  }
+}
+```
+
+Then run the MeshCentral server with the --logintokenkey parameter, you should see something like this: 
+
+```
+node ./node_modules/meshcentral --logintokenkey
+f3bd69a08a2dde4a3423bec8f20d8626b1e6365381f2d9919e7dfe256ace9cbbdea66bed2bdcd00b71eea9d7c727cb6eb37f3148c0c2d240d5ed44c8f3f6795a479c949159dad366571fea4db7f31c24
+```
+
+The hex value presented here is a sensitive secret that allows anyone to create login tokens that can be used for user impersonation. This key is used when MeshCentral does server peering and load balancing for example. You should save this key in a file, for example “key.txt”, you can do it like this: 
+
+```
+node ./node_modules/meshcentral –logintokenkey > key.txt
+```
+
+Now that you have the server key, you can use MeshCtrl like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --loginuser admin
+```
+
+Instead of using a password, we use the key file instead. MeshCtrl will generate a time limited cookie and use that to login as “admin”. Since “admin” is the default username for MeshCtrl, we can omit this parameter: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt
+```
+
+Like the username and password example above, the result will be the server information we requested. Something like this: 
+
+```
+name: devbox.meshcentral.com
+mpsname: devbox.meshcentral.com
+mpsport: 4433
+port: 443
+emailcheck: true
+domainauth: false
+tlshash: E7A41E1A56D8D716F7D7729B876E48693F2D19C4761F22B1…
+https: true
+redirport: 80
+```
+
+### Login into a different domain
+
+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. 
+
+![](images/2022-05-16-21-54-38.png)
+
+To do this, using the username and password, we have to tell MeshCtrl to login using the URL that would be used to access that domain, for example: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo --url wss://server/domainname --loginuser "admin" --loginpass "mypassword"
+```
+
+or for servers have a DNS name for a domain: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo --url wss://domainname.server --loginuser "admin" --loginpass "mypassword"
+```
+
+Note the "--url" argument is different and so, the server will see MeshCtrl access the server using a different domain. 
+
+Doing a domain login using the login is key file is a bit different. We need to specify both the url to access that domain and specify the domain name explicitly using the --domain argument. For example: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://server/domainname --domain mycustomer
+```
+
+So, we add both the url to access the correct domain and the domain name explicitly. The domain name must be exactly the one that is used in the domain section of the config.json for of MeshCentral. For example, if the MeshCentral config.json file looks like this: 
+
+```
+{
+  "settings": {
+    "Cert": "myserver.com",
+    "Port": 443
+  },
+  "domains": {
+    "": {
+      "title": "Default domain",
+    },
+    "customer1": {
+      "dns": "c1.myserver.com",
+      "title": "Customer1 domain",
+    }
+  }
+}
+```
+
+The domain login for MeshCtrl with a key file would look like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl serverinfo –-loginkeyfile key.txt --url wss://c1.myserver.com --domain customer1
+```
+
+In the next section, we start making use of MeshCtrl to do useful things on the server. From now on, we will omit the login arguments, but note that they are required for all commands. 
+
+## Making use of MeshCtrl 
+
+We can start doing useful operations with MeshCtrl. The current list of operations are: 
+
+```
+ServerInfo                - Show server information.
+  UserInfo                  - Show user information.
+  ListUsers                 - List user accounts.
+  ListDevices               - List devices.
+  ListDeviceGroups          - List device groups.
+  ListUsersOfDeviceGroup    - List the users in a device group.
+  AddUser                   - Create a new user account.
+  RemoveUser                - Delete a user account.
+  AddDeviceGroup            - Create a new device group.
+  RemoveDeviceGroup         - Delete a device group.
+  AddUserToDeviceGroup      - Add a user to a device group.
+  RemoveUserFromDeviceGroup - Remove a user from a device group.
+  SendInviteEmail           - Send an agent install invitation email.
+  Broadcast                 - Display a message to all online users.
+```
+
+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]” 
+
+### Gathering information
+
+The following commands are really easy to use: serverinfo, userinfo, listusers, listdevices, listdevicegroups. They just request information from the server. Note that for these commands, you can optionally use “--json" to receive the response in JSON format. For example, getting the list of users will look like this: 
+
+```
+node meshctrl.js listusers
+id, name, email
+---------------
+"admin", "admin", "ylian.saint-hilaire@intel.com"
+"joe", "joe", "joe@intel.com"
+"mytestuser", "MyTestUser", "a@a.com"
+"test.user", "test.user", "test.user@user.com"
+```
+
+In the --json argument is used, it looks like this: 
+
+```
+node meshctrl.js listusers --json
+  {
+    "_id": "user//admin",
+    "name": "admin",
+    "creation": 1417814230,
+    "siteadmin": 4294967295,
+    …
+```
+
+The JSON version is much long and contain much more information. This format can be useful if you take the output of MeshCtrl and dump it into a file for later parsing. One really useful command is “listdevices” that just displays all the devices in the account grouped by device groups. For example: 
+
+```
+node meshctrl listdevices
+
+Device group: "Lab Computers"
+id, name, icon, conn, pwr, ip
+-----------------------------
+p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
+yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
+DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
+ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
+ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
+fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
+hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
+YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
+PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
+tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
+i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
+2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
+0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
+
+Device group: "IntelAMT only"
+id, name, icon, conn, pwr, ip
+-----------------------------
+LN8qsH634RGjDwATIOd3ICzfKrB@t@ERow8AEyDndyAs3yqwfrfhEaMPABMg53cg, "AmtMachine7", 0, 0, 0
+Ea3GcF$EoMnDEc9Tbz$Vu9wnmTziqqcOZ0URSdYeuVn4LU9LLMT@91P5s1WLSgVA, "DevBox", 0, 0, 0
+```
+
+It’s also possible to list only the display the list of devices for a single group. Just add --id followed by the group identifier. You can find the group identifier using the “DeisplayDeviceGroups” command. For example: 
+
+```
+node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055…
+
+id, name, icon, conn, pwr, ip
+-----------------------------
+p3HOhDapgT@VyO$upGJYxEa$v4YCY76Y2G@hOGmJnbPXjkSHP@AgJ1M6FkqSEUqg, "raspberrypi", 5, 1, 1
+yjbMXlQBf09TSIqKlkwrRucm767TcXfNbSinQWXgpdBBY5MEU1gg0kzshwiwFCOp, "tinkerboard", 5, 1, 1
+DRvCLkYIgk744tqqMr9Xvy5TK8aXkLoOXUQETnFdFepVQojyFV5gaBi5Gh4f6B6d, "LattePanda", 5, 1, 1
+ggifepc5wqK7sCVnOIjOZy9i9kaJizalIarz7Qwe5bJ4icpLD69zWYpjAaU@sfY$, "MeshLabTop", 1, 5, 1
+ECAI7NO893JoN3ntK7@mbniyDq0qriG82wqGKQF4s8SpXs3NdnvuHR76Bzq14Pik, "MeshLabRight", 1, 1, 1
+fCLFeHaxQ$T6mgICdVkCdkifiU8LNJdU73YknmxfAb@0jBF2BrhTsEIBwgpoCNx$, "DevLinux", 1, 1, 1
+hfbJ7zAgwZK@LQfsZkr1cqTSp6mjjZ3MjGC$v4X8E7HM1cZEnlGBgcorELu1hZWe, "AmtMachine11", 1, 1, 1
+YRGm4AQVRR38Ypisuo40KhvBGhDl2pE5YCp4j4eIbLaX3kmH3tmumOUbxb44A@Rh, "CoffeeTable", 1, 1, 1
+PpMJiPxtjRjfoEal$9RHdm5s31BaqDSbGc3329s49rzcXcVuTDvm4VO0YllO5XR7, "DevBox", 1, 0, 0
+tyR7l2j5@wOjDeRbOQNfjU7xB$ss6VZQPDkFsALPzJ4zbTI4IamV$OdwHeqiXV0K, "MeshLabLeft", 1, 5, 1
+i@BNTAHB5NMtDyrHMiCaz3GzYlJUUQn7qZZfh@N6271DWAM3EH6ujRNPc2snGXYX, "raspberrypi", 5, 1, 1
+2E$CjXw2Aldh3DGAzSNo5qTSgEhd4OTWcO9KGBi9ja4EOxEUHq8J1135Y2IvxOlX, "AmtMachine7", 1, 5, 1
+0Ab3O@4fgHjwVOpC0qaARfURTtKCa@QjxWPDpT5WQ0Wz5s4OvRWAgeoGT9j8k5JF, "RaspberryPi", 5, 1, 1
+```
+
+You can also add “--count" to just return the number of devices instead of displaying them. An example of this would be: 
+
+```
+node meshctrl listdevices --id 7b4b43cdad850135f36ab31124b52e47c167fba055… --count
+13
+```
+
+Here we see that in a specific device group, there are 13 devices.
+
+### Adding and removing accounts
+
+MeshCtrl can be used to add and remove user accounts. This is great is you want to automate MeshCentral in some situations. Normally, an administrator can go to the “My Users” tab and press “New Account…” button to create a new account. 
+
+![](images/2022-05-16-22-04-06.png)
+
+With MeshCtrl the same process can be accomplished using the following command line:
+
+```
+node ./node_modules/meshcentral/meshctrl adduser --user SampleUser --pass SamplePassword 
+```
+
+This will create a basic user account with the specified “SampleUser” username and “SamplePassword” password. In addition to the basic example above, there are plenty of additional arguments that can be used. There is a list: 
+
+```
+--email [email]    - New account email address.
+--emailverified    - New account email is verified.
+--resetpass        - Request password reset on next login.
+--siteadmin        - Create the account as full site administrator.
+--manageusers      - Allow this account to manage server users.
+--fileaccess       - Allow this account to store server files.
+--serverupdate     - Allow this account to update the server.
+--locked           - This account will be locked.
+--nonewgroups      - Account will not be allowed to create device groups
+--notools          - Account not see MeshCMD download links.
+```
+
+Instead of specifying a password, one can specify “--randompass" to have MeshCtrl generate a random password, this is typically use along with “--resetpass" and “--email" to cause the user to perform a password reset the first time a login occurs. 
+
+The permission arguments are used to grant server permissions to the new account. The “-- siteadmin" argument will grant this account full site administrator rights and all other permission arguments are ignored. The other permission arguments can be combined. 
+
+To remove a user account, use the following command: 
+
+```
+node ./node_modules/meshcentral/meshctrl removeuser --userid SampleId
+```
+
+Note that when creating a new user, the username is passed in. However, when removing a user account, the userid is used. One can get the list of userid’s by using the “ListUsers” command. 
+
+MeshCtrl will return “ok” if the command is successful and the account will be added in real-time to the “My Users” tab on the website. 
+
+### Creating and removing device groups
+
+MeshCtrl can be used to add and remove device groups. When a group is created, it’s added in the account that MeshCtrl is logged into and that account gets full rights over that device group. Typically, a new device group is created using the “Add Device Group” link in the main website. 
+
+![](images/2022-05-16-22-06-35.png)
+
+A group has a name, type and optionally a description text. To add a device group using MeshCtrl, we use the “AddDeviceGroup” command like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl adddevicegroup --name "Sample group name" --desc "Sample description"
+```
+
+Here we specify the name and description of the new device group. This will create a normal device group that requires agents to be installed on each computer. You can also create an agent-less Intel AMT device group by adding the "--amtonly" argument. Once done, MeshCtrl will return “ok" and the group will be created in the logged in account in real-time. 
+
+You can delete a group by using the “RemoveDeviceGroup” command like this: 
+
+```
+node ./node_modules/meshcentral/meshctrl removedevicegroup --id 7b4b43cd…dc89fe0e581c
+```
+
+To remove a device group, the group identifier needs to be specified. You can get that identifier using the "ListDeviceGroups" command. For device groups, the group identifier is a long hex value. 
+
+### Adding and removing users from device groups
+
+Once you created user account and device groups, the next important operation is to connect the two and grant users access to some device groups. In the web interface, this is typically done by clicking on a device group and managing the users in that page. 
+
+![](images/2022-05-16-22-20-44.png)
+
+To do this, you first have to get the user and group identifiers. You can get these using the “listusers” and “listdevicegroups” commands. Then, you can for example do this: 
+
+```
+node ./node_modules/meshcentral/meshctrl addusertodevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob --fullrights
+```
+
+Typically, the group identifier is a long hex value. The command will add user “bob” to a given group with full rights. You can also add a user to a group with only some rights, the list is as follows: 
+
+```
+  --fullrights           - Allow full rights over this device group.
+  --editgroup            - Allow the user to edit group information.
+  --manageusers          - Allow the user to add/remove users.
+  --managedevices        - Allow the user to edit device information.
+  --remotecontrol        - Allow device remote control operations.
+  --agentconsole         - Allow agent console operations.
+  --serverfiles          - Allow access to group server files.
+  --wakedevices          - Allow device wake operation.
+  --notes                - Allow editing of device notes.
+  --desktopviewonly      - Restrict user to view-only remote desktop.
+  --limiteddesktop       - Limit remote desktop keys.
+  --noterminal           - Hide the terminal tab from this user.
+  --nofiles              - Hide the files tab from this user.
+  --noamt                - Hide the Intel AMT tab from this user.
+```
+
+Note that if “fullrights” are granted, all other access right arguments are ignored. If successful, MeshCtrl will display “ok”, otherwise it will show an error message. 
+
+To remove a user from a group, use the “removeuserfromdevicegroup” command. For example: 
+
+```
+node ./node_modules/meshcentral/meshctrl removeuserfromdevicegroup --id 7b4b43cd…dc89fe0e581c --userid bob
+```
+
+The syntax of this command is identical to the “addusertodevicegroup” command, but there are no rights arguments. MeshCtrl will also display “ok” if the command got processed correctly. 
+
+### Message Broadcast
+
+One fun command the MeshCtrl offers is the “broadcast” command. It sends a short notification message that all connected users will see in real-time. For example, you can do this: 
+
+```
+node ./node\_modules/meshcentral/meshctrl broadcast --msg "This is a test" 
+```
+
+All connected users will see this: 
+
+![](images/2022-05-16-22-23-40.png)
+
+The broadcast command is great for notifying users of upcoming server downtime or other events. 
+
+## Conclusion 
+
+MeshCtrl is an essential tools in every MeshCentral administrator’s tool box. It allows administrators to automate various MeshCentral management tasks which can be useful for large scale management of many devices and users. 
+
+## License 
+
+MeshCtrl and this document are both opens source and licensed using Apache 2.0, the full license can be found at [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0) 

docs/docs/other/adfs_sso_guide.md

@@ -0,0 +1,82 @@
+# ADFS SSO Guide
+
+## Assumptions
+
+The following guide was built under the assumptions that:
+
+1. ADFS 4.0 running on Server 2016 using Active Directory
+2. Main ADFS setup already completed / working. SSL certs installed and port forwarded as expected.
+
+The guide was built to deal specifically with adding mesh as a Relying Party. I’m far from an ADFS expert and some configurations may not be needed. Most of this was built by reading the code and taking guesses as to the needed values.
+
+## Guide
+
+As with anything SSO, you need 2 pieces – the IDP setup (in this case ADFS) and the SP setup (in this case Mesh).
+
+### Mesh Setup:
+
+Add the following to your mesh config file in the domains part:
+
+![](images/adfs_sso2022-05-16-23-24-54.png)
+
+`Callback URL`: Should be the FQDN for your Mesh Server, ending with /auth-saml-callback
+
+`Entity ID`: This is how ADFS IDs which party the request goes to. You can set this to whatever you want, but you will need this value later on when working in ADFS.
+
+`IDP URL`: This is the URL to ADFS. Ends with /adfs/ls unless you did something very weird in ADFS.
+
+`Cert`: You will need to export the token signing cert from ADFS, then convert it to PEM format. This cert can be found in `ADFS -> Service -> Certificates`. You can use this openssl command to convert it from CRT to PEM format: 
+
+```
+openssl x509 -in mycert.crt -out mycert.pem -outform PEM
+```
+
+Save the config and restart the mesh server. 
+
+### Windows Server Configuration
+
+ADFS setup (in pictures):
+
+Relying Party Trust -> New Relying Party Trust
+
+![](images/adfs_sso2022-05-16-23-25-48.png)
+
+![](images/adfs_sso2022-05-16-23-26-01.png)
+
+![](images/adfs_sso2022-05-16-23-26-47.png)
+
+![](images/adfs_sso2022-05-16-23-26-56.png)
+
+![](images/adfs_sso2022-05-16-23-27-03.png)
+
+![](images/adfs_sso2022-05-16-23-27-09.png)
+
+![](images/adfs_sso2022-05-16-23-27-16.png)
+
+![](images/adfs_sso2022-05-16-23-27-22.png)
+
+![](images/adfs_sso2022-05-16-23-27-28.png)
+
+Edit the new “Relying Party Trust” Properties:
+
+![](images/adfs_sso2022-05-16-23-27-41.png)
+
+![](images/adfs_sso2022-05-16-23-27-51.png)
+
+Then it’s time to add Claims…
+
+![](images/adfs_sso2022-05-16-23-28-09.png)
+
+![](images/adfs_sso2022-05-16-23-28-15.png)
+
+![](images/adfs_sso2022-05-16-23-28-21.png)
+
+For the outgoing claim type, where it says firstname, lastname, and email, manually type it in as shown. All other fields should be selected from the dropdown.
+
+Add another rule:
+
+![](images/adfs_sso2022-05-16-23-28-41.png)
+
+![](images/adfs_sso2022-05-16-23-28-48.png)
+
+For all fields, select from the dropdowns

docs/mkdocs.yml

@@ -26,6 +26,9 @@ nav:
   - Intel AMT:
     - intelamt/index.md
 
+  - Other:
+    - other/adfs_sso_guide.md
+
 site_description: "A remote monitoring and management tool"
 site_author: "Ylianst"
 site_url: "https://git.meshcentral.com/"

docs/startdevmkdocs.ps1

@@ -13,4 +13,7 @@ pip install mkdocs-material #only 1st time
 
 #Run mkdocs and look at changes as you make them
 mkdocs serve
-start http://localhost:8010 #Opens Browser
+start http://localhost:8010 #Opens Browser
+
+#Stop python
+deactivate