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.
`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>
    </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 NSM esegue da sé l’accesso a Kerberos (kerberosRealm è configurato e le condivisioni non usano externalKerberosManagement), può avvisare gli utenti prima della scadenza della loro password AD. Gli avvisi sono attivi per impostazione predefinita: entrambe le soglie sono di 14 giorni, quindi compaiono anche senza alcuna configurazione. Gli account la cui password non scade mai non ricevono avvisi.

Chiave	Tipo	Predefinito	Descrizione
`ExpirationCountdownStartDay`	Integer	`14`	Avviso passivo. Giorni prima della scadenza della password a partire dai quali compare un conto alla rovescia nella barra dei menu. L’utente lo vede solo aprendo il menu, senza interruzioni del lavoro. `0` disattiva tutti gli avvisi di scadenza della password, cioè il conto alla rovescia e la finestra di dialogo. Corrisponde all’omonima chiave dell’estensione Kerberos SSO di Apple.
`ExpirationNotificationStartDay`	Integer	`14`	Avviso attivo. Giorni prima della scadenza della password a partire dai quali viene mostrata automaticamente una finestra di dialogo, al massimo una volta per giorno di calendario. La finestra di dialogo non inizia mai prima del conto alla rovescia: se questo valore è superiore a `ExpirationCountdownStartDay`, inizia insieme al conto alla rovescia. `0` disattiva solo la finestra di dialogo, il conto alla rovescia rimane (dalla versione 4.1.6). Corrisponde all’omonima chiave di Jamf Connect e dell’estensione Kerberos SSO di Apple.
`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.

Configurazioni tipiche:

Obiettivo	Impostazione
Nessun avviso di scadenza della password	`ExpirationCountdownStartDay` = `0`
Solo conto alla rovescia nel menu, nessuna finestra di dialogo	`ExpirationNotificationStartDay` = `0` (dalla versione 4.1.6)
Conto alla rovescia da 14 giorni, finestra di dialogo da 7 giorni	`ExpirationCountdownStartDay` = `14`, `ExpirationNotificationStartDay` = `7`

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.
`disableDiagnostics`	Boolean	`false`	Quando `true`, nasconde la sezione Diagnostica (l’interruttore “Invia dati diagnostici anonimi” e lo strumento nascosto di esportazione dei log di debug) in Impostazioni → Generale.

È 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.

Namespace DFS basati sul dominio (smb://example.com/share)

Le condivisioni Kerberos che puntano al nome di dominio invece che a un file server possono non riuscire con “invalid credentials” anche se l’utente dispone di un ticket Kerberos valido. Di solito Active Directory non ha un service principal per il nome di dominio stesso (cifs/example.com). Un nome di server come smb://fileserver.example.com/share funziona, ma vincola gli utenti a un unico server.

Soluzione: A partire da macOS 26.5, i Mac non collegati ad Active Directory possono risolvere i namespace DFS tramite i domain controller. Distribuire /etc/nsmb.conf con il seguente contenuto, ad esempio come script o pacchetto tramite l’MDM, e mantenere l’URL basato sul dominio in managedNetworkShares:

[default]
srv_lookup_enabled=yes

Per i dettagli su questa impostazione, consultare la documentazione di Apple: https://support.apple.com/en-mz/guide/deployment/depd1a7cad1f/web

Platform SSO con un Active Directory locale

Con Platform SSO (Microsoft Entra ID), un Mac riceve per impostazione predefinita solo un ticket Kerberos per il cloud (tgt_cloud). Non è utilizzabile per i file server locali, quindi le condivisioni Kerberos non riescono con “invalid credentials” anche se è presente un ticket.

Soluzione: Attivare Microsoft Entra Kerberos affinché Platform SSO fornisca anche un ticket per il dominio locale (tgt_ad), e attivare Use TGT from Platform SSO for Kerberos requests nel payload dell’estensione Kerberos SSO. Contrassegnare le condivisioni con externalKerberosManagement in modo che NSM utilizzi questi ticket. La presenza di entrambi i ticket si può verificare con app-sso platform -s nel Terminale (sezione “User Configuration”).

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