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üssel	Typ	Erforderlich	Beschreibung
`networkShare`	String	✓	Die Freigabe-URL, z.B. `smb://fileserver.example.com/share`. Der Platzhalter `%USERNAME%` wird zur Laufzeit durch den macOS-Anmeldenamen des Benutzers ersetzt.
`authType`	String	✓	Authentifizierungsmethode: `krb` (Kerberos/SSO), `pwd` (Benutzername + Passwort) oder `guest`. Standard: `krb`.
`mountPoint`	String		Ü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.
`displayName`	String		Anzeigename für diese Freigabe innerhalb der App. Wird der Freigabename verwendet, wenn nicht gesetzt.
`username`	String		Legt einen Benutzernamen für Freigaben vom Typ `pwd` fest. Wenn nicht angegeben, wird der Benutzer danach gefragt.
`externalKerberosManagement`	String		Auf `"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`.
`kerberosRealm`	String		Per-Freigabe-Kerberos-Realm-Override. Wird zusammen mit `externalKerberosManagement` verwendet, um das zuzuweisende externe Profil zu identifizieren. Verwendet standardmäßig die globale `kerberosRealm`-Einstellung.
`autoMount`	String		`"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.

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>
        <key>displayName</key>
        <string>Global Data</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.

2. Authentifizierung & Kerberos

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

Schlüssel	Typ	Standard	Beschreibung
`kerberosRealm`	String	—	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.
`kerberosProfileDisplayName`	String	—	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.
`usernameOverride`	String	—	Überschreibt die Variable `%USERNAME%` in Freigabepfaden. Verwenden, wenn der lokale macOS-Anmeldename vom AD- oder Netzwerk-Benutzernamen abweicht.

Passwortablauf-Warnungen

Wenn kerberosRealm konfiguriert ist, kann NSM Benutzer vor dem Ablauf ihres AD-Passworts warnen. Zwei unabhängige Schwellenwerte steuern das Warnverhalten:

Schlüssel	Typ	Standard	Beschreibung
`ExpirationCountdownStartDay`	Integer	`14`	Passive Warnung. Tage vor Ablauf des Passworts, ab denen ein stiller Countdown-Eintrag in der Menüleiste erscheint. Sichtbar nur, wenn der Benutzer das Menü öffnet – keine Unterbrechung des Workflows. Auf `0` setzen, um alle Passwortablauf-Funktionen vollständig zu deaktivieren. Entspricht dem gleichnamigen Schlüssel der Apple Kerberos SSO Extension.
`ExpirationNotificationStartDay`	Integer	`14`	Aktive Warnung. Tage vor Ablauf des Passworts, ab denen automatisch einmal pro Kalendertag ein Warnhinweisdialog erscheint. Sollte kleiner als `ExpirationCountdownStartDay` sein, damit der Dialog den Benutzer erst dann unterbricht, wenn der Ablauf wirklich nahe ist. Entspricht dem gleichnamigen Schlüssel von Jamf Connect / Apple Kerberos SSO Extension.
`passwordChangeURL`	String	—	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`).
`allowPasswordChange`	Boolean	`false`	Wenn `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.

Tipp – Zweistufige Ablaufstrategie: ExpirationCountdownStartDay höher als ExpirationNotificationStartDay setzen. Beispiel: Countdown erscheint ab 14 Tagen (passiv, nur beim Öffnen des Menüs sichtbar), Dialog ab 7 Tagen (aktiv, einmal täglich). ExpirationCountdownStartDay auf 0 deaktiviert beide Warnungen vollständig.

3. Autostart & App-Lifecycle

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

Schlüssel	Typ	Standard	Beschreibung
`autostart`	Boolean	`false`	Wird 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.
`canChangeAutostart`	Boolean	`true`	Steuert 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.
`canQuit`	Boolean	`true`	Wenn `true`, kann der Benutzer die App über die Menüleiste beenden. Bei `false` wird der Beenden-Eintrag vollständig entfernt.
`unmountOnExit`	Boolean	`true`	Wenn `true`, werden alle verwalteten Freigaben beim Beenden der App automatisch getrennt.

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üssel	Typ	Standard	Beschreibung
`location`	String	—	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.
`cleanupLocationDirectory`	Boolean	`false`	Wenn `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.
`showMountsInMenu`	Boolean	`true`	Wenn `true`, werden eingehängte und getrennte Freigaben einzeln in der Menüleiste für schnellen Ein-Klick-Zugriff aufgelistet.
`helpURL`	String	—	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.

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üssel	Steuert
`menuConnectShares`	Aktion Freigaben einhängen
`menuDisconnectShares`	Aktion Freigaben aushängen
`menuShowSharesMountDir`	Eingehängte Freigaben anzeigen (öffnet Mount-Ordner im Finder)
`menuShowShares`	Einzelne Freigaben in der Liste
`menuSettings`	Eintrag Einstellungen…
`menuCheckUpdates`	Eintrag Nach Updates suchen…
`menuAbout`	Eintrag Über Network Share Mounter (nur sichtbar, wenn `helpURL` gesetzt ist)
`menuQuit`	Eintrag 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üssel	Typ	Standard	Beschreibung
`disableAutoUpdateFramework`	Boolean	`false`	Hauptschalter. 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.
`SUEnableAutomaticChecks`	Boolean	`true`	Wenn 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.
`SUAutomaticallyUpdate`	Boolean	`true`	Wenn `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".

Signal	Aktion
`SIGUSR1`	Alle Freigaben aushängen
`SIGUSR2`	Alle 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.

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