MeshCentral 1.3.1

In the AWS Marketplace listing, choose Continue to Subscribe, then Continue to Configuration. Pick MeshCentral 1.3.1 on Ubuntu 24.04 as the software version, choose your Region, then choose Launch through EC2.

Choose m5.large, your key pair, a subnet and a security group as described above. A t3.medium serves a few dozen devices well. Add memory as the number of devices and remote sessions grows.

Attach an Elastic IP. Agents connect to the server's name or address, so it should never change.

With the AWS CLI, replace the values in angle brackets:

aws ec2 run-instances --region <region> --image-id <ami-id-from-the-listing> \
  --instance-type m5.large --key-name <your-key-pair> \
  --security-group-ids <your-security-group> --subnet-id <your-subnet> \
  --metadata-options HttpTokens=required,HttpEndpoint=enabled \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=meshcentral}]'

Version SSH user

MeshCentral 1.3.1 on Ubuntu 24.04 ubuntu

ssh -i <your-key.pem> ubuntu@<public-ip>

First boot reads the instance's public address from EC2 instance metadata, generates the certificate, creates the admin account and writes the credentials file. The egress backstop then loads, and MeshCentral and nginx start:

systemctl is-active sac-meshcentral-egress meshcentral nginx
sudo test -f /var/lib/sac/data/meshcentral-firstboot.done && echo FIRSTBOOT_DONE

All three units are active, and the first-boot marker is present:

active active active FIRSTBOOT_DONE

Only SSH and nginx listen on the network. MeshCentral (the node process) listens on localhost only:

sudo ss -lntpH | awk '{print $4, $6}' | sed -E 's/users:\(\("([^"]+)".*/\1/' | grep -v '127.0.0.5' | sort -u

0.0.0.0:22 sshd 0.0.0.0:443 nginx 0.0.0.0:80 nginx 127.0.0.1:4430 node [::]:22 sshd [::]:443 nginx [::]:80 nginx

Read the credentials file:

sudo cat /root/meshcentral-credentials.txt

Only root can read the file. It holds the URL, the user name, the password and the certificate's fingerprint:

# MeshCentral 1.3.1 (sac) on this instance. Open MESHCENTRAL_URL in a browser and sign in as MESHCENTRAL_USERNAME / MESHCENTRAL_PASSWORD.
# The password is unique to this instance. Change it in the web UI (My Account), or:
sudo meshcentral-set-password (--stdin to choose one).
# The certificate is self-signed for this instance: compare its SHA-256 fingerprint with MESHCENTRAL_TLS_SHA256.
# Set your DNS name BEFORE deploying agents:
sudo meshcentral-set-domain mesh.example.com MESHCENTRAL_URL=https://<public-ip>/ MESHCENTRAL_HOST=<public-ip> MESHCENTRAL_USERNAME=admin MESHCENTRAL_PASSWORD=<MESHCENTRAL_PASSWORD> MESHCENTRAL_TLS_SHA256=<64 hex digits, colon separated> MESHCENTRAL_ADDRESS_SOURCE=imdsv2-public-ipv4 GUIDE=https://secureanycloud.com/stacks/meshcentral-1-3-1/

MESHCENTRAL_ADDRESS_SOURCE says where the address came from. It is the public IPv4 address from instance metadata, or the private address when the instance has no public one.

The image includes a self-test. It runs through nginx, pinned to this instance's certificate. It checks that the sign-in page loads, that a wrong password is refused, that the admin password signs in, and that the agent endpoint accepts a WebSocket:

sudo meshcentral-selftest

meshcentral-selftest: sign-in page ok; a wrong password refused; the admin password signs in; /agent.ashx upgrades (101) MESHCENTRAL_SELFTEST_OK

Every agent MeshCentral builds carries the server's name and the fingerprint of MeshCentral's own server key, and connects only to that name. Agents installed while the server is known by its IP address keep looking for that address.

So, before you add your first device, point a DNS A record (for example mesh.example.com) at the instance's Elastic IP and run:

sudo meshcentral-set-domain <your-domain>

meshcentral-set-domain: nginx for <your-domain> localhost 127.0.0.1 meshcentral-set-domain: TLS certificate for <your-domain> (SAN DNS:<your-domain>,DNS:localhost,IP:127.0.0.1) meshcentral-set-domain: MeshCentral settings.cert = <your-domain> (/etc/meshcentral/config.json) meshcentral-set-domain: restarted MeshCentral and nginx meshcentral-set-domain: https://<your-domain>/ (also served: localhost 127.0.0.1). Agents you deploy from now on connect to wss://<your-domain>/agent.ashx

This command sets the name nginx accepts and generates a new self-signed certificate for it. It also sets MeshCentral's settings.cert, and updates MESHCENTRAL_URL, MESHCENTRAL_HOST and MESHCENTRAL_TLS_SHA256 in the credentials file.

Add more names or addresses after the first to serve them too (sudo meshcentral-set-domain <your-domain> <elastic-ip>). If you keep using the IP address, use an Elastic IP so it never changes.

For a certificate your browser trusts, put the certificate chain for <your-domain> in /etc/ssl/meshcentral/meshcentral.crt. Put its private key in /etc/ssl/meshcentral/meshcentral.key (root only, mode 600). Then run sudo meshcentral-set-domain --keep-cert <your-domain>. It checks that the certificate covers the name and gives MeshCentral its copy of the certificate.

The endpoints your devices use, all on port 443 of <your-domain>:

Endpoint Used by

https://<your-domain>/ the web interface (administrators and users)

wss://<your-domain>/agent.ashx the agent on each device (one long-lived WebSocket)

wss://<your-domain>/meshrelay.ashx remote desktop, terminal and file sessions, relayed between your browser and the device

https://<your-domain>/meshagents the agent downloads and install scripts behind Add Agent

Open MESHCENTRAL_URL in your browser. The certificate is self-signed for your instance, so the browser warns once.

To check that you are talking to your instance, open the certificate details and compare its SHA-256 fingerprint with MESHCENTRAL_TLS_SHA256. Then continue.

Sign in as admin with MESHCENTRAL_PASSWORD. The sign-in page offers no way to create an account.

Turn on two-factor sign-in now. Open My Account (the second icon on the left). Choose Manage authenticator app to add a time-based one-time password, or Manage security keys for a hardware key. Change password on the same page changes the admin password.

Devices belong to device groups, and permissions are given per group.

On My Devices, choose click here to create a device group (later, Add Device Group). Give it a name, keep the type Manage using a software agent, and choose OK.

Choose Add Agent next to the group, then pick the device's operating system. For Windows, download the agent .exe and run it on the device. For Linux or BSD, copy the command and run it on the device as root. The agent and its install script are downloaded from your server and carry its name, its certificate fingerprint and the group.

Within a few seconds of installing, the device appears in its group as online.

Click a device to open it. General shows its group, operating system, agent and the logged-in user. It has buttons to run commands, send a message, chat or share the device.

The tabs across the top open a remote Terminal, a remote Desktop on devices with a desktop, the device's Files, its installed Software, its Events and hardware Details.

Remote sessions are relayed through your server on port 443 (/meshrelay.ashx). Neither your browser nor the device needs any other port open.

Users. Give each person their own account rather than sharing admin. As admin, open My Users (the fifth icon) and choose Add User. Then give the user rights on a device group from the group's page. Each user signs in with their own password and can add two-factor sign-in.

Your server. My Server (the last icon) shows the server's load, memory, and connected agents and sessions. It also holds Download server backup, Restore server with backup, the server's error log and its configuration.

Change the admin password in the web interface (My Account, Change password), or on the instance.

To generate a new random password, run the command below. It writes the password to the credentials file as MESHCENTRAL_PASSWORD:

sudo meshcentral-set-password

To choose your own password, use the command below. It must be 16 characters or more, and it is read from standard input and not stored on the instance:

sudo meshcentral-set-password --stdin

meshcentral-set-password: the admin password was changed

meshcentral-set-password is also the way back in if you are locked out, or if admin has lost its two-factor device. It unlocks the account and removes its two-factor methods.

It restarts MeshCentral, which disconnects the agents for a few seconds. They reconnect on their own.

MeshCentral reads /etc/meshcentral/config.json, which is owned by root:

sudo jq -c '{settings: .settings | {cert, port, aliasPort, portBind, redirPort, mpsPort, tlsOffload, trustedProxy, WANonly, maxInvalidLogin, autoBackup}, domain: .domains[""] | {title, title2, newAccounts}}' /etc/meshcentral/config.json

{"settings":{"cert":"<public-ip>","port":4430,"aliasPort":443,"portBind":"127.0.0.1","redirPort":0,"mpsPort":0,"tlsOffload":"127.0.0.1","trustedProxy":"127.0.0.1","WANonly":true,"maxInvalidLogin":{"time":10,"count":10,"coolofftime":10},"autoBackup":{"backupPath":"/var/lib/meshcentral/backups","backupIntervalHours":24,"keepLastDaysBackup":10}},"domain":{"title":"MeshCentral","title2":"sac","newAccounts":false}}

Edit it with sudo nano /etc/meshcentral/config.json, then run sudo systemctl restart meshcentral. Every MeshCentral setting is in the configuration reference. Email (smtp), for example, lets MeshCentral send invitations and notifications.

Keep newAccounts false.

MeshCentral refuses to start, and journalctl -u meshcentral says why, when any of these is true:

• cert is not your server's name (meshcentral-set-domain sets it).
• port is not 4430.
• portBind or tlsOffload is not 127.0.0.1.
• redirPort is not 0.
• letsencrypt is set.

nginx holds the certificate and is the only way in.

MeshCentral, nginx and the first-boot service are refused any connection to the instance metadata service. The meshcentral and www-data accounts are refused link-local, private, carrier-grade NAT, reserved and multicast addresses, your VPC's own address ranges (read from instance metadata on every boot), and all IPv6 except localhost.

Your devices connect in to MeshCentral, so it needs no internal address for normal use.

The allow list is empty by default:

sed -n '1,6p' /etc/sac/meshcentral-egress-allow

# sac MeshCentral egress allow-list (empty by default).
# Managed devices reach MeshCentral INBOUND (their agents connect to this server on 443), so MeshCentral needs no internal
# address for normal use. MeshCentral itself opens connections to a private network only for Intel AMT devices managed over
# the LAN (ports 16992-16995), Wake-on-LAN relays or an internal SMTP/LDAP server: list such a network here, one CIDR per line - it must lie inside 10.0.0.0/8,
# 172.16.0.0/12, 192.168.0.0/16, 100.64.0.0/10 or fc00::/7 (metadata and link-local addresses can never be allowed) -
# then run:
sudo systemctl reload sac-meshcentral-egress

The instance metadata service can never be allowed.

The commands below check that:

• Self-registration is refused.
• A sign-in or WebSocket from another site's page is refused.
• Agents connect.
• The health check needs no password.
• A host name the instance does not serve gets no answer.
• Plain HTTP redirects.
• Other local accounts cannot reach MeshCentral directly.

H=$(sudo sed -n 's/^MESHCENTRAL_HOST=//p' /root/meshcentral-credentials.txt); WRONG="not-the-password" curl -sk -o /dev/null -w 'sign-in page: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/" curl -sk -o /dev/null -w 'create an account: %{http_code}\n' --resolve "$H:443:127.0.0.1" -X POST -H "Origin: https://$H" -d action=createaccount -d username=intruder -d email=x@example.com -d password1=Aa1-$WRONG -d password2=Aa1-$WRONG "https://$H/createaccount" curl -sk -o /dev/null -w 'sign-in POST from another site: %{http_code}\n' --resolve "$H:443:127.0.0.1" -X POST -H 'Origin: https://evil.example' -d action=login -d username=admin -d password=x "https://$H/login" curl -sk -o /dev/null -w 'WebSocket from another site: %{http_code}\n' --http1.1 --resolve "$H:443:127.0.0.1" -H 'Connection: Upgrade' -H 'Upgrade: websocket' -H 'Sec-WebSocket-Version: 13' -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" -H 'Origin: https://evil.example' -m 5 "https://$H/control.ashx" curl -sk -o /dev/null -w 'agent endpoint: %{http_code}\n' --http1.1 --resolve "$H:443:127.0.0.1" -H 'Connection: Upgrade' -H 'Upgrade: websocket' -H 'Sec-WebSocket-Version: 13' -H "Sec-WebSocket-Key: $(openssl rand -base64 16)" -m 5 "https://$H/agent.ashx" || true curl -sk -o /dev/null -w 'health check: %{http_code}\n' --resolve "$H:443:127.0.0.1" "https://$H/healthz" curl -sk -o /dev/null -w 'unknown host name: %{http_code}\n' --resolve evil.example:443:127.0.0.1 https://evil.example/ || true curl -s -o /dev/null -w 'http: %{http_code}\n' --resolve "$H:80:127.0.0.1" "http://$H/" curl -s -m 5 -o /dev/null -w 'MeshCentral directly, as ubuntu: %{http_code}\n' http://127.0.0.1:4430/ || true

sign-in page: 200 create an account: 401 sign-in POST from another site: 403 WebSocket from another site: 403 agent endpoint: 101 health check: 200 unknown host name: 000 http: 301 MeshCentral directly, as ubuntu: 000

MeshCentral and nginx are blocked from the instance metadata service and reserved addresses:

for u in meshcentral nginx; do printf '%s ' "$u"; systemctl show -p IPAddressDeny --value "$u" | tr ' ' '\n' | sort | tr '\n' ' '; echo; done
sudo -u meshcentral curl -s -m 5 -o /dev/null -w 'metadata from the meshcentral account: %{http_code}\n' http://169.254.169.254/latest/meta-data/ || true

meshcentral 168.63.129.16/32 169.254.169.254/32 192.0.0.0/24 198.18.0.0/15 2001::/32 2002::/16 224.0.0.0/4 240.0.0.0/4 64:ff9b:1::/48 64:ff9b::/96 ::ffff:0.0.0.0/96 fd00:ec2::254/128 nginx 168.63.129.16/32 169.254.169.254/32 192.0.0.0/24 198.18.0.0/15 2001::/32 2002::/16 224.0.0.0/4 240.0.0.0/4 64:ff9b:1::/48 64:ff9b::/96 ::ffff:0.0.0.0/96 fd00:ec2::254/128 metadata from the meshcentral account: 000

The egress backstop refuses the private ranges and your VPC. It reads the VPC's ranges on every boot:

sudo iptables -S SAC-MESHCENTRAL-EGRESS | sed -n '1,4p' cat /run/sac/meshcentral-vpc-cidrs

-N SAC-MESHCENTRAL-EGRESS -A SAC-MESHCENTRAL-EGRESS -d 127.0.0.0/8 -o lo -j RETURN -A SAC-MESHCENTRAL-EGRESS -d 169.254.0.0/16 -p tcp -j REJECT --reject-with tcp-reset -A SAC-MESHCENTRAL-EGRESS -d 169.254.0.0/16 -j REJECT --reject-with icmp-admin-prohibited <your VPC CIDR, for example 172.31.0.0/16>

MeshCentral (its launcher and the server process it starts) runs as meshcentral, on localhost, with no Linux capabilities. It cannot gain any:

P=$(systemctl show -p MainPID --value meshcentral) ps -o user:11=,args= --ppid "$P" -p "$P" for p in $P $(pgrep -P "$P"); do
sudo grep -E '^(CapEff|CapBnd|CapAmb|NoNewPrivs)' /proc/"$p"/status | tr '\n' ' '; echo; done

meshcentral /usr/bin/node /opt/meshcentral/node_modules/meshcentral/meshcentral.js --datapath /var/lib/meshcentral/data meshcentral /usr/bin/node --disable-proto=delete /opt/meshcentral/node_modules/meshcentral/meshcentral.js --datapath /var/lib/meshcentral/data --launch <pid> CapEff: 0000000000000000 CapBnd: 0000000000000000 CapAmb: 0000000000000000 NoNewPrivs: 1 CapEff: 0000000000000000 CapBnd: 0000000000000000 CapAmb: 0000000000000000 NoNewPrivs: 1

Only their owners can read the credentials, the TLS key and MeshCentral's database:

sudo stat -c '%a %U:%G %n' /root/meshcentral-credentials.txt /etc/ssl/meshcentral/meshcentral.key /etc/meshcentral/config.json /var/lib/meshcentral/data/meshcentral.db /var/lib/meshcentral/data /var/lib/meshcentral/backups

600 root:root /root/meshcentral-credentials.txt 600 root:root /etc/ssl/meshcentral/meshcentral.key 644 root:root /etc/meshcentral/config.json 600 meshcentral:meshcentral /var/lib/meshcentral/data/meshcentral.db 700 meshcentral:meshcentral /var/lib/meshcentral/data 700 meshcentral:meshcentral /var/lib/meshcentral/backups

Other notes:

• Lockout. After 10 failed sign-ins from one IPv4 /24 range in 10 minutes, MeshCentral refuses sign-in from every address in that range for 10 minutes, even with the right password. This is MeshCentral's default iprange blocking, and an IPv6 client is counted by its own address. Colleagues who share an office network therefore share the lockout. Restarting MeshCentral (sudo systemctl restart meshcentral, or sudo meshcentral-set-password) clears it at once.
• Rate limits. The sign-in limit (30 a minute, bursts of 20) counts every request other than a page or download (GET), every WebSocket, and any request that carries credentials. That means an x-meshauth header, or an auth, user or pass query parameter in any spelling (any case, bracketed or percent-encoded). So GET /?user=...&pass=... and the browser's own remote-session relays count too. Only the agents' own connections are treated differently, and only when they carry nothing but the query parameters MeshCentral's agents use. /agent.ashx is not limited, because agents authenticate with their certificate. The agent side of /meshrelay.ashx and /agenttransfer.ashx has its own limit of 120 a minute, with bursts of 120. The burst of 20 covers normal use: each page load opens one control channel, and each remote desktop, terminal or files session opens one relay. A script that signs in or posts in a tight loop from one address gets 429. Slow it to one request every two seconds. Many administrators behind one shared address share the limit.
• Client addresses. nginx replaces any X-Forwarded-For or X-Real-IP a client sends with the address it connected from. MeshCentral's lockout, its IP filters and its logs therefore see the real client. nginx keeps no query strings, where MeshCentral puts session tokens, in its access log.
• The account database fails closed. Before MeshCentral starts, the image checks its database /var/lib/meshcentral/data/meshcentral.db. If the file is missing, unreadable, damaged or holds no account, MeshCentral stays stopped and the journal says why (journalctl -u meshcentral), rather than let the first visitor create an administrator. Restore the database from a backup (Step 13) and start it.
• Program files. MeshCentral cannot write to /opt/meshcentral, so its own update button cannot change it. New versions arrive as new versions of this listing (Step 14).
• Intel AMT. The Intel AMT management port (4433) is off. To manage AMT devices, see the MeshCentral documentation, and open the port in config.json and your security group.
• NVMe host identity. No NVMe-oF host identity ships in the image. If you install nvme-cli, its host NQN and host ID are your instance's own.
• Who can reach it. Keep port 22 open only to your own networks. Port 443 must be open to your devices, so open it no wider than they need.
• Logs. nginx logs are in /var/log/nginx. MeshCentral logs to the journal (journalctl -u meshcentral) and keeps its event log in its database (Events in the web interface).

MeshCentral writes a backup of its database every 24 hours to /var/lib/meshcentral/backups and keeps the last 10 days. My Server, Download server backup downloads one now, and Restore server with backup restores one.

Copy the backups off the instance regularly:

ssh -i <your-key.pem> ubuntu@<public-ip> 'sudo tar -C /var/lib/meshcentral -czf - backups' > meshcentral-backups.tar.gz

The data directory /var/lib/meshcentral/data also holds MeshCentral's own server keys, which the agents trust. Keep an EBS snapshot of the instance's volume as well, because it is a complete backup.

To apply Ubuntu updates now:

sudo apt-get update && sudo apt-get upgrade -y

New MeshCentral releases arrive as new versions of this listing, built and checked the same way. Read the MeshCentral release notes before you move.

Your agents keep working across a move when the new server has the same name, the same server keys (the data directory) and the database. Restore a backup on the new version, or move the data directory.