Roll out MoorNest with your RMM

An install code works once and needs someone at the server to type it. When you add many servers at once, from an RMM tool, a Group Policy startup script or a server image, use a provisioning token instead. You create it once in the console, give it to your script as a secret, and every server that runs the script registers itself with no prompts.

A provisioning token only adds servers. It cannot restore, read, change or delete backups, and a server it adds has exactly the same access as one added with an install code. Restores still need an administrator.

Before you start

• You need the Administrator role with your authenticator app set up. Creating a token asks for your password and a fresh code.
• Each server needs outbound HTTPS (port 443) to app.moornest.com, the same as a normal install. See Add a server.
• The script must run with administrator rights: as SYSTEM (most RMM tools, Group Policy startup scripts) or an elevated prompt on Windows, and as root on Linux.

Step 1: create a provisioning token

1. In the console, open Settings > Server rollout and click Create token. The Add server page links here too: Use a provisioning token.
2. Choose: - Adds servers to: the client the servers belong to (workspaces with clients only). A token can never add servers to another client or another organization. - Server type: File servers or Hyper-V hosts. A Hyper-V token is refused on a server without Hyper-V, and a File server token leaves Hyper-V backups off even on a Hyper-V host. - Expires after: 1 to 30 days. Pick the shortest time your rollout needs. - Most servers it can add: a limit, or 0 for no limit until it expires. - Default storage and Default schedule (optional): what Set up backup starts from for these servers. Folders and VMs are still chosen per server after it connects.
3. Confirm with your password and a fresh code.

The console shows the token once. It looks like mnpt1.yourorg.0123abcd.... Copy it into your RMM's secret or password field, or download it as a file. MoorNest keeps only a fingerprint of it and cannot show it again. If you lose it, revoke it and create another.

Step 2: run the installer with the token

The installer reads the token from a file (-token-file PATH) or from the MOORNEST_PROVISIONING_TOKEN environment variable. It never accepts the token on the command line, where other users, process lists and RMM job logs could see it.

Windows: RMM script running as SYSTEM

Put the token in your RMM's secret variable (shown here as {{MoorNestToken}}; use your RMM's own syntax), then run this PowerShell script:

$ErrorActionPreference = 'Stop'
[Net.ServicePointManager]::SecurityProtocol = 'Tls12'
$exe = Join-Path $env:ProgramFiles 'MoorNest-setup\moornest-agent.exe'
New-Item -ItemType Directory -Force -Path (Split-Path $exe) | Out-Null
Invoke-WebRequest -UseBasicParsing https://app.moornest.com/downloads/moornest-agent-windows-amd64.exe -OutFile $exe
$sig = Get-AuthenticodeSignature $exe
if ($sig.Status -ne 'Valid' -or $sig.SignerCertificate.Subject -notmatch '(^|, )CN=DevSmooth Software Inc\.(,|$)') { throw 'moornest-agent.exe is not signed by DevSmooth Software Inc.' }
$env:MOORNEST_PROVISIONING_TOKEN = '{{MoorNestToken}}'
& $exe install
$code = $LASTEXITCODE
Remove-Item Env:\MOORNEST_PROVISIONING_TOKEN -ErrorAction SilentlyContinue
exit $code

The script runs the agent only if Windows confirms its Authenticode signature from DevSmooth Software Inc. (see Check a download before you run it). The signature status must be Valid. If it is not, check the server's root certificates first: an offline server, or one with automatic root certificate updates turned off, must get its root certificates updated before the check can pass.

Keep the setup copy under Program Files, as here, or another folder only administrators can write to. Not under ProgramData or a temp folder: ordinary users can create files there, and a program they plant would run as SYSTEM.

The installer removes the variable from its own environment as soon as it reads it, and the script removes it from PowerShell's. The installer never prints the token.

Windows: Group Policy startup script

Startup scripts run as SYSTEM on every boot. Save the token in a file on a share that only Domain Computers and your administrators can read, then use this as the startup script (PowerShell):

[Net.ServicePointManager]::SecurityProtocol = 'Tls12'
$exe = Join-Path $env:ProgramFiles 'MoorNest-setup\moornest-agent.exe'
if (-not (Test-Path $exe)) {
  New-Item -ItemType Directory -Force -Path (Split-Path $exe) | Out-Null
  Invoke-WebRequest -UseBasicParsing https://app.moornest.com/downloads/moornest-agent-windows-amd64.exe -OutFile $exe
}
$sig = Get-AuthenticodeSignature $exe
if ($sig.Status -ne 'Valid' -or $sig.SignerCertificate.Subject -notmatch '(^|, )CN=DevSmooth Software Inc\.(,|$)') { exit 1 }
& $exe install -token-file '\\corp.example\NETLOGON\moornest\token.txt'
exit $LASTEXITCODE

On a server that is already registered, running the same installer again changes nothing and exits with 0, so it is safe on every boot. Remove the policy and the file once the rollout is done.

Linux

As root, with the token in your tool's secret variable MOORNEST_TOKEN:

set -eu
dir=$(mktemp -d)
cd "$dir"
curl --retry 5 -fsSLO https://app.moornest.com/downloads/moornest-agent-linux-amd64
curl --retry 5 -fsSLO https://app.moornest.com/downloads/moornest-agent-linux-amd64.sha256
sha256sum -c moornest-agent-linux-amd64.sha256
chmod +x moornest-agent-linux-amd64
printf '%s\n' "$MOORNEST_TOKEN" | ./moornest-agent-linux-amd64 install -token-file -
cd /
rm -rf "$dir"

-token-file - reads the token from standard input, and printf is built into the shell, so the token never appears in the process list. The script stops before running anything if the download does not match its SHA-256 checksum. --retry 5 makes curl wait and try again when MoorNest is busy with other downloads, which happens when many servers run the script at once. To check the MoorNest release signature too, for example when you bake the agent into an image, see Check a download before you run it.

Server images and first-boot tasks

Bake the downloaded agent into the image, not the token. At first boot, have your provisioning tool (cloud-init, a scheduled task, your deployment system) write the token to a file readable only by root or SYSTEM, run moornest-agent install -token-file PATH, then delete the file. Use a token with a short expiry and a use limit that matches the number of machines.

Self-hosted MoorNest

Add -server https://your-director.example (and -ca FILE for a private CA), as for a normal install.

Check the result

Each server shows up in the console as soon as it registers, named after its computer name. Open it and choose what to back up; Set up backup starts from the token's default storage and schedule.

Every server a token adds is recorded in Settings > Audit log with the token and the server's computer name. Settings > Server rollout shows how many servers each token has added.

Installs MoorNest refuses are recorded there too: a revoked, expired or used-up token that is still being tried shows as "refuse server install with provisioning token ..." with the reason, the computer name and the address it came from. To keep the log readable, a token gets at most one such entry an hour; a later entry says how many more were refused in between and where the last one came from. Attempts turned away because too many arrived at once (the installer is told to wait a minute) are not recorded. Attempts with a token MoorNest does not recognise are grouped the same way into one entry an hour for the whole workspace. The token itself is never written to the log.

Exit codes

Use these in your RMM to tell a real failure from a retry later.

If a run fails after the server registered (for example the service could not start), fix the problem and run the same script again. Within 15 minutes, a server that never connected is registered again in place, not twice, and does not use up another of the token's servers. After that, a new run adds it as a new server; remove the old entry that never connected.

On a server that is already registered, a token install changes nothing, even if the download is older or newer than the installed agent. Update agents from MoorNest (see Agent updates). To register a server again, add -replace; that adds it as a new server and counts as one more use.

Large rollouts

You can start the script on a few hundred servers at once. MoorNest accepts up to 300 installs a minute through one token, and up to 300 a minute from one public address, so servers behind the same office or datacentre address are fine too. The total is still capped by the number of servers your plan allows.

If MoorNest asks an installer to wait, newer agents wait and try again by themselves, up to three times over about four minutes, before exiting with 4. Code 4 is always safe to retry: re-run the script for those servers, or let your RMM retry failed jobs after a few minutes. For rollouts of more than 300 servers, run them in batches of up to 200 a minute.

A computer that keeps sending wrong tokens or codes is made to wait a minute. That affects only its own public address, not the rest of the rollout.

Expiry and revocation

• A token stops working when it expires, when it has added its maximum number of servers, or when you revoke it in Settings > Server rollout. Revoking needs no authenticator code, so you can act at once if a token leaks.
• Servers a token already added keep working after it expires or is revoked.
• A token is revoked if the administrator who created it is disabled or is no longer an administrator. Turning the account back on does not bring the token back; create a new one. Changing that administrator's password does not affect it.
• Revoke each token as soon as its rollout is done.

Asking for codes less often

By default MoorNest asks for a fresh authenticator code on every sensitive change, including creating an install code and starting a restore. An administrator can turn this off for Adding servers or Restores in Settings > Sign-in and security > Ask for a fresh code (see Sign in and two-factor). Exporting recovery keys, allowing restores to a server, people and roles, storage and keys, removing servers, provisioning tokens and those settings themselves always ask. Updating agents needs no code unless a server is set to require one (Server details > Fresh code for updates).