Guida per l'amministratore IT (MDM)

Distribuzione tramite MDM

Network Share Mounter può essere completamente configurato tramite un profilo di configurazione macOS standard. Tutte le impostazioni vengono lette dal dominio di preferenze de.fau.rrze.NetworkShareMounter.

Per semplificare la creazione dei profili, forniamo uno schema di manifesto JSON per Jamf Pro e un manifesto per iMazing Profile Editor.

Per la distribuzione tramite AutoPKG, le ricette sono disponibili su de.fau.rrze.pkg.networkShareMounter.

1. Condivisioni gestite (`managedNetworkShares`)

L’array managedNetworkShares definisce quali condivisioni di rete vengono distribuite centralmente agli utenti. Ogni voce è un dizionario con le seguenti chiavi:

Chiave	Tipo	Obbligatorio	Descrizione
`networkShare`	String	✓	L’URL della condivisione, ad es. `smb://fileserver.example.com/share`. Il segnaposto `%USERNAME%` viene sostituito in fase di esecuzione con il nome di accesso macOS dell’utente.
`authType`	String	✓	Metodo di autenticazione: `krb` (Kerberos/SSO), `pwd` (nome utente + password) o `guest`. Predefinito: `krb`.
`mountPoint`	String		Sostituisce il nome della directory locale usata come punto di montaggio. Rilevante solo quando la posizione di montaggio non è `/Volumes`. Lasciare vuoto per usare il nome della condivisione.
`displayName`	String		Nome visualizzato per questa condivisione all’interno dell’app. Se non impostato, viene usato il nome della condivisione.
`username`	String		Predefinisce un nome utente per le condivisioni di tipo `pwd`. Se omesso, all’utente verrà chiesto di inserirlo.
`externalKerberosManagement`	String		Impostare su `"true"` se i ticket Kerberos per questa condivisione sono gestiti esternamente (binding AD, Jamf Connect, Apple SSO Extension). NSM monterà la condivisione senza interferire con la gestione dei ticket e non mostrerà l’avviso «profilo richiesto». Rilevante solo per `authType: krb`.
`kerberosRealm`	String		Override del realm Kerberos per singola condivisione. Usato insieme a `externalKerberosManagement` per identificare quale profilo esterno assegnare. Per impostazione predefinita usa il valore globale `kerberosRealm`.
`autoMount`	String		`"true"` (predefinito): la condivisione viene montata automaticamente all’avvio e al cambio di rete. `"false"`: la condivisione appare nel menu ma non viene mai montata automaticamente — l’utente può montarla su richiesta.

Esempio di payload:

<key>managedNetworkShares</key>
<array>
    <!-- Condivisione Kerberos, montata automaticamente, gestione esterna dei ticket -->
    <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>
    <!-- Condivisione con password, home directory per utente, solo montaggio manuale -->
    <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>

Nota: l’array legacy networkShares della versione 2 è ancora accettato per compatibilità con le versioni precedenti, ma non deve essere usato nei nuovi profili.

2. Autenticazione e Kerberos

Queste chiavi configurano come NSM gestisce i ticket Kerberos e l’identità degli utenti.

Chiave	Tipo	Predefinito	Descrizione
`kerberosRealm`	String	—	Dominio Kerberos/AD per l’autenticazione degli utenti (ad es. `EXAMPLE.COM`). Quando configurato, NSM gestisce automaticamente l’acquisizione e il rinnovo dei ticket Kerberos. Richiesto per l’SSO Kerberos gestito dall’app.
`kerberosProfileDisplayName`	String	—	Nome visualizzato per il profilo di autenticazione Kerberos nelle preferenze dell’app. Se non impostato, viene usato direttamente il nome del realm (ad es. `EXAMPLE.COM`). Utile quando si preferisce un nome leggibile come `"Rete Aziendale"` alla stringa tecnica del realm.
`usernameOverride`	String	—	Sostituisce la variabile `%USERNAME%` nei percorsi delle condivisioni. Usare quando il nome di accesso macOS locale differisce dal nome utente AD o di rete.

Gestione della scadenza delle password

Quando kerberosRealm è configurato, NSM può avvisare gli utenti prima della scadenza della loro password AD. Due soglie indipendenti controllano il comportamento degli avvisi:

Chiave	Tipo	Predefinito	Descrizione
`ExpirationCountdownStartDay`	Integer	`14`	Avviso passivo. Giorni prima della scadenza della password in cui appare silenziosamente un conto alla rovescia nella barra dei menu. L’utente lo vede solo aprendo il menu — nessuna interruzione del flusso di lavoro. Impostare su `0` per disabilitare completamente tutte le funzioni di scadenza. Corrisponde alla chiave omonima di Apple Kerberos SSO Extension.
`ExpirationNotificationStartDay`	Integer	`14`	Avviso attivo. Giorni prima della scadenza in cui una finestra di dialogo di avviso viene mostrata automaticamente una volta al giorno. Deve essere impostato al di sotto di `ExpirationCountdownStartDay` in modo che la finestra di dialogo interrompa l’utente solo quando la scadenza è davvero imminente. Corrisponde alla chiave omonima di Jamf Connect / Apple Kerberos SSO Extension.
`passwordChangeURL`	String	—	URL di un portale web self-service per le password (SSPR). Se impostato, nella finestra di dialogo di scadenza appare un pulsante Cambia password che apre questo URL nel browser predefinito. Se non impostato, l’utente può cambiare la password direttamente nell’app (richiede `kerberosRealm`).
`allowPasswordChange`	Boolean	`false`	Quando `true`, nella barra dei menu viene mostrato permanentemente un elemento Cambia password…, anche prima che venga raggiunta la soglia di scadenza. Si trasforma automaticamente nel conto alla rovescia di scadenza quando la soglia viene raggiunta. Se è impostato anche `passwordChangeURL`, il clic apre quell’URL invece della finestra di dialogo integrata. Corrisponde alla chiave omonima di Apple Kerberos SSO Extension.

Suggerimento — strategia di scadenza a due livelli: Impostare ExpirationCountdownStartDay a un valore superiore a ExpirationNotificationStartDay. Esempio: il conto alla rovescia appare a 14 giorni (passivo, visibile solo nel menu), la finestra di dialogo a 7 giorni (attiva, una volta al giorno). Impostare ExpirationCountdownStartDay su 0 disabilita entrambi gli avvisi completamente.

3. Avvio automatico e ciclo di vita dell’app

Queste chiavi controllano se l’app si avvia automaticamente al login e come si comporta alla chiusura.

Chiave	Tipo	Predefinito	Descrizione
`autostart`	Boolean	`false`	Quando distribuita come chiave MDM bloccata, il valore viene applicato a ogni avvio dell’app. Quando distribuita come valore predefinito non bloccato, viene applicato solo al primo avvio — successivamente l’utente mantiene il controllo.
`canChangeAutostart`	Boolean	`true`	Controlla solo la visibilità dell’interruttore di avvio automatico nelle preferenze dell’app. Impostare su `false` per disabilitarlo visivamente. Non influisce sull’applicazione MDM. Per imporre lo stato di avvio automatico a ogni avvio, distribuire `autostart` come chiave bloccata.
`canQuit`	Boolean	`true`	Quando `true`, l’utente può chiudere l’app dalla barra dei menu. Impostare su `false` per rimuovere completamente la voce Esci.
`unmountOnExit`	Boolean	`true`	Quando `true`, tutte le condivisioni gestite vengono smontate automaticamente alla chiusura dell’app.

Come funziona l’applicazione dell’avvio automatico (macOS 13+)

NSM utilizza l’API SMAppService di Apple per registrarsi come elemento di accesso. macOS gestisce questo come LaunchAgent in /Library/LaunchAgents/de.fau.rrze.NetworkShareMounter.plist (proprietà root). Questo è il comportamento standard di macOS, con le seguenti implicazioni per gli amministratori MDM:

Il comando osascript tell application "System Events" to delete login item "…" non funziona per gli elementi registrati con SMAppService. System Events gestisce solo i vecchi elementi di accesso utente.
Quando autostart = false viene applicato tramite una chiave MDM bloccata, NSM chiama SMAppService.unregister() a ogni avvio e macOS rimuove automaticamente il file LaunchAgent.
Se gestisci l’avvio automatico tramite un proprio LaunchAgent o payload di elementi di accesso, imposta autostart = false come chiave bloccata per impedire a NSM di registrare un elemento in conflitto.

Impedire agli utenti di disabilitare l’avvio automatico

macOS 13 (Ventura) e versioni successive consentono agli utenti di disabilitare liberamente le app in background tramite le Impostazioni di Sistema. Per imporre l’avvio automatico e impedire agli utenti di disabilitare NSM, distribuire un payload Managed Login Items insieme al profilo di configurazione:

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

Attivare l’avvio automatico iniziale

A causa del design della sicurezza di macOS, un’app deve essere aperta almeno una volta prima che la registrazione dell’elemento di accesso abbia effetto. Per un deployment silenzioso senza interazione dell’utente, configurare il MDM per avviare NSM una volta immediatamente dopo l’installazione o al primo accesso.

Esempio di policy Jamf:

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

4. Interfaccia utente

Queste chiavi controllano la posizione di montaggio, l’aspetto della barra dei menu e quali voci del menu sono accessibili agli utenti.

Chiave	Tipo	Predefinito	Descrizione
`location`	String	—	Percorso in cui vengono montate le condivisioni di rete. Il valore predefinito è una cartella localizzata nella home directory dell’utente (ad es. `~/Network Shares`). ⚠️ Si raccomanda vivamente di lasciare questo campo vuoto e usare il valore predefinito. Modificarlo può compromettere l’integrazione con il Finder.
`cleanupLocationDirectory`	Boolean	`false`	Quando `true`, NSM rimuove file e directory vuote nella posizione di montaggio che impedirebbero il montaggio di una condivisione. Leggere attentamente la documentazione prima di attivarlo — questa opzione modifica il filesystem dell’utente.
`showMountsInMenu`	Boolean	`true`	Quando `true`, le condivisioni montate e smontate vengono elencate individualmente nella barra dei menu per un accesso rapido con un solo clic.
`helpURL`	String	—	URL all’helpdesk interno o alla documentazione IT della propria organizzazione. Quando impostato, nella barra dei menu appare la voce Informazioni su Network Share Mounter che apre questo URL nel browser predefinito.

È possibile mostrare, nascondere o disabilitare le singole voci della barra dei menu tramite le seguenti chiavi. Impostare il valore su hidden per rimuovere completamente la voce, o su disabled per disabilitarla senza rimuoverla. Se una chiave non è definita, la voce viene mostrata normalmente.

Chiave	Controlla
`menuConnectShares`	Azione Monta condivisioni
`menuDisconnectShares`	Azione Smonta condivisioni
`menuShowSharesMountDir`	Mostra condivisioni montate (apre la cartella di montaggio nel Finder)
`menuShowShares`	Singole voci delle condivisioni nell’elenco
`menuSettings`	Voce Preferenze…
`menuCheckUpdates`	Voce Cerca aggiornamenti…
`menuAbout`	Voce Informazioni su Network Share Mounter (visibile solo se `helpURL` è impostato)
`menuQuit`	Voce Esci da Network Share Mounter

Esempio — nascondere Preferenze e Aggiornamenti agli utenti:

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

5. Gestione degli aggiornamenti software

NSM utilizza il framework Sparkle per gli aggiornamenti automatici. Negli ambienti gestiti, è generalmente consigliabile disabilitarlo e gestire gli aggiornamenti tramite MDM.

Chiave	Tipo	Predefinito	Descrizione
`disableAutoUpdateFramework`	Boolean	`false`	Interruttore principale. Impostare su `true` per disabilitare completamente il framework di aggiornamento Sparkle. Quando disabilitato, non vengono effettuati controlli sugli aggiornamenti e la voce Cerca aggiornamenti viene rimossa.
`SUEnableAutomaticChecks`	Boolean	`true`	Quando il framework è abilitato, controlla se NSM cerca attivamente nuove versioni in background. Impostare su `false` per sopprimere i controlli mantenendo il framework caricato.
`SUAutomaticallyUpdate`	Boolean	`true`	Quando `true`, gli aggiornamenti vengono scaricati e installati automaticamente senza chiedere conferma all’utente. Ha effetto solo quando `SUEnableAutomaticChecks` è anch’esso `true`.

Nota: la chiave legacy enableAutoUpdater (logica invertita) è ancora accettata e viene migrata automaticamente al primo avvio. Usare disableAutoUpdateFramework in tutti i nuovi profili.

6. Scripting e automazione

NSM risponde ai segnali UNIX, consentendo a script esterni di attivare operazioni di montaggio e smontaggio senza usare l’interfaccia dell’app. Questo è utile per i flussi di lavoro dei portali self-service che permettono agli utenti di «riparare» le unità di rete.

Segnale	Azione
`SIGUSR1`	Smonta tutte le condivisioni
`SIGUSR2`	Monta tutte le condivisioni

Esempio:

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

# Smontare tutte le condivisioni
kill -SIGUSR1 "$NSM_PID"

# Montare tutte le condivisioni
kill -SIGUSR2 "$NSM_PID"

7. Problemi noti e compatibilità

Jamf Pro: la raccolta dell’inventario (recon) si blocca

Quando le condivisioni vengono montate nella home directory dell’utente (comportamento predefinito), il processo di inventario Jamf Pro (recon) potrebbe bloccarsi indefinitamente. Questo accade perché Jamf tenta di calcolare la dimensione totale della home directory, il che causa la scansione di tutte le condivisioni di rete montate.

Soluzione: In Jamf Pro, andare su Settings > Computer Management - Management Framework > Inventory Collection e disabilitare Include home directory sizes. In alternativa, impostare la chiave location su un percorso al di fuori della home directory, come /Volumes.

Se si utilizza ancora il Network Share Mounter legacy (v3/v2), la documentazione è disponibile nel nostro repository.