MeshAgent used along with MeshCentral to remotely manage computers. Many variations of the background management agent are included as binaries in the MeshCentr
MeshAgent used along with MeshCentral to remotely manage computers. Many variations of the background management agent are included as binaries in the MeshCentr
About
Social Media
MSH format
Self Test
Feedback
License
The MeshCentral Agent is the software that runs on remote devices and connects to the MeshCentral server to allow for remote device management. This agent is compiled for Windows, many different Linux distributions, macOS and FreeBSD. In addition compiled for many different processors x86-32, x86-64, ARM, MIPS. For most users, install the MeshCentral server first and install the agent from your server.
For more information, visit MeshCentral.com.
YouTube
Reddit
X
BlogSpot
LinkedIn
The MeshAgent gets it's security and connection instructions from a .msh text file formatted with each line being a "key=value". The .msh file is generally created by the MeshCentral server and, for example, would look like this:
MeshName=MyComputers
MeshType=2
MeshID=0xEDBE1BE...
ServerID=D99362D5...
MeshServer=wss://example.com:443/agent.ashxHere is a list of the possible keys that are currently supported by the agent. Note that the key name must have the exact capitalization:
| Option | Description |
|---|---|
AgentCapabilities |
Bitmask specifying supported agent capabilities. |
agentName |
If set, sent to the server instead of the hostname. |
ClientCertPem |
Path to a PEM file holding a private key followed by a certificate. If set, this certificate is presented as the TLS client certificate on the control channel and on relay tunnels, for example when the server sits behind a reverse proxy that requires mTLS. Does not affect the agent identity certificate or the NodeID. |
compactDirtyMinimum |
Minimum dirty bytes threshold for the db.compact() operation. |
consoleTextMaxRate |
Rate limit for sendConsoleText. Default is 10 messages per second. |
controlChannelDebug |
If set, logs/displays control channel messages (except JSON messages). |
controlChannelIdleTimeout |
Idle timeout in seconds; sends Ping/Pong to server to keep connection alive. |
coreDumpEnabled |
If set, writes a dump file when the agent crashes. |
disableUpdate |
If set, prevents the agent from self-updating. |
noUpdateCoreModule |
If set, prevents the agent from accepting a new meshcore from the server. |
enableILibRemoteLogging |
Port number to enable web logging. Disabled if not set. |
fakeUpdate |
If set, agent self-updates to the same version. Sets disableUpdate on completion. |
forceUpdate |
If set, causes the agent to perform a self-update on next start. |
ignoreProxyFile |
If set, causes the agent to ignore any proxy settings. |
logUpdate |
If set, causes the agent to log self-update status. |
logRotate |
If set to N (greater than 0), rotates the log file when it reaches maxLogSize, keeping N older copies (meshagent.log.1 … meshagent.log.N). |
logTruncate |
If set, clears the log file and continues when it reaches maxLogSize instead of stopping. Ignored if logRotate is set. |
jsDebugPort |
Specifies a JS debugger port. |
maxLogSize |
Maximum size in bytes of the log file (meshagent.log). Default 524288 (512 KiB). When reached, logging stops by default unless logRotate or logTruncate is set. |
nocertstore |
Windows only. Forces the agent to use OpenSSL instead of WinCrypto for cert generation/storage. |
readonly |
If set, forces the agent to open the database in read-only mode. |
readmsh |
If set while db is in read-only mode, caches the local .msh file in the read-only db. |
remoteMouseRender |
If set, always renders the remote mouse cursor for KVM. |
showModuleNames |
If set, displays module names when loaded for the first time. |
skipmaccheck |
If set, the agent will not change NodeID on local MAC address changes. |
slaveKvmLog |
Linux only. Enables logging inside the child KVM process. |
WebProxy |
Manually specifies proxy configuration. |
Many of these values are used by developers and are not typically used in normal use.
You'll need to mount procfs, which isn't mounted by default on FreeBSD. Add the following line to /etc/fstab
proc /proc procfs rw 0 0If you don't reboot, then you can manually mount with the command:
mount -t procfs proc /procIn addition, it is recommended to install bash, which you can do with the following command:
pkg install bashIf you get an error stating that an Xauthority cannot be found, and asking if your DM is configured to use X, or if you get a black screen when connecting to the login screen, you may need to:
DefaultSession=gnome-xorg.desktopIf you are using LightDM, and the child KVM process unexpectedly closes while connecting to the login screen, you'll need to:
user-authority-in-system-dir=falseYou need to disable rootfs verification, in order to install the meshagent service. After running the following commands, and rebooting, you should be able to install the meshagent service.
sudo su -
cd /usr/share/vboot/bin/
./make_dev_ssd.sh --remove_rootfs_verificationThe above line will return a warning, but it will tell you the boot partition number, which you will need when specifying the above command again, this time with the --partions options. Specify the number instead of (ID)
./make_dev_ssd.sh --remove_rootfs_verification --partitions ID
rebootWhen you are ready to install the agent, you'll need to copy the binary to a path that is not marked noexec, like /usr/local, so that you can execute the installer from there.
The MeshAgent has the ability to run a self test script, to aid in testing features of the Mesh Agent in consistent/reproducable fashion.
There are two modes of operation of the self test:
The easiest way to run the self tests, is by using Stand-alone mode, as it can be quickly setup and run anywhere. To get started, you will need make sure that the agent that you will be testing, has successfully connected to the server at least once. This is becuase the self test will simulate a server connection with the agent, so the agent will need to be running the meshcore that was pushed by the server, which is stored in the db. If the agent has not yet connected with a server, or the meshcore is missing from the .db, the self test will error out with a message stating that the meshcore could not be loaded.
Once the agent has successfully connected at least once, simply exit/stop the agent. Make sure that you have placed a copy of the agent-selftest.js file from the modules folder of the agent repository to the folder where the agent that you wish to test is located.
To start the test on Windows, from a command prompt, simply run the agent from the command line, with the --selfTest=1 switch:
MeshAgent --selfTest=1The self test does not explicitly need an elevated command prompt to run, but some tests, such as the AMT tests require elevated permissions.
To start the test on other platforms, simply run the agent from a console session. It will run best from a GUI capable console session, so that it can test features such as user consent. If you use SU to elevate the self test, it is best to pass in the -p flag, to preserve the envionment variables. To start the test, simply run the agent with the --selfTest=1 switch:
./MeshAgent --selfTest=1To run the self test in IPC Mode, requires a little more preparation. For security reasons, by default the agent does not allow running 'eval' commands thru the IPC channel, however, the Self Test IPC Mode, requires this functionality. The simplest way to allow this command, is to add the following entry in the msh configuration file of the agent, then restart the agent:
debugConsole=1To verify if this flag has been enabled, from the console tab for the agent, run the following command:
eval debugConsoleIf this returns 'true', then you are ready to run the self test in IPC Mode. To start the self test in IPC Mode, start the self test similarly to how you launch the Stand Alone test, from an elevated console, but add the following command line switch:
--serviceName="xxx"substituting xxx, with the service name of the agent you are trying to test. If you do not know the service name, you can navigate to the folder that contains the agent, and run the the agent from the command line with the following command line switch:
-nameThis will return the service name for that agent.
After concluding the tests, you can again disable the debugConsole flag by editing the msh configuration file of the agent like the following, and restarting the agent:
debugConsole=This will ensure that the debugConsole flag is cleared on the agent. This can be verified by running the following console command, similar to before. It should return false:
eval debugConsoleThe following is the list of basic tests that the Stand Alone test mode will test:
In addition to the above tests, IPC Mode test adds the following tests:
If you encounter a problem or have a suggestion to improve the product, you may file an issue report
If you are filing a problem report, you should include:
This software is licensed under Apache 2.0.
No open issues yet, or sync has not completed.