Howto install MeshCentral on NethServer

Howto
, ,
41

do you know how to whitelist ip from fail2ban via ssh?
i have blocked my ip, it can;t connect to ssh, but meshcentral ui can

42

fail2ban-unban IP

1 Like
43

and whitelist?

44

You can manage it in UI when unbanned.

config setprop fail2ban IgnoreIP 1.2.3.4,5.6.7.8
signal-event nethserver-fail2ban-save

2 Likes
45

You can configure a MeshCentral server to use an LDAP server for user authentication by adding the following to the domain section of the config.json (this is only an example):

      "auth": "ldap",
      "ldapUserName": "displayName",
      "ldapUserBinaryKey": "objectSid",
      "ldapOptions": {
        "url": "ldap://127.16.0.1:389",
        "bindDN": "CN=svc_meshcentral,CN=Users,DC=meshcentral,DC=local",
        "bindCredentials": "Password.1",
        "searchBase": "DC=meshcentral,DC=local",
        "searchFilter": "(sAMAccountName={{username}})"
      }

MeshCentral uses the “ldapauth-fork” module to do this. Look at that module for the proper options.

4 Likes
46

Tip: if after editing config.json things go south, check config.json has valid syntax. To save time when looking for the error you can use tools like jq:

jq empty < /opt/meshcentral/meshcentral-data/config.json

or some online json linters:

3 Likes
47

Great, I added the jq line to the troubleshooting section.

48

This 503 error that just comes on its own is driving me nuts.
currently there are no errors in error log, and i have not made any new changes to the server

EDIT: weired scenraio, remember the coma we added the other time, not sure who or how it was removed, i used jsonlint to check if there is an issue.

Now add to the install guide that any 503 error, should first check the config.json as there is where most of that error is.

49

Weird. I have no issues since days. I hope it’s working now.

The howto is wikified so you can always add what you like.

It’s already in the troubleshooting section, it’s the first point after checking the logs.

In this case the 503 error occurs if meshcentral is not started. The reason for this was more times a permission issue than a config file error yet.

2 Likes
50

When meshcentral fails to parse config.json file the error is logged in /var/log/messages (you can also find it with journalctl -e -u meshcentral):

node: ERROR: Unable to parse /opt/meshcentral/meshcentral-data/config.json.

Once you know it is a config.json error, you can more easily spot the line(s) where the error is using a json linter.

@mrmarkuz, as in the howto we do not use the MeshCentral RedirPort, I’ve disabled it setting it to 0 (already changed in the howto). That way MeshCentral starts without binding to a Redirection port.
Notice RedirPort might affect MeshCentral’s built-in letsencrypt certificate request/renewal (as noted, in the howto we are using certs handled by NethServer).

1 Like
51

I demonstrated Meshcentral to a university and they are very much interested in applying this to their IT

1 Like
52

Here’s some gathered info on logs, so we can resume it to incorporate any useful part to the howto.

Logs and debugging

Described options go into the settings section of config.json file.

Mesh Errors: it is related to the “Show server error log” on MeshCentral admin page:

"MeshErrorLogPath": "/opt/meshcentral/meshcentral-data/mesherrors.txt"

Log and Debug options log MeshCentral events from nodejs (more suited for debugging), offering a custom set of verbosity through the assigned values:

"Log": "main,web,webrequest,cert"
  • Target log is /opt/meshcentral/meshcentral-data/log.txt
"Debug": "main,web,webrequest,cert"
  • Debug option targets syslog (/var/log/messages and journalctl).

add “?trace=1” at the end of the web application URL and open the browser debug console. You will see all the WebSocket control traffic.

Another option is to use the Trace bar on MeshCentral interface.

Authentication events (could be redundant if using syslogauth option):

"AuthLog": "/opt/meshcentral/meshcentral-data/auth.log"

Syslog support. Each option can be enabled individually. Destination log is /var/log/messages:

"syslog": "meshcentral",
"syslogjson": "meshcentral-json",
"syslogauth": "meshcentral-auth"

The assigned values represent the name identifier that will be sent to syslog, they can be customized. Values can also be set to true:

"syslog": true,
"syslogjson": true,
"syslogauth": true
  • syslog: more human readable, you just get the message string
  • syslogjson: seems to override syslog option and offers a more detailed information (message string + data in json format)
  • syslogauth: authentication events

As in the howto we run MeshCentral with a restricted user, enabling syslog options cause an error:

node: ERROR: Unable to install required module “modern-syslog”. MeshCentral may not have access to npm, or npm may not have suffisent rights to load the new module. Try “npm install modern-syslog” to manualy install this module.

Manual install of modern-syslog fails:

npm ERR! modern-syslog@1.2.0 install: node-gyp rebuild
npm ERR! Exit status 1

node-gyp was missing a prerequisite. Solved with:

yum install gcc-c++    # notice it is usually not needed/advisable to have build tools on a production server
systemctl stop meshcentral
cd /opt/meshcentral
scl enable rh-nodejs10 bash
npm install modern-syslog
exit    #exit rh-nodejs10 bash session
systemctl start meshcentral
2 Likes
53

Here are some of the features related to enabling the SMTP email server. Only tried with external SMTP, so if someone wants to try it with NethServer’s own email server… :wink:

Email (smtp section)

The use of an email server (SMTP) could allow MeshCentral to verify user’s account email address by sending a confirmation request to the user to complete the account registration and for password recovery. It also allows users to enable email-two-factor authentication.

Manually install the required node module:

cd /opt/meshcentral
scl enable rh-nodejs10 bash
npm install nodemailer
exit

Add the required options to config.json:

"smtp": {
  "host": "smtp.domain.tld",
  "port": 465,
  "from": "mail@domain.tld",
  "user": "mail@domain.tld",
  "pass": "emailpassword",
  "tls": true,
  "_tlscertcheck": false,
  "_tlsstrict": true
},

Common SMTP server ports are 465, 587 and 25.
If the SMTP server requires authentication, provide the user and pass options.
Set TLS options according to your SMTP server:

  • for STARTTLS set tls option to false.
  • tlsstrict: when set to true, TLS cypher setup is more limited, SSLv2 and SSLv3 are not allowed.

(Re)start MeshCentral server:

systemctl restart meshcentral

Usage examples…

Email verification for preexisting users
Upon login, preexisting users will be requested to verify the email account through a verification link sent to its registration email:
meshcentral - reset account link meshcentral - login of preexisting user with unverified email meshcentral - login email verification email sent

User password reset through email
Use the “Reset account” link on the login screen, fill in your user registration email address to reset the account password. Once you receive the email message click on the reset link and a new password will be provided:
meshcentral - reset account link meshcentral - account reset meshcentral - account reset link provides new password

Invitation email for new account
An administrator can create a new user account and have MeshCentral send an invitation email to the user. The email contains a temporary password that must be changed upon first login:
meshcentral - New account with email options
meshcentral - email new account invitation
msehcentral - password change requested

2FA by email
From “My account” page, each user can enable Email Authentication:
meshcentral - email authentication meshcentral - email 2fa info message

Users can create backup codes for 2fa:
meshcentral - 2fa - manage backup codes

Once 2FA by email is enabled, the login process is like this:
meshcentral - login meshcentral - email 2fa - login token request meshcentral - email 2fa - Email button - Send token to email meshcentral - email message with login token meshcentral - email 2fa - email sent - login token requested

Agent Email Invitation
An email invitation with instructions on how to install/run the software agent can be send by MeshCentral:
meshcentral - my devices - Invite - Email invitation

3 Likes
54

Agent Invite Codes
Add AgentInviteCodes: true in the domain section (either in the default "" domain or within a custom(er) domain if any).

Invite Codes feature will be made available to device groups.
meshcentral - agent invite codes
Any user can visit the invite page (https://server.domain.tld/invite), enter the code and get agent installation instructions.

You can add ?c=abc to the invite URL to pre-fill the invitation code. For example: https://server.domain.tld/invite?c=abc

4 Likes
55

About the “Minify” setting:

as of MeshCentral v0.5.22, the “minify” setting is moved to the domain section, put "minify":true . You can also override this setting with &minify=1 or &minify=0 in the URL and minification is much more effective now, saving over 1 megabyte of downloads on the main web app and works correctly for all languages.
Info Source

Regarding SelfUpdate settings, won’t work when using an “increased security installation” as in the howto.

3 Likes
56

i saw you @dnutan contributing to the project github code.

57

Well, just contributing reporting little things noted while testing.

58

Session Recording

In the domains section of config.json add this to the desired domain:

  "SessionRecording": {
    "_filepath": "/opt/meshcentral/meshcentral-recordings",
    "index": true,
    "_maxRecordings": 100,
    "_maxRecordingSizeMegabytes": 100,
    "__protocols__": "Is an array: 1 = Terminal, 2 = Desktop, 5 = Files, 100 = Intel AMT WSMAN, 101 = Intel AMT Redirection",
    "protocols": [ 1, 2, 101 ]
  }
  • filepath: if not enabled, defaults to meshcentral-recordings on main meshcentral installation directory.
  • index : when set to true, the remote desktop recording files will be indexed every 10 seconds.

node: ERROR: Unable to install required module “image-size”. MeshCentral may not have access to npm, or npm may not have suffisent rights to load the new module. Try “npm install image-size” to manualy install this module.

Manually install the required node module:

cd /opt/meshcentral
scl enable rh-nodejs10 bash
npm install image-size
exit

Once the option is enabled, MeshCentral server that already acts as a traffic relay between the browser, agents and Intel AMT will now record traffic automatically. Notice that if WebRTC support is enabled, the browser and agent will attempt to setup a direct connection to bypass the server. If successful, the server will no longer relay the traffic and will no longer record anything.

An indicator shows when recording is active:
meshcentral - session recording

Recordings will be saved in .mcrec file format, encoding session metadata along with traffic time, direction and in the case of web socket, the traffic data type. This file format is a re-playable TCP/Web Socket session, suitable for auditing.

Indexing is done in a separate process from the main MeshCentral server. Indexing works by recording the network traffic and adding timestamps and direction flags when writing the stream to a file. Indexing occurs after saving the file and the index is appended at the end of it. Also, there is a mcrec.js file in the MeshCentral folder you can run manually as a command line tool to index an existing .mcrec file.

MeshCentral Session Player is a web application that can take in a .mcrec and play it back. The player is accessible at /player or at /player.htm.

There is a “Recordings” panel in the “My Users” section that can be viewed by administrators.

In addition to being able to record server side, users can now record browser side with a recording button (recording camera icon) on the bottom right of the remote desktop screen.
meshcentral - session recording - camera icon to access player
It allows users to start and stop recording at any point in the session and play the recorded portion back on the web-based session player.
session recording - camera icon contextual menu

References

Note: at the moment of writing, the player doesn’t play recordings from server-side, in order to play them you have to download the recordings and open them with the player.
The player appears to be publicly accessible.

3 Likes
59

i just discovered that if you disable root login on the nethserver interface, you can still be able to login into the server using Meshcentral. this is cool, especially fo security reasons.

What i am curious about is, how can i also disable cockpit and nethserver /9090 and /980 access. and enable it through ssh?

EDIT: its not paranoi, just assesing different ways to secure server

60

You may disable the server manager wan access in the System settings:

image

The legacy server manager access can be disabled in Services, just unset red and keep green:

image

Check the wiki for using an ssh tunnel to access the server manager:

Settings for Windows putty/kitty:

image