IT Administrator Guide (MDM)

Deploying via MDM

Network Share Mounter can be fully configured through a standard macOS configuration profile. All settings are read from the preference domain de.fau.rrze.NetworkShareMounter.

To simplify profile creation, we provide a JSON manifest schema for Jamf Pro and a manifest for the iMazing Profile Editor.

For distribution via AutoPKG, recipes are available at de.fau.rrze.pkg.networkShareMounter.

1. Managed Shares (`managedNetworkShares`)

The managedNetworkShares array defines which network shares are centrally deployed to users. Each entry is a dictionary with the following keys:

Key	Type	Required	Description
`networkShare`	String	✓	The share URL, e.g. `smb://fileserver.example.com/share`. The placeholder `%USERNAME%` is replaced at runtime with the user’s macOS login name.
`authType`	String	✓	Authentication method: `krb` (Kerberos/SSO), `pwd` (username + password), or `guest`. Default: `krb`.
`mountPoint`	String		Overrides the local directory name used as the mount point. Only relevant when the mount location is not `/Volumes`. Leave blank to use the share name.
`displayName`	String		Display name shown for this share inside the app. Falls back to the share name if not set.
`username`	String		Pre-defines a username for `pwd`-type shares. If omitted, the user is prompted.
`externalKerberosManagement`	String		Set to `"true"` if Kerberos tickets for this share are managed externally (AD binding, Jamf Connect, Apple SSO Extension). NSM will mount the share without interfering with ticket management and will not prompt for a Kerberos profile. Only relevant for `authType: krb`.
`kerberosRealm`	String		Per-share Kerberos realm override. Used together with `externalKerberosManagement` to identify which external profile to assign. Defaults to the global `kerberosRealm` setting.
`autoMount`	String		`"true"` (default): the share is mounted automatically at startup and on network changes. `"false"`: the share appears in the menu but is never mounted automatically — the user can mount it on demand.

Example payload:

<key>managedNetworkShares</key>
<array>
    <!-- Kerberos share, auto-mounted, external ticket management -->
    <dict>
        <key>networkShare</key>
        <string>smb://fileserver.example.com/global</string>
        <key>authType</key>
        <string>krb</string>
        <key>externalKerberosManagement</key>
        <string>true</string>
        <key>displayName</key>
        <string>Global Data</string>
    </dict>
    <!-- Password share with per-user home directory, manual mount only -->
    <dict>
        <key>networkShare</key>
        <string>smb://home.example.com/%USERNAME%</string>
        <key>authType</key>
        <string>pwd</string>
        <key>mountPoint</key>
        <string>My Home Drive</string>
        <key>autoMount</key>
        <string>false</string>
    </dict>
</array>

Note: The legacy networkShares array from version 2 is still accepted for backward compatibility but should not be used in new profiles.

2. Authentication & Kerberos

These keys configure how NSM handles Kerberos ticket management and user identity.

Key	Type	Default	Description
`kerberosRealm`	String	—	Kerberos/AD domain for user authentication (e.g. `EXAMPLE.COM`). When set, NSM manages Kerberos ticket acquisition and renewal automatically. Required for app-managed Kerberos SSO.
`kerberosProfileDisplayName`	String	—	Friendly display name for the Kerberos authentication profile shown in the app’s Settings. If not set, the realm name (e.g. `EXAMPLE.COM`) is used as-is. Useful when a human-readable name like `"Corporate Network"` is preferred over the technical realm string.
`usernameOverride`	String	—	Overrides the `%USERNAME%` variable used in share paths. Use this when the local macOS login name differs from the AD or network username.

Password Expiration Management

When kerberosRealm is configured, NSM can warn users before their AD password expires. Two independent thresholds control the warning behavior:

Key	Type	Default	Description
`ExpirationCountdownStartDay`	Integer	`14`	Passive warning. Days before password expiry when a silent countdown item first appears in the menu bar. The user only sees it when they open the menu — no interruption to their workflow. Set to `0` to disable all password expiration features entirely. Mirrors the Apple Kerberos SSO Extension key of the same name.
`ExpirationNotificationStartDay`	Integer	`14`	Active warning. Days before password expiry when an alert dialog is shown automatically, once per calendar day. Set this lower than `ExpirationCountdownStartDay` so the dialog only interrupts when expiry is genuinely imminent. Mirrors the Jamf Connect / Apple Kerberos SSO Extension key of the same name.
`passwordChangeURL`	String	—	URL of a web-based password self-service portal (SSPR). If set, a Change Password button in the expiration dialog opens this URL in the default browser. If not set, the user can change their password directly within NSM (requires `kerberosRealm`).
`allowPasswordChange`	Boolean	`false`	When `true`, a permanent Change Password… item is shown in the menu bar at all times, even before the expiry threshold is reached. It automatically transforms into the expiry countdown when the threshold is reached. If `passwordChangeURL` is also set, clicking the item opens that URL instead of the in-app dialog. Mirrors the Apple Kerberos SSO Extension key of the same name.

Tip – two-level expiration strategy: Set ExpirationCountdownStartDay higher than ExpirationNotificationStartDay. Example: countdown appears at 14 days (passive, visible only in menu), dialog starts at 7 days (active, once per day). Setting ExpirationCountdownStartDay to 0 disables both warnings entirely.

3. Autostart & App Lifecycle

These keys control whether the app starts automatically at login and how it behaves when the user quits.

Key	Type	Default	Description
`autostart`	Boolean	`false`	When deployed as a locked MDM key, the value is enforced on every app launch. When deployed as an unlocked default, it is applied once on the first launch only — after that, the user retains control.
`canChangeAutostart`	Boolean	`true`	Controls only the autostart toggle in the app’s Settings UI. Set to `false` to grey it out. Does not affect MDM enforcement. To enforce the autostart state on every launch, deploy `autostart` as a locked key instead.
`canQuit`	Boolean	`true`	When `true`, the user can quit the app via the menu bar. Set to `false` to remove the Quit item entirely.
`unmountOnExit`	Boolean	`true`	When `true`, all managed shares are automatically unmounted when the app quits.

How Autostart Enforcement Works (macOS 13+)

NSM uses Apple’s SMAppService API to register itself as a login item. macOS manages this as a LaunchAgent at /Library/LaunchAgents/de.fau.rrze.NetworkShareMounter.plist (root-owned). This is standard macOS behavior with the following implications for MDM administrators:

The osascript command tell application "System Events" to delete login item "…" does not work for SMAppService-registered items. System Events only manages old-style user login items.
When autostart = false is enforced via a locked MDM key, NSM calls SMAppService.unregister() on every launch, and macOS removes the LaunchAgent file automatically.
If you manage the autostart via your own LaunchAgent or login item payload, set autostart = false as a locked key to prevent NSM from registering a competing login item.

Preventing Users from Disabling Autostart

macOS 13 (Ventura) and later allows users to freely disable background apps via System Settings. To enforce the autostart and prevent users from turning off NSM, deploy a Managed Login Items payload alongside your configuration profile:

Rule Type: Bundle Identifier
Rule Value: de.fau.rrze.NetworkShareMounter

Triggering the Initial Autostart

Due to macOS security design, an app must be launched at least once before its login item registration takes effect. For a silent, zero-touch deployment, configure your MDM to launch NSM once immediately after installation or at first login.

Example Jamf policy:

Trigger: Login
Frequency: Once per user per computer
Command: sudo -u $(stat -f%Su /dev/console) open -a "/Applications/Network Share Mounter.app"

4. User Interface

These keys control the mount location, menu bar appearance, and which menu items are accessible to users.

Key	Type	Default	Description
`location`	String	—	Path where network shares are mounted. The default is a localized folder in the user’s home directory (e.g. `~/Network Shares`). ⚠️ It is strongly recommended to leave this empty and use the default. Changing it can break Finder integration.
`cleanupLocationDirectory`	Boolean	`false`	When `true`, NSM removes files and empty directories from the mount location that would prevent a share from mounting. Read the documentation carefully before enabling — this modifies the user’s file system.
`showMountsInMenu`	Boolean	`true`	When `true`, mounted and unmounted shares are listed individually in the menu bar for quick one-click access.
`helpURL`	String	—	URL to your organization’s internal helpdesk or IT documentation. When set, an About Network Share Mounter item appears in the menu bar, opening this URL in the default browser.

You can show, hide, or disable individual menu bar items using the following string keys. Set the value to hidden to remove the item completely, or disabled to grey it out without removing it. If a key is not set, the item is shown normally.

Key	Controls
`menuConnectShares`	Mount shares action
`menuDisconnectShares`	Unmount shares action
`menuShowSharesMountDir`	Show mounted shares (opens mount folder in Finder)
`menuShowShares`	Individual share items in the list
`menuSettings`	Preferences… item
`menuCheckUpdates`	Check for Updates… item
`menuAbout`	About Network Share Mounter item (only visible when `helpURL` is set)
`menuQuit`	Quit Network Share Mounter item

Example – hide Settings and Updates from users:

<key>menuSettings</key>
<string>hidden</string>
<key>menuCheckUpdates</key>
<string>hidden</string>

5. Software Update Management

NSM uses the Sparkle framework for automatic updates. In managed environments, you typically want to disable this and deploy updates via your MDM.

Key	Type	Default	Description
`disableAutoUpdateFramework`	Boolean	`false`	Master switch. Set to `true` to completely disable the Sparkle update framework. When disabled, no update checks occur and the Check for Updates menu item is removed.
`SUEnableAutomaticChecks`	Boolean	`true`	When the framework is enabled, controls whether NSM actively checks for new versions in the background. Set to `false` to suppress checks while keeping the framework loaded.
`SUAutomaticallyUpdate`	Boolean	`true`	When `true`, updates are downloaded and installed automatically without asking the user for confirmation. Only takes effect when `SUEnableAutomaticChecks` is also `true`.

Note: The legacy key enableAutoUpdater (inverted logic) is still accepted and migrated automatically on first launch. Use disableAutoUpdateFramework in all new profiles.

6. Scripting & Automation

NSM responds to UNIX signals, allowing external scripts to trigger mount and unmount operations without using the app interface. This is useful for Self Service portal workflows that allow users to “repair” network drives.

Signal	Action
`SIGUSR1`	Unmount all shares
`SIGUSR2`	Mount all shares

Example:

# Find the PID
NSM_PID=$(pgrep -x "Network Share Mounter")

# Unmount all shares
kill -SIGUSR1 "$NSM_PID"

# Mount all shares
kill -SIGUSR2 "$NSM_PID"

7. Known Issues & Compatibility

Jamf Pro: inventory collection (recon) hangs

When shares are mounted inside the user’s home directory (the default), the Jamf Pro inventory process (recon) may hang indefinitely. This happens because Jamf attempts to calculate the total size of the home directory, which causes it to traverse all mounted network shares.

Solution: In Jamf Pro, go to Settings > Computer Management - Management Framework > Inventory Collection and disable Include home directory sizes. Alternatively, set the location key to a path outside the home directory, such as /Volumes.

If you still rely on the legacy Network Share Mounter (v3/v2), the documentation is available in our repository.