Deploy an installer file from the file server
Create an App Hub app that runs an MSI, EXE, MSU, PowerShell, DEB, RPM, shell or PKG file from the file server, with arguments per action, a detection script and a pinned SHA-512.
Deploy an installer file from the file server
Many installers are not in Winget, Chocolatey or Flathub and are not worth wrapping in a script: a vendor MSI, a setup EXE, a Windows update package, a .deb or .rpm from a supplier, a macOS .pkg. For those, App Hub has the source File from the file server. You upload the file to the File Server once, pick it in the app, set the arguments for install, update and uninstall, and add a detection script. Software Deployment, the tray icon's App Hub and auto-update then run exactly that file on the devices.
The app stores the SHA-512 of the file when you pick it. A device downloads the file, compares its SHA-512 with the stored value and starts it only when both match. A file that was replaced or changed on the server is never run.
Before you start
- Permissions:
collections_app_hub_enabledandcollections_app_hub_addto create the app,collections_app_hub_manageto edit it, andfile_server_enabledto choose or change its file. Uploading a new file from the dialog needsfile_server_add. - The file lies on the File Server (
Collections → Files, see 9.1 File Server). Files belownetlock/and files collected from devices (belowdevices/) cannot be chosen. - You know the silent switches of the installer.
- File apps always run as the agent:
SYSTEMon Windows,rooton Linux and macOS. There is no interactive user, so the installer must run without any question.
File types
The extension of the chosen file decides how the agent starts it. Only the types of the app's target system can be chosen.
| System | Extension | Started as | Prefilled arguments | Uninstall with the file | Success | Success, restart required |
|---|---|---|---|---|---|---|
| Windows | .msi | msiexec.exe /i "<file>" <arguments> | /qn /norestart | yes, msiexec.exe /x "<file>" <arguments> | 0 | 3010, 1641 |
| Windows | .exe | "<file>" <arguments> | — | yes | 0 | 3010, 1641 |
| Windows | .msu | wusa.exe "<file>" <arguments> | /quiet /norestart | no (use a script) | 0, 2359302 (already installed) | 3010, 1641 |
| Windows | .ps1 | powershell.exe -NoProfile -NonInteractive -ExecutionPolicy Bypass -File "<file>" <arguments> | — | yes | 0 | 3010, 1641 |
| Linux | .deb | apt-get install -y <file> <arguments> (without apt: dpkg -i) | — | no (use a script) | 0 | — |
| Linux | .rpm | dnf install -y <file> <arguments> (otherwise yum, zypper --non-interactive install or rpm -Uvh) | — | no (use a script) | 0 | — |
| Linux | .sh | /bin/bash <file> <arguments> | — | yes | 0 | — |
| macOS | .pkg | /usr/sbin/installer -pkg <file> -target / <arguments> | — | no (use a script) | 0 | — |
The programs are started by their full path and never through a shell. Every other exit code is a failure. One start may take up to 60 minutes; after that it is stopped and reported as Timeout.
Create the app
- Upload the installer under
Collections → Filesif it is not there yet. You can also upload it from the file dialog in step 5. - Open
Collections → App Huband clickAdd. - Fill in
NameandVersion(required for file apps; it is compared with the version the detection script reports). - Under Source, choose
File from the file server. The option is available with the permissionfile_server_enabled. - Click
Choose fileand select the installer. Only the types the source supports can be selected; thenetlockanddevicesfolders are not offered. The dialog shows the file name and itsSHA-512, with a copy button. The target system follows the file type: an.msimakes a Windows app, a.deba Linux app, a.pkga macOS app. - Enter the arguments per action (see below).
Command the agent runsbelow the fields shows the resulting command. - Choose the uninstall mode under
Uninstall. - Write the
Detection Script (required). - A file app always runs as SYSTEM or root; the elevation switch is on and locked.
- Click
Confirm.
Edit the app
Edit App shows the same block. Without a new choice, the app keeps the file and the SHA-512 it pinned. If the file on the file server is missing or was replaced since it was chosen, the dialog asks you to choose the file again before you can save; choosing a file pins its current SHA-512. Changing the file, the arguments or the uninstall mode needs file_server_enabled. Saving the app also updates the pending deployments that use it and have not started on any device yet; a deployment that has started keeps what it started with.
Arguments
There are three argument fields:
Install arguments: used for an install.Update arguments: used for an update. Leave it empty to use the install arguments.Uninstall arguments: used when the uninstall mode isThis file with arguments.
Each field holds up to 2048 characters on one line. Line breaks and other control characters are refused.
On Windows, the arguments are appended to the command line exactly as you type them, without a shell. Quotes work the way the installer expects them. For example, INSTALLDIR="C:\Program Files\Contoso" for msiexec, or /D=C:\Program Files\Contoso for NSIS. Characters such as &, | and > have no special meaning. On Linux and macOS, the arguments are split like a command line, with quotes grouping words, and passed to the program without a shell.
The Template menu next to the install field fills in common silent switches for the type of the chosen file:
| Installer | Arguments |
|---|---|
| MSI | /qn /norestart |
| Inno Setup | /VERYSILENT /SUPPRESSMSGBOXES /NORESTART /SP- |
| NSIS | /S |
| InstallShield | /s /v"/qn /norestart" |
| MSU | /quiet /norestart |
For MSI, the agent adds /L*v with a log file of its own when the arguments do not name a log. For a failed run, the result contains the part of that log around the first failed action (Return value 3) and its last lines.
The hash pins only the chosen file. The arguments are part of what you approve: they can make the installer load something else. Examples are
TRANSFORMS=orPATCH=with msiexec, a second/i, additional package names with apt-get, dnf or zypper, or a second-pkgwithinstaller. Such additional files are not covered by the SHA-512 of the app. Keep the arguments to the switches the chosen file needs.
Arguments are delivered to the devices with the policy and shown in the device's App Hub data. Do not put passwords or licence keys into them; pass such values with a script and a custom field instead.
Uninstall
The uninstall mode decides what Uninstall does:
None: the app cannot be uninstalled from NetLock RMM. The tray icon shows no uninstall button, and a deployment cannot use the action.This file with arguments: the same file runs with the uninstall arguments. Available for.msi(asmsiexec.exe /x),.exe,.ps1and.sh.Script: an uninstall script that you write, run in the platform's shell. Use it for.msu,.deb,.rpmand.pkg, or when the vendor's uninstaller is not the installer file.
Uninstall an MSI by its ProductCode (PowerShell, as SYSTEM):
$name = 'Contoso Client'
$keys = 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*',
'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'
$app = Get-ItemProperty $keys -ErrorAction SilentlyContinue |
Where-Object { $_.DisplayName -eq $name -and $_.PSChildName -match '^\{[0-9A-F-]+\}$' } |
Select-Object -First 1
if (-not $app) { exit 0 }
$p = Start-Process -FilePath "$env:SystemRoot\System32\msiexec.exe" -ArgumentList "/x $($app.PSChildName) /qn /norestart" -Wait -PassThru
if ($p.ExitCode -in 0, 1605, 3010) { exit 0 } else { exit $p.ExitCode }Other examples: wusa.exe /uninstall /kb:5000000 /quiet /norestart for an MSU, apt-get remove -y contoso-client for a DEB, dnf remove -y contoso-client for an RPM. For a PKG, remove the installed files and then run pkgutil --forget com.contoso.client.
Detection is required
A file app needs a detection script. It works as for script apps (see The detection script): exit code 0 and output means installed, and the first line should carry the installed version. It runs before the action and, until the detection window ends, after it. When the detection before an install already reports the app, the file is not even downloaded.
Examples:
# Windows: version of an installed MSI or EXE from the uninstall keys
$keys = 'HKLM:\Software\Microsoft\Windows\CurrentVersion\Uninstall\*',
'HKLM:\Software\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall\*'
$app = Get-ItemProperty $keys -ErrorAction SilentlyContinue | Where-Object { $_.DisplayName -eq 'Contoso Client' } | Select-Object -First 1
if ($app) { $app.DisplayVersion; exit 0 } else { exit 1 }# Linux (DEB): version of an installed package
dpkg-query -W -f='${Version}\n' contoso-client 2>/dev/null# Linux (RPM)
rpm -q --qf '%{VERSION}\n' contoso-client 2>/dev/null# macOS (PKG)
pkgutil --pkg-info com.contoso.client 2>/dev/null | awk '/^version:/ {print $2}'How the agent runs the file
- The detection script runs. An install of an app that is detected, and an update or uninstall of an app that is not, are skipped.
- Unattended runs (deployments, auto-update) wait a random 0 to 120 seconds, so that a large rollout does not start every download at once.
- The agent downloads the file from the File Server into its protected working folder. It needs free space for twice the file size plus 512 MB. A broken download resumes where it stopped. If the File Server answers that it is busy, the agent waits as long as the server asks and tries again, for up to 30 minutes.
- The agent computes the SHA-512 of the downloaded file and compares it with the app. On a mismatch nothing starts and the result is
Error: file hash mismatch. - The installer starts as described in File types.
- Exit codes.
- 3010 and 1641 on Windows mean success with a restart required. The output ends with
[reboot] restart required. The agent never restarts the device; plan the restart yourself. If the detection script cannot confirm the change before the restart, the result is still a success, with the note that the detection is pending until the restart. - 1618 (another installation is in progress) is tried again up to three times, one minute apart, for
.msiand.msu. On Linux, apt-get waits up to five minutes for the package database lock (held, for example, by unattended-upgrades), and a lock held by another dpkg, rpm or zypper process is tried again the same way. - The result starts with a summary: the restart line, the exit code and, for a failure, the reason. The installer's output follows.
- 3010 and 1641 on Windows mean success with a restart required. The output ends with
- The downloaded file and its folder are deleted. The detection script confirms the result.
The tray icon shows the phase downloading with a percentage while the file is transferred.
A .ps1 file runs with -ExecutionPolicy Bypass. If a Group Policy enforces AllSigned, sign the script with a certificate the devices trust (see Run only signed PowerShell scripts).
Update to a new release
- Upload the new installer under a new name, for example
contoso-client-4.3.msi. The file the app uses cannot be overwritten (see below). - Edit the app, choose the new file, and raise
Version. - Save, and sign it if your devices use endpoint protection.
Devices then see an update when the detection script reports a lower version: the tray icon offers Update, and auto-update runs it when the policy allows auto-update for the app. An update runs the new file with the update arguments, or with the install arguments if the update field is empty. Once no app and no open deployment uses the old file any more, you can delete it.
The file stays protected
- A file that an App Hub app or an open deployment (draft, pending or running) uses cannot be deleted or overwritten on the File Server. The Console names the apps and deployments. Renaming or moving the file is allowed: the app keeps working.
- The App Hub list marks an app with
File missingorFile changedwhen its file is gone or was changed on the server outside of NetLock RMM (for example restored from a backup); open the app and choose the file again. Devices refuse such a file: a missing file is reported as not available, a changed file as a hash mismatch. - A deployment keeps the file it was saved with. Saving the app updates pending deployments that have not started on any device yet; a deployment whose file is missing or changed on the server cannot be saved.
Endpoint protection
On anchored devices a file app runs only when it is signed. The signing request in the NetLock app shows the file name, the SHA-512, the arguments and the uninstall mode. Compare the SHA-512 with the hash of your own copy of the installer:
- Windows:
Get-FileHash .\contoso-client-4.3.msi -Algorithm SHA512 - Linux:
sha512sum contoso-client-4.3.msi - macOS:
shasum -a 512 contoso-client-4.3.msi
A software deployment with file items shows its items with file, SHA-512 and arguments in the signing request as well. A file or an argument changed after signing is refused by the device with event type 14 (file_hash_mismatch or payload_hash_mismatch). See Endpoint protection.
Deploy the app
Deploy the app with Software Deployment like any other app (see Deploy software with App Hub). Update is always available for file apps, and Uninstall is available when an uninstall mode is set.
Troubleshooting
| Result | Meaning |
|---|---|
the file is not available on the file server (status 401) / (status 404) | The file was deleted or replaced outside of NetLock RMM, or the device is isolated. Choose the file again in the app. The agent does not repeat the download in that run. |
file hash mismatch | The file on the server is not the file of the app. Choose the file again (and sign the app on anchored devices). |
not enough free disk space | The device needs twice the file size plus 512 MB free. |
another installation is in progress | Windows Installer stayed busy during three attempts (exit code 1618). The deployment retries according to its retry settings. |
the download did not finish within N min | The transfer took longer than its limit: at least 30 minutes, longer for large files (about 100 kB/s), at most 12 hours. Check the connection between the device and the File Server. |
the file server stayed busy | The File Server limited parallel downloads for 30 minutes; see Downloads by devices. |
a file app runs only as the system account or root / A file item runs only with elevation | The app or deployment item has elevation switched off. |
[reboot] restart required | Success; the change completes after the next restart. |
Related
Deploy custom applications with scripts
Create a script-based App Hub app — install, update, uninstall and detection scripts — and roll it out with Software Deployment.
Restrict USB devices on a group
Let new devices learn their keyboard, mouse and dock, then approve further USB devices from the Blocked Devices queue at group scope.