MeshCentral Config Reference
The majority of the options for setting up MeshCentral are contained in the file config.json
. The basics of this file are pretty easy to grasp, but there are so many options available, and new features are being added so quickly, it can be hard to keep up.
Let's start with the obvious: The official config schema is quite literally the definition of all of these options. Anytime there is a discrepancy between that file and this page, trust that file!
also see config.md
Sections Overview
The first thing to grasp abut eh config file is the general layout, and what each section controls (or doesn't!). Let's start with a rough outline:
- settings:
- This section holds what are mostly global settings for the MeshCentral server. Database settings, security certificate, proxy, etc. are all examples of the types of things in this section. All of these are settings which can be defined at the command line when running the server manually.
- domaindefaults:
- Any settings in this section will be applied to ALL of the domains you set up in the next section.
- domains:
- This section will always have at least one (default) domain. The title and branding of the domain, password policies, hiding or showing features, and user consent settings are all the kinds of things you would find in this section. You can also define additional domains here (for different customers, or different departments, etc.) which can each have their own branding and preferences.
- letsnecrypt:
- Pretty self-explanatory. All the settings for using the built in support for Let's Encrypt Certificates with MeshCentral.
- peers:
- All of the settings related to load balancing multiple MeshCentral Servers for expanded capacity a resilience. Using load balancing still requires the use of a separate load balancer.
- smtp:
- Settings to tell MeshCentral how to send emails for forgotten passwords, MFA, or invitations.
- sms:
- Settings to support using SMS as a second factor authentication.
Settings Section
Individual Definitions and usage of each option available in the Settings section of config.json
In alphabetical order for easy searching. For actual use of these options when configuring MesCentral please see the COnfiguration How-To section of the wiki.
agentAliasDNS
When set, this specifies the DNS name used by the agents to connect to the agent-only port
agentAliasPort
When set, indicates the actual publically visible agent-only port. If not set, the AgentPort value is used.
agentAllowedIP
Comma separated list of IP Addresses or subnets in CIDR notation agents are allowed to connect from.
agentBlockedIP
Comma separated list of IP Addresses or subnets in CIDR notation agents are not allowed to connect from.
agentCoreDump
Automatically activates and transfers any agent crash dump files to the server in meshcentral-data/coredumps.
agentCoreDumpUsers
List of non-administrator users that have access to mesh agent crash dumps.
agentIdleTimeout
Needs Clarification I believe it is time in seconds an agent connection sits idle before being disconnected.
agentLogDump
Automatically downloads all agent error logs into meshcentral-data/agenterrorlogs.
agentPort
When set, enabled a new HTTPS server port that only accepts agent connections
agentPortTls
Indicates if the agent-only port must perform TLS, this should be set to false if TLS is performed in front of this server.
agentpPortBind
When set, binds the agent port to a specific network interface. Need to determine format, does it expect IP Address of the interface to bind to? Or name of the interface?
agentwscompression
Enables agent-side, websocket per-message deflate compression. wscompression must also be true for this to work.
aliasPort
Number of the publicly available port the agents will connect to. Used when MeshCentral is behind a reverse proxy and the MeshCentral Server is actually listening on a different port (defined by agentPort )
allowFraming
When enabled, the MeshCentral web site can be embedded within another website's iframe.
allowHighQualityDesktop
Allows high quality desktop streaming to be chosen. If set to false then ??? - Need to determine what quality this limits to
allowLoginToken
Allows accounts to be accessed by use of a login token in the URL as a replacement to user login. Useful for running MeshCentral embedded into another site
amtmanager
When enabled, MeshCentral will automatically monitor and manage Intel AMT devices. Assumed - This would apply to all device groups, regardless of settings?
authLog
File path and name of the authentication log to be created. This log can be parsed by Fail2ban.
autoBackup
Enables automated backups of the MeshCentral Server. These backups can then be stored to a local path on the server, a Google Could instance, or a WebDAV directory.
Properties:
- mongoDumpPath - Is this the path to save the database dump files, or the path to the database?
- mysqlDumpPath - Same question as above
- backupIntervalHours - Number of hours between backups
- backupIntervalDays - Number of days between backups
- keepLastDaysBackup - Needs clarification either the total number of past backup files to keep (last three backup files, regardless of created date) or Age in days to keep backup files before deleting them. (Make backup every 2 days, keep any backup less than 9 days old would keep 4 rolling backup files…)
- zipPassword - Password used to encrypt the backup zip file
- backupPath - local (to the server) path to store the backup files in. Note that the user/group MeshCentral is running as will require write permissions to this directory.
- googleDrive - Enables automatic upload of the backups to a Google Drive account. Once this is enabled, you will need to go into th eMy Server tab as an administrator and associate the Google Drive account.
- folderName - The name of the folder to create/use in the Google Drive Account.
- maxFiles - The maximum number of files to keep in the Google Drive Folder defined above. Older files will be removed as needed
- weDav - Enables the automated upload of backup files to a WebDAV Account.
- url - the WebDAV account URL
- username - WebDAV account username
- password - WebDAV account password
- folderName - The name of the folder to create/use in the WebDAV account
- maxFiles - The maximum number of files to keep in the WebDAV Folder defined above. Older files will be removed as needed
browserPing
When specified, sends data to the browser at x seconds interval and expects a response from the browser.
browserPong
When specified, sends data to the browser at x seconds interval. Does not expect a response.
cert
Set this to the primary DNS name for the server. This option must be set to run in WAN mode. If this option is not set the server will only run in LAN mode
compression
Enables GZIP compression for web requests.
cookieEncoding
Encoding format of cookies in the HTTP headers, this is typically Base64 but some reverse proxies will require HEX.
cookieIpCheck
Needs clarification - I believe it verifies the IP Address of the browser the cookie is sent from. if it does not match account is required to log in again?
dbEncryptKey
Specifies a password used to encrypt the database when NeDB is in use.
dbExpire
Settings related to automated Database cleanup routines. Properties:
- events - Amount of time in seconds that events are kept in the database. Default = 1,728,000 = 20 days
- powerevents - Amount of time in seconds that device power events are stored in the database. Default 864,000 = 10 days
- statsevents - Amount of time in seconds that server statistics are kept in the database. Default = 2,592,000 = 30 days
dbRecordsDecryptKey
When dbRecordsEncryptKey has been previously used in a database, but the bahavior is no longer desired, you can enter the key in this field to continue to be able to decrytpt any previously encrypted records, but not encrypting any new records in the future. You can then run this command again to force all records to be rewritten without encryption: node node_modules/meshcentral –recordencryptionrecode
dbRecordsEncryptKey
String used to encrypt specific sensitive fields before they are stored in the database. This is separate from any security settings applied to the full database. When DbRecordsEncryptKey is set, any new or updated records that are written will be encrypted when needed. Existing encrypted records will be read and decrypted as needed. You can force the all entries to be re-written by running: node node_modules/meshcentral –recordencryptionrecode
desktopMultiplex
When true, enables a server modules that efficiently splits a remote desktop stream to multiple browsers. Also allows slow browsers to not slow down the session for fast ones, this comes at the cost of extra server memory and processing for all remote desktop sessions.
exactPorts
Needs Clarification
ignoreAgentHashCheck
<HTML> <span style=“color:red;font-size:110%;”>!!Use of this option can pose a serious security risk, and is not recommended for production use!!</span> </HTML> When true, the agent no longer checks the TLS certificate of the server. This should be used for debugging only. You can also set this to a comma separated list of IP addresses which will ignore TLS certificate checks, for example: “192.168.2.100,192.168.1.0/24”
LANonly
When enabled, only MeshCentral LAN features are enabled and agents will find the server using multicast LAN packets.
localDiscovery
When this server is in LAN mode, you may discover this server using a multicast discovery tool. When discovery happens, the name and info fields are sent back to the discovery tool. Properties:
- name - The name of the MeshCentral Server.
- info - Any additional info or description about the MeshCentral Server to be sent.
- key - When set, encrypts all LAN discovery traffic to agents and tools using this key. This is only useful in LAN/Hybrid mode when agents and tools use multicast to find the server.
log
needs clarification. Schema says it is a string, so possibly the path to store log files?
maintenanceMode
When enabled the server is in maintenance mode, only administrators can login. Use the maintenance command in server console to change.
manageAllDeviceGroups
Comma separated list of administrators who are allowed to manage all device groups created on the server. (Without being added to them manually or through groups.)
manageCrossDomain
Comma separated list of administrators who are allowed to manage all domains created on the server. These admins will be allowed to manage the users for additional domains, bt will still requirte a domain specific account to be allowed to log in a nd manage devices on those domains.
mariaDB
Used to connect MeshCentral to a MriaDB instance. Properties
- host - hostname of the MariaDB Server
- user - MariaDB username
- port - MariaDB port number
- password - MariaDB password
- connectionLimit - MariaDB ConnectionLimit
- database - Name of the MariaDB database being used
- ssl -
- caCertPath - Absolute path to the CA certificate. Required for self-signed certificates
- clientCertPath - Absolute path to the client certificate. Required for two-way SSL Authentication
- clientKeyPath - Absolute path to the client key. Required for two-way SSL Authentication
- dontCheckServerIdentity - Set true to not check the server hostname during verification
meshErrorLogPath
Absolute path to store the MeshCentral server error log file. Defaults to meshcentral-data
mongoDB
When specified, tells MeshCentral server to use MongoDB instead of the built in NeDB. This should be entered as the connection string for the MongoDB being used. for example
mongodb://username:password@127.0.0.1:27017/meshcentral
or
mongodb://127.0.0.1:27017/meshcentral
mongoDBBulkOperations
Needs clarification - Enables/disables bulk operations, which I believe means MeshCentral caches several database changes, then sends them all at one time, reducing the number of individual connections required. I would be interested in learning the tradeoffs to this approach.
mongoDBcol
By default, MeshCentral creates a single collection called meshcentral
. Use this option to specify a different collection name.
mongoDBName
Needs clarification - By default MeshCentral uses meshcentral
as a database name. I believe this option is to change that default
mpsAliasPort
Publicly available port for Intel AMT connections to communicate with the MeshCentral Server. Used when MeshCentral is behind a reverse proxy, and may be locally using a different port.
mpsPort
Port MeshCentral Server will listen on for connections with Intel AMT
mpsPortBind
Needs clarification - physical interface to listen for Intel AMT connection on. Unsure whether this requires IP Address of the interface, or the name of the interface
mpsTlsOffload
When enabled, tells MeshCentral Server that another system (such as a reverse proxy) will be handling all encryption duties for AMT connections. Must be set to true when MeshCentral is being run behind a reverse proxy.
mySQL
Add this section to connect MeshCentral to a MySQL Database instance. Properties:
- host - hostname of the MySQL Server
- user - MySQL username
- port - MySQL port number
- password - MySQL password
- database - Name of the MySQL database being used
- ssl -
- caCertPath - Absolute path to the CA certificate. Required for self-signed certificates
- clientCertPath - Absolute path to the client certificate. Required for two-way SSL Authentication
- clientKeyPath - Absolute path to the client key. Required for two-way SSL Authentication
- dontCheckServerIdentity - Set true to not check the server hostname during verification
nice404
By default, a nice looking 404 error page is displayed when needed. Set this to false to disable it.
no2FactorAuth
Disables all multifactor authentication.
npmPath
Absolute path to the npm executable
npmProxy
URL to the proxy npm will use to connect to internet.
orphanAgentUser
If an agent attempts to connect to a unknown device group, automatically create a new device group and grant access to the specified user. Example: admin
port
The port number MeshCentral Server will run https services on.
portBind
Needs Clarification - Physical interface to bind https services to. Need to know if it requires IP Address of the interface, or the interface name.
publicPushNotifications
When true, this server uses MeshCentral.com a push notification relay for Android notifications. Push notifications work even if the Android app is not open.
redirAliasPort
Publicly accessible http port.
redirPort
Local port MeshCentral server will run http service on. (To be automatically redirected to https)
redirPortBind
Needs clarification - Physical interface MeshCentral Server will bind https services to. Need to know if this requires IP address or the name of the interface
selfUpdate
When true, this server will attempt to self-update everyday after midnight.
sessionSameSite
Needs Clarification -
sessionTime
Duration of a session cookie in minutes. Changing this affects how often the session needs to be automatically refreshed.
SessionKey
Needs Clarification -
syslog
When enabled, sends all server events to the (local) Linux syslog.
syslogauth
Needs clarification
syslogtcp
Send syslog events over the network (RFC3164) to a target hostname:port. For example: localhost:514
syslogjson
When enabled, sends all server events to the (local) Linux syslog in json format
tlsOffload
When true, indicates that a TLS offloader is in front of the MeshCentral server. More typically, set this to the IP address of the reverse proxy or TLS offloader so that IP forwarding headers will be trusted. For example: 127.0.0.1,192.168.1.100
trustedProxy
userAllowedIP
Comma separated list of IP Addresses or subnets which are allowed to access the MeshCentral web portal For example: 192.168.123.45,192.168.100.0/24
userBlockedIP
Comma separated list of IP Addresses or subnets which are not allowed to access the MeshCentral web portal For example: 192.168.123.45,192.168.100.0/24
WANonly
When enabled, only MeshCentral WAN features are enabled and agents will connect to the server using a well known DNS name.
webPush
When set with a valid email address, enables the MeshCentral web push notification feature. Allows administrators to send browser notifications to users even if they are not looking at the MeshCentral web site. Properties:
- email - Server administrator email given to the FireFox and Chrome push notification services.
webRTC
When enabled, allows use of WebRTC to allow direct network traffic between the agent and browser.
webrtcConfig
The STUN servers used for WebRTC, if not specified the Google and Mozilla servers and used when the server is not in LAN mode. Properties:
- iceServers - URL of the STUN server(s) to be used by WebRTC
wscompression
Enables server-side, websocket per-message deflate compression to reduce traffic bandwidth.