IT-Administrator-Handbuch (MDM)

Bereitstellung über MDM#

Der Network Share Mounter kann vollständig über ein macOS-Konfigurationsprofil konfiguriert werden. Alle Einstellungen werden aus der Preference Domain de.fau.rrze.NetworkShareMounter gelesen.

Um die Profilerstellung zu vereinfachen, stellen wir ein JSON-Manifestschema für Jamf Pro und ein Manifest für den iMazing Profile Editor zur Verfügung.

Für die Verteilung über AutoPKG stehen Recipes unter de.fau.rrze.pkg.networkShareMounter bereit.


1. Verwaltete Freigaben (managedNetworkShares)#

Das Array managedNetworkShares legt fest, welche Netzwerkfreigaben zentral für Benutzer bereitgestellt werden. Jeder Eintrag ist ein Dictionary mit folgenden Schlüsseln:

SchlüsselTypErforderlichBeschreibung
networkShareString✓Die Freigabe-URL, z.B. smb://fileserver.example.com/share. Der Platzhalter %USERNAME% wird zur Laufzeit durch den macOS-Anmeldenamen des Benutzers ersetzt.
authTypeString✓Authentifizierungsmethode: krb (Kerberos/SSO), pwd (Benutzername + Passwort) oder guest. Standard: krb.
mountPointStringÜberschreibt den lokalen Verzeichnisnamen, der als Mount-Point verwendet wird. Nur relevant, wenn der Mount-Pfad nicht /Volumes ist. Leer lassen, um den Freigabenamen zu verwenden.
usernameStringLegt einen Benutzernamen für Freigaben vom Typ pwd fest. Wenn nicht angegeben, wird der Benutzer danach gefragt.
externalKerberosManagementStringAuf "true" setzen, wenn Kerberos-Tickets für diese Freigabe extern verwaltet werden (AD-Binding, Jamf Connect, Apple SSO Extension). NSM greift nicht in die Ticketverwaltung ein und zeigt keine „Profil erforderlich"-Warnung an. Nur relevant für authType: krb.
kerberosRealmStringPer-Freigabe-Kerberos-Realm-Override. Wird zusammen mit externalKerberosManagement verwendet, um das zuzuweisende externe Profil zu identifizieren. Verwendet standardmäßig die globale kerberosRealm-Einstellung.
autoMountString"true" (Standard): Die Freigabe wird beim Start und bei Netzwerkänderungen automatisch eingehängt. "false": Die Freigabe erscheint im Menü, wird aber nie automatisch eingehängt – der Benutzer kann sie manuell mounten.
hideFromFinderString"true": Die Freigabe wird weder in der Finder-Seitenleiste noch auf dem Schreibtisch angezeigt (wie die autofs-Option nobrowse). Sie bleibt über ihren Ordner und das Menü der App erreichbar, kann aber im Finder nicht ausgeworfen werden – sinnvoll für Freigaben, auf die sich andere Apps oder Skripte verlassen. "false" (Standard): wie gewohnt im Finder sichtbar. Eine Änderung wirkt beim nächsten Verbinden der Freigabe. Verfügbar ab Version 4.2.0.
localMountPointStringVollständiger lokaler Pfad, an dem diese Freigabe statt im gemeinsamen Ordner verbunden wird, z. B. ~/Projekte/docs oder /Users/%USERNAME%/docs. Muss mit / oder ~/ beginnen und darf nicht in /Volumes liegen. Der Ordner muss dem Benutzer gehören und leer sein; ein fehlender Ordner wird angelegt. Die App löscht ihn nie, er eignet sich daher auch als Finder-Favorit. Nicht erlaubt sind Ordner, die mit einem Cloud-Dienst synchronisiert werden, und Systemordner im Benutzerordner: Desktop, Documents, Library, FAUbox, PowerFolders, Dropbox, OneDrive, Google Drive, Nextcloud, ownCloud, Seafile, Box sowie jeder von iCloud synchronisierte Ordner. Ungültige Werte werden ignoriert, die Freigabe wird dann im gemeinsamen Ordner verbunden. mountPoint bestimmt weiterhin den Namen im Menü. Verfügbar ab Version 4.2.0.

Beispiel-Payload:

<key>managedNetworkShares</key>
<array>
    <!-- Kerberos-Freigabe, automatisch eingehängt, externe Ticketverwaltung -->
    <dict>
        <key>networkShare</key>
        <string>smb://fileserver.example.com/global</string>
        <key>authType</key>
        <string>krb</string>
        <key>externalKerberosManagement</key>
        <string>true</string>
    </dict>
    <!-- Passwort-Freigabe mit benutzerspezifischem Home-Verzeichnis, nur manuell einhängen -->
    <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>

Hinweis: Das veraltete networkShares-Array aus Version 2 wird aus Gründen der Abwärtskompatibilität noch akzeptiert, sollte aber in neuen Profilen nicht mehr verwendet werden.

Active-Directory-Home-Laufwerk (mountSMBHome)#

Auf Macs, die an ein Active Directory gebunden sind, verbindet NSM zusätzlich das Home-Laufwerk aus dem SMBHome-Attribut des AD-Kontos. Es erscheint im Menü als per MDM definiert und kann vom Benutzer weder bearbeitet noch entfernt werden.

SchlüsselTypStandardBeschreibung
mountSMBHomeBooleantrueAuf false setzen, um das AD-Home-Laufwerk nicht zu verbinden, z. B. wenn NSM die Freigaben-Funktion von NoMAD oder Jamf Connect ersetzt. Fehlt der Schlüssel, wird das Home-Laufwerk wie bisher verbunden. Eine Freigabe mit derselben URL in managedNetworkShares ist davon nicht betroffen. Verfügbar ab Version 4.1.7.

Bearbeitbare Freigaben ohne MDM (userNetworkShares)#

Freigaben, die Benutzer selbst anlegen, speichert NSM unter userNetworkShares in den Benutzereinstellungen. Über denselben Schlüssel lassen sich ohne MDM viele Freigaben auf einmal anlegen, zum Beispiel bei der Migration von einem anderen Tool. Anders als bei managedNetworkShares sind diese Freigaben nicht gesperrt: Benutzer können sie in der App bearbeiten und entfernen.

  • Gleiche Schlüssel wie oben: networkShare (Pflicht), authType, mountPoint, username und autoMount. Für authType nur krb, pwd oder guest verwenden; der ältere Wert password wird hier nicht erkannt. MDM-spezifische Schlüssel wie externalKerberosManagement und kerberosRealm werden nicht unterstützt.
  • Network Share Mounter vor dem Schreiben des Schlüssels beenden. defaults write ersetzt vorhandene Benutzerfreigaben, defaults import sogar die gesamte Einstellungsdomäne.
  • Passwörter lassen sich nicht importieren. Bei pwd-Freigaben anschließend in der App ein Authentifizierungsprofil zuweisen.
  • userNetworkShares nicht per Konfigurationsprofil verteilen: Änderungen der Benutzer an ihren Freigaben könnten dann nicht gespeichert werden.

Beispiel:

defaults write de.fau.rrze.NetworkShareMounter userNetworkShares '<array>
  <dict>
    <key>networkShare</key><string>smb://fileserver.example.com/projects</string>
    <key>authType</key><string>krb</string>
  </dict>
  <dict>
    <key>networkShare</key><string>smb://fileserver.example.com/finance</string>
    <key>authType</key><string>pwd</string>
    <key>username</key><string>jdoe</string>
    <key>autoMount</key><string>false</string>
  </dict>
</array>'

2. Authentifizierung & Kerberos#

Diese Schlüssel steuern, wie NSM Kerberos-Tickets und die Benutzeridentität verwaltet.

SchlüsselTypStandardBeschreibung
kerberosRealmString—Kerberos/AD-Domäne für die Benutzerauthentifizierung (z.B. EXAMPLE.COM). Wenn gesetzt, verwaltet NSM den Kerberos-Ticket-Erwerb und die Erneuerung automatisch. Erforderlich für App-verwaltetes Kerberos-SSO.
kerberosProfileDisplayNameString—Anzeigename für das Kerberos-Authentifizierungsprofil in den App-Einstellungen. Wenn nicht gesetzt, wird der Realm-Name (z.B. EXAMPLE.COM) direkt verwendet. Nützlich, wenn ein sprechender Name wie „Universitätsnetzwerk" dem technischen Realm-String vorgezogen wird.
usernameOverrideString—Überschreibt die Variable %USERNAME% in Freigabepfaden. Verwenden, wenn der lokale macOS-Anmeldename vom AD- oder Netzwerk-Benutzernamen abweicht.

Passwortablauf-Warnungen#

Wenn sich NSM selbst bei Kerberos anmeldet (kerberosRealm ist gesetzt und die Freigaben verwenden kein externalKerberosManagement), kann NSM Benutzer vor dem Ablauf ihres AD-Passworts warnen. Die Warnungen sind standardmäßig aktiv: Beide Schwellenwerte stehen auf 14 Tagen, die Warnungen erscheinen also auch ohne Konfiguration. Für Konten, deren Passwort nie abläuft, erscheint keine Warnung.

SchlüsselTypStandardBeschreibung
ExpirationCountdownStartDayInteger14Passive Warnung. Tage vor Passwortablauf, ab denen ein Countdown-Eintrag in der Menüleiste erscheint. Benutzer sehen ihn nur, wenn sie das Menü öffnen – ihre Arbeit wird nicht unterbrochen. 0 schaltet alle Warnungen zum Passwortablauf ab, also den Countdown und den Dialog. Entspricht dem gleichnamigen Schlüssel der Apple Kerberos SSO Extension.
ExpirationNotificationStartDayInteger14Aktive Warnung. Tage vor Passwortablauf, ab denen automatisch ein Hinweisdialog erscheint, höchstens einmal pro Kalendertag. Der Dialog beginnt nie vor dem Countdown: Ist dieser Wert höher als ExpirationCountdownStartDay, startet der Dialog zusammen mit dem Countdown. 0 schaltet nur den Dialog ab, der Countdown bleibt (ab Version 4.1.6). Entspricht dem gleichnamigen Schlüssel von Jamf Connect und der Apple Kerberos SSO Extension.
passwordChangeURLString—URL eines webbasierten Passwort-Self-Service-Portals (SSPR). Wenn gesetzt, erscheint im Ablaufdialog eine Schaltfläche Passwort ändern, die diese URL im Standardbrowser öffnet. Wenn nicht gesetzt, kann der Benutzer das Passwort direkt in der App ändern (erfordert eine konfigurierte kerberosRealm).
allowPasswordChangeBooleanfalseWenn true, wird dauerhaft ein Passwort ändern…-Eintrag in der Menüleiste angezeigt, auch bevor der Ablaufschwellenwert erreicht ist. Er verwandelt sich automatisch in den Ablauf-Countdown, sobald der Schwellenwert erreicht wird. Falls passwordChangeURL gesetzt ist, öffnet der Klick diese URL statt des In-App-Dialogs. Entspricht dem gleichnamigen Schlüssel der Apple Kerberos SSO Extension.

Typische Einstellungen:

ZielEinstellung
Keine Warnungen zum PasswortablaufExpirationCountdownStartDay = 0
Nur Countdown im Menü, kein DialogExpirationNotificationStartDay = 0 (ab Version 4.1.6)
Countdown ab 14 Tagen, Dialog ab 7 TagenExpirationCountdownStartDay = 14, ExpirationNotificationStartDay = 7

3. Autostart & App-Lifecycle#

Diese Schlüssel steuern, ob die App beim Login automatisch startet und wie sie sich beim Beenden verhält.

SchlüsselTypStandardBeschreibung
autostartBooleanfalseWird der Schlüssel als gesperrter MDM-Schlüssel verteilt, wird der Wert bei jedem App-Start durchgesetzt. Wird er als ungesperrter Standardwert verteilt, wird er nur beim ersten Start angewendet – danach behält der Benutzer die Kontrolle.
canChangeAutostartBooleantrueSteuert ausschließlich die Sichtbarkeit des Autostart-Toggles in den App-Einstellungen. Bei false wird der Toggle ausgegraut. Hat keinen Einfluss auf die MDM-Durchsetzung. Um den Autostart-Zustand bei jedem Start zu erzwingen, stattdessen autostart als gesperrten Schlüssel verteilen.
canQuitBooleantrueWenn true, kann der Benutzer die App über die Menüleiste beenden. Bei false wird der Beenden-Eintrag vollständig entfernt.
unmountOnExitBooleantrueWenn true, werden alle verwalteten Freigaben beim Beenden der App automatisch getrennt.
mountTriggerIntervalInteger300Sekunden zwischen den regelmäßigen Prüfungen, die nicht verbundene Freigaben verbinden, z. B. wenn ein Server nicht erreichbar war. Nach einem Netzwerkwechsel oder dem Aufwachen wird sofort verbunden, unabhängig von diesem Wert. Vom Benutzer getrennte Freigaben bleiben getrennt. Erlaubter Bereich: 60 bis 3600; Werte außerhalb werden darauf begrenzt. Die Authentifizierung wird weiterhin höchstens alle 5 Minuten erneuert. Wirkt nach einem Neustart der App. Verfügbar ab Version 4.2.0.

Wie die Autostart-Durchsetzung funktioniert (macOS 13+)#

NSM verwendet Apples SMAppService-API, um sich als Login-Objekt zu registrieren. macOS verwaltet dies als LaunchAgent unter /Library/LaunchAgents/de.fau.rrze.NetworkShareMounter.plist (Root-Eigentümer). Dies ist Standard-macOS-Verhalten mit folgenden Konsequenzen für MDM-Administratoren:

  • Der osascript-Befehl tell application "System Events" to delete login item "…" funktioniert nicht für SMAppService-registrierte Objekte. System Events verwaltet nur die alten Benutzer-Login-Objekte.
  • Wenn autostart = false als gesperrter MDM-Schlüssel erzwungen wird, ruft NSM bei jedem Start SMAppService.unregister() auf — macOS entfernt die LaunchAgent-Datei automatisch.
  • Wenn du den Autostart über einen eigenen LaunchAgent oder ein Login-Item-Payload steuerst, setze autostart = false als gesperrten Schlüssel, damit NSM keinen konkurrierenden Login-Eintrag registriert.

Benutzer am Deaktivieren des Autostarts hindern#

Ab macOS 13 (Ventura) können Benutzer Hintergrund-Apps über die Systemeinstellungen jederzeit deaktivieren. Um den Autostart zu erzwingen und zu verhindern, dass Benutzer NSM abschalten, solltest du zusammen mit dem Konfigurationsprofil einen Managed Login Items Payload verteilen:

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

Initialen Autostart auslösen#

Aufgrund des macOS-Sicherheitsdesigns muss eine App mindestens einmal geöffnet werden, bevor die Login-Item-Registrierung greift. Für eine lautlose Verteilung ohne Benutzerinteraktion konfiguriere dein MDM so, dass NSM einmalig direkt nach der Installation oder beim ersten Login gestartet wird.

Beispiel 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. Benutzeroberfläche#

Diese Schlüssel steuern den Mount-Pfad, das Erscheinungsbild der Menüleiste und welche Menüeinträge für Benutzer zugänglich sind.

SchlüsselTypStandardBeschreibung
locationString—Pfad, in dem Netzwerkfreigaben eingehängt werden. Standard ist ein lokalisierter Ordner im Benutzer-Home (z.B. ~/Netzlaufwerke). ⚠️ Es wird dringend empfohlen, diesen Wert leer zu lassen und den Standard zu verwenden. Eine Änderung kann die Finder-Integration beeinträchtigen.
cleanupLocationDirectoryBooleanfalseWenn true, entfernt NSM Dateien und leere Verzeichnisse am Mount-Ort, die das Einhängen einer Freigabe verhindern würden. Vor dem Aktivieren die Dokumentation sorgfältig lesen – diese Option verändert das Dateisystem des Benutzers.
restartFinderOnUnmountBoolean—Legt fest, ob der Finder nach dem Trennen von Freigaben neu gestartet wird. Der Neustart sorgt dafür, dass getrennte Freigaben zuverlässig verschwinden, schließt aber alle Finder-Fenster und bricht laufende Kopiervorgänge im Finder ab. Fehlt der Schlüssel, wird der Finder nur unter macOS-Versionen vor 27 neu gestartet; macOS 27 erkennt getrennte Freigaben selbst. true startet den Finder immer neu, false aktualisiert ihn nur, jeweils unter allen macOS-Versionen. Verfügbar ab Version 4.2.0.
helpURLString—URL zum internen Helpdesk oder zur IT-Dokumentation deiner Organisation. Wenn gesetzt, erscheint in der Menüleiste ein Eintrag Über Network Share Mounter, der diese URL im Standardbrowser öffnet.
sendDiagnosticsBooleantrueWenn false, sendet NSM keine Absturz- und Fehlerberichte an den Sentry-Server des Projekts. Die manuelle Übermittlung von Debug-Logs ist dann ebenfalls deaktiviert. Am besten mit disableDiagnostics = true kombinieren: Ist nur sendDiagnostics erzwungen, bleibt der Schalter in den Einstellungen sichtbar, hat aber keine Wirkung.
disableDiagnosticsBooleanfalseWenn true, wird der Bereich Diagnose (der Schalter „Anonyme Diagnosedaten senden" und das versteckte Debug-Log-Export-Tool) unter Einstellungen → Allgemein ausgeblendet.

Menüleisten-Einträge anpassen#

Du kannst einzelne Menüleisten-Einträge anzeigen, ausblenden oder deaktivieren. Setze den Wert auf hidden, um den Eintrag vollständig zu entfernen, oder auf disabled, um ihn auszugrauen ohne ihn zu entfernen. Wenn ein Schlüssel nicht gesetzt ist, wird der Eintrag normal angezeigt.

SchlüsselSteuert
menuConnectSharesAktion Freigaben einhängen
menuDisconnectSharesAktion Freigaben aushängen
menuShowSharesMountDirEingehängte Freigaben anzeigen (öffnet Mount-Ordner im Finder)
menuShowSharesEinzelne Freigaben in der Liste
menuSettingsEintrag Einstellungen…
menuCheckUpdatesEintrag Nach Updates suchen…
menuAboutEintrag Über Network Share Mounter (nur sichtbar, wenn helpURL gesetzt ist)
menuQuitEintrag Network Share Mounter beenden

Beispiel – Einstellungen und Updates vor Benutzern verstecken:

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

5. Software-Update-Verwaltung#

NSM verwendet das Sparkle-Framework für automatische Updates. In verwalteten Umgebungen empfiehlt es sich, dies zu deaktivieren und Updates über das MDM zu verteilen.

SchlüsselTypStandardBeschreibung
disableAutoUpdateFrameworkBooleanfalseHauptschalter. Auf true setzen, um das Sparkle-Update-Framework vollständig zu deaktivieren. Wenn deaktiviert, finden keine Update-Prüfungen statt und der Eintrag Nach Updates suchen wird entfernt.
SUEnableAutomaticChecksBooleantrueWenn das Framework aktiviert ist, steuert dieser Schlüssel, ob NSM aktiv im Hintergrund nach neuen Versionen sucht. Auf false setzen, um Prüfungen zu unterdrücken, ohne das Framework vollständig zu deaktivieren.
SUAutomaticallyUpdateBooleantrueWenn true, werden Updates automatisch heruntergeladen und installiert, ohne den Benutzer um Bestätigung zu bitten. Greift nur, wenn SUEnableAutomaticChecks ebenfalls true ist.

Hinweis: Der veraltete Schlüssel enableAutoUpdater (umgekehrte Logik) wird noch akzeptiert und beim ersten Start automatisch migriert. In neuen Profilen disableAutoUpdateFramework verwenden.


6. Skripting & Automatisierung#

NSM reagiert auf UNIX-Signale, mit denen externe Skripte Mount- und Unmount-Vorgänge auslösen können, ohne die App-Oberfläche zu verwenden. Dies ist besonders nützlich für Self-Service-Portal-Workflows, die Benutzern ermöglichen, Netzlaufwerke zu „reparieren".

SignalAktion
SIGUSR1Alle Freigaben aushängen
SIGUSR2Alle Freigaben einhängen

Beispiel:

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

# Alle Freigaben aushängen
kill -SIGUSR1 "$NSM_PID"

# Alle Freigaben einhängen
kill -SIGUSR2 "$NSM_PID"

7. Bekannte Probleme & Kompatibilität#

Jamf Pro: Inventarisierung (recon) bleibt hängen

Wenn Freigaben im Home-Verzeichnis des Benutzers eingehängt werden (Standardverhalten), kann der Jamf Pro Inventarisierungsprozess (recon) auf unbestimmte Zeit hängen bleiben. Das passiert, weil Jamf versucht, die Gesamtgröße des Home-Verzeichnisses zu berechnen, und dabei alle eingehängten Netzwerkfreigaben durchsucht.

Lösung: In Jamf Pro unter Settings > Computer Management - Management Framework > Inventory Collection die Option Include home directory sizes deaktivieren. Alternativ den location-Schlüssel auf einen Pfad außerhalb des Home-Verzeichnisses setzen, z.B. /Volumes.

Domänenbasierte DFS-Namespaces (smb://example.com/share)

Kerberos-Freigaben, die auf den Domänennamen statt auf einen Dateiserver zeigen, können mit “invalid credentials” fehlschlagen, obwohl der Benutzer ein gültiges Kerberos-Ticket hat. Active Directory hat für den Domänennamen selbst (cifs/example.com) meist keinen Service Principal. Ein Servername wie smb://fileserver.example.com/share funktioniert, bindet die Benutzer aber an einen einzelnen Server.

Lösung: Ab macOS 26.5 können Macs ohne Active-Directory-Bindung DFS-Namespaces über die Domain Controller auflösen. /etc/nsmb.conf mit folgendem Inhalt verteilen, zum Beispiel als Skript oder Paket über das MDM, und die domänenbasierte URL in managedNetworkShares beibehalten:

[default]
srv_lookup_enabled=yes

Details zu dieser Einstellung stehen in der Dokumentation von Apple: https://support.apple.com/en-mz/guide/deployment/depd1a7cad1f/web

Platform SSO mit einem On-Premises-Active-Directory

Mit Platform SSO (Microsoft Entra ID) erhält ein Mac standardmäßig nur ein Kerberos-Ticket für die Cloud (tgt_cloud). Für Dateiserver im lokalen Netz ist es nicht verwendbar, Kerberos-Freigaben scheitern dann mit “invalid credentials”, obwohl ein Ticket vorhanden ist.

Lösung: Microsoft Entra Kerberos aktivieren, damit Platform SSO zusätzlich ein Ticket für die lokale Domäne bereitstellt (tgt_ad), und in der Payload der Kerberos-SSO-Extension Use TGT from Platform SSO for Kerberos requests einschalten. Die Freigaben mit externalKerberosManagement kennzeichnen, damit NSM diese Tickets verwendet. Ob beide Tickets vorhanden sind, zeigt app-sso platform -s im Terminal (Abschnitt “User Configuration”).


Network Share Mounter v3#

Wenn du noch auf den alten Network Share Mounter (v3/v2) angewiesen bist, findest du die Dokumentation in unserem Repository.