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

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.

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.

When set, this specifies the DNS name used by the agents to connect to the agent-only port

When set, indicates the actual publically visible agent-only port. If not set, the AgentPort value is used.

Comma separated list of IP Addresses or subnets in CIDR notation agents are allowed to connect from.

Comma separated list of IP Addresses or subnets in CIDR notation agents are not allowed to connect from.

Automatically activates and transfers any agent crash dump files to the server in meshcentral-data/coredumps.

List of non-administrator users that have access to mesh agent crash dumps.

Needs Clarification I believe it is time in seconds an agent connection sits idle before being disconnected.

Automatically downloads all agent error logs into meshcentral-data/agenterrorlogs.

When set, enabled a new HTTPS server port that only accepts agent connections

Indicates if the agent-only port must perform TLS, this should be set to false if TLS is performed in front of this server.

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?

Enables agent-side, websocket per-message deflate compression. wscompression must also be true for this to work.

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 )

When enabled, the MeshCentral web site can be embedded within another website's iframe.

Allows high quality desktop streaming to be chosen. If set to false then ??? - Need to determine what quality this limits to

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

When enabled, MeshCentral will automatically monitor and manage Intel AMT devices. Assumed - This would apply to all device groups, regardless of settings?

File path and name of the authentication log to be created. This log can be parsed by Fail2ban.

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

When specified, sends data to the browser at x seconds interval and expects a response from the browser.

When specified, sends data to the browser at x seconds interval. Does not expect a response.

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

Enables GZIP compression for web requests.

Encoding format of cookies in the HTTP headers, this is typically Base64 but some reverse proxies will require HEX.

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?

Specifies a password used to encrypt the database when NeDB is in use.

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

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

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

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.

Needs Clarification

<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”

When enabled, only MeshCentral LAN features are enabled and agents will find the server using multicast LAN packets.

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.

needs clarification. Schema says it is a string, so possibly the path to store log files?

When enabled the server is in maintenance mode, only administrators can login. Use the maintenance command in server console to change.

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.)

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.

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

Absolute path to store the MeshCentral server error log file. Defaults to meshcentral-data

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

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.

By default, MeshCentral creates a single collection called meshcentral. Use this option to specify a different collection name.

Needs clarification - By default MeshCentral uses meshcentral as a database name. I believe this option is to change that default

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.

Port MeshCentral Server will listen on for connections with Intel AMT

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

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.

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

By default, a nice looking 404 error page is displayed when needed. Set this to false to disable it.

Disables all multifactor authentication.

Absolute path to the npm executable

URL to the proxy npm will use to connect to internet.

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

The port number MeshCentral Server will run https services on.

Needs Clarification - Physical interface to bind https services to. Need to know if it requires IP Address of the interface, or the interface name.

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.

Publicly accessible http port.

Local port MeshCentral server will run http service on. (To be automatically redirected to https)

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

When true, this server will attempt to self-update everyday after midnight.

Needs Clarification -

Duration of a session cookie in minutes. Changing this affects how often the session needs to be automatically refreshed.

Needs Clarification -

When enabled, sends all server events to the (local) Linux syslog.

Needs clarification

Send syslog events over the network (RFC3164) to a target hostname:port. For example: localhost:514

When enabled, sends all server events to the (local) Linux syslog in json format

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

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

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

When enabled, only MeshCentral WAN features are enabled and agents will connect to the server using a well known DNS name.

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.

When enabled, allows use of WebRTC to allow direct network traffic between the agent and browser.

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

Enables server-side, websocket per-message deflate compression to reduce traffic bandwidth.