Funzione NetCreateProvisioningPackage (lmjoin.h)

Articolo
02/01/2024

La funzione NetCreateProvisioningPackage crea un pacchetto di provisioning che effettua il provisioning di un account computer per un uso successivo in un'operazione di aggiunta a un dominio offline. Il pacchetto può anche contenere informazioni sui certificati e i criteri da aggiungere al computer durante il provisioning.

Sintassi

NET_API_STATUS NET_API_FUNCTION NetCreateProvisioningPackage(
  [in]            PNETSETUP_PROVISIONING_PARAMS pProvisioningParams,
  [out, optional] PBYTE                         *ppPackageBinData,
  [out, optional] DWORD                         *pdwPackageBinDataSize,
  [out, optional] LPWSTR                        *ppPackageTextData
);

Parametri

[in] pProvisioningParams

Puntatore a una struttura NETSETUP_PROVISIONING_PARAMS che contiene informazioni sul pacchetto di provisioning.

Per i membri di questa struttura vengono definiti i valori seguenti:

Valore	Significato
dwVersion	Versione di Windows nel pacchetto di provisioning. Questo membro deve usare il valore seguente definito nel file di intestazione Lmjoin.h : NETSETUP_PROVISIONING_PARAMS_CURRENT_VERSION (0x00000001)
lpDomain	Puntatore a una stringa di caratteri con terminazione Null costante che specifica il nome del dominio in cui viene creato l'account computer.
lpMachineName	Puntatore a una stringa di caratteri con terminazione Null costante che specifica il nome breve del computer da cui deriva l'attributo dell'account computer sAMAccountName aggiungendo un valore '$'. Questo parametro deve contenere un nome di computer DNS o NetBIOS valido.
lpMachineAccountOU	Puntatore facoltativo a una stringa di caratteri con terminazione Null costante contenente il nome di formato RFC 1779 dell'unità organizzativa in cui verrà creato l'account computer. Se si specifica questo parametro, la stringa deve contenere un percorso completo, ad esempio OU=testOU,DC=domain,DC=Domain,DC=com. In caso contrario, questo parametro deve essere NULL. Se questo parametro è NULL, il contenitore di oggetti computer noto verrà usato come pubblicato nel dominio.
lpDcName	Puntatore facoltativo a una stringa di caratteri con terminazione Null costante contenente il nome del controller di dominio di destinazione.
dwProvisionOptions	Set di flag di bit che definiscono le opzioni di provisioning. Questo parametro può essere uno o più dei valori specificati per il parametro dwOptions passato alla funzione NetProvisionComputerAccount . Questi valori possibili sono definiti nel file di intestazione Lmjoin.h . L'opzione NETSETUP_PROVISION_ROOT_CA_CERTS è supportata solo in Windows 8 e Windows Server 2012.
aCertTemplateNames	Puntatore facoltativo a una matrice di nomi di modelli di certificato con terminazione NULL.
cCertTemplateNames	Quando aCertTemplateNames non è NULL, questo membro fornisce un conteggio esplicito del numero di elementi nella matrice.
aMachinePolicyNames	Puntatore facoltativo a una matrice di nomi di criteri computer con terminazione NULL.
cMachinePolicyNames	Quando aMachinePolicyNames non è NULL, questo membro fornisce un conteggio esplicito del numero di elementi nella matrice.
aMachinePolicyPaths	Puntatore facoltativo a una matrice di stringhe di caratteri. Ogni elemento della matrice è una stringa di caratteri con terminazione NULL che specifica il percorso completo o parziale di un file nel formato file dei criteri del Registro di sistema. Per altre informazioni sul formato del file dei criteri del Registro di sistema, vedere Formato di file dei criteri del Registro di sistema Il percorso può essere un percorso UNC in un server remoto.
cMachinePolicyPaths	Quando aMachinePolicyPaths non è NULL, questo membro fornisce un conteggio esplicito del numero di elementi nella matrice.

[out, optional] ppPackageBinData

Puntatore facoltativo che riceverà il pacchetto richiesto dalla funzione NetRequestOfflineDomainJoin per completare un aggiunta a un dominio offline, se la funzione NetProvisionComputerAccount viene completata correttamente. I dati vengono restituiti come buffer binario opaco che può essere passato alla funzione NetRequestOfflineDomainJoin .

Se questo parametro è NULL, il parametro pPackageTextData non deve essere NULL. Se questo parametro non è NULL, il parametro pPackageTextData deve essere NULL.

[out, optional] pdwPackageBinDataSize

Puntatore a un valore che riceve le dimensioni, in byte, del buffer restituito nel parametro pProvisionBinData .

Questo parametro non deve essere NULL se il parametro pPackageBinData non è NULL. Questo parametro deve essere NULL quando il parametro pPackageBinData è NULL.

[out, optional] ppPackageTextData

Puntatore facoltativo che riceverà il pacchetto richiesto dalla funzione NetRequestOfflineDomainJoin per completare un aggiunta a un dominio offline, se la funzione NetProvisionComputerAccount viene completata correttamente. I dati vengono restituiti in formato stringa per l'incorporamento in un file di risposte di installazione automatica.

Se questo parametro è NULL, il parametro pPackageBinData non deve essere NULL. Se questo parametro non è NULL, il parametro pPackageBinData deve essere NULL.

Valore restituito

Se la funzione ha esito positivo, il valore restituito viene NERR_Success.

Se la funzione ha esito negativo, il valore restituito può essere uno dei codici di errore seguenti o uno dei codici di errore di sistema seguenti.

Codice restituito	Descrizione
ERROR_ACCESS_DENIED	Accesso negato. Questo errore viene restituito se il chiamante non dispone di privilegi sufficienti per completare l'operazione.
ERROR_INVALID_DOMAIN_ROLE	Questa operazione è consentita solo per il controller di dominio primario del dominio. Questo errore viene restituito se è stato specificato un nome di controller di dominio nell'lpDcName dello struct NETSETUP_PROVISIONING_PARAMS a cui punta il parametro pProvisioningParams, ma non è stato possibile convalidare il computer specificato come controller di dominio per il dominio di destinazione specificato nell'lpDomain del NETSETUP_PROVISIONING_PARAMS.
ERROR_INVALID_PARAMETER	Un parametro non è corretto. Questo errore viene restituito anche se il parametro pProvisioningParams è NULL. Questo errore viene restituito anche se il membro lpDomain o lpMachineName dello struct NETSETUP_PROVISIONING_PARAMS a cui punta il parametro pProvisioningParams è NULL.
ERROR_NO_SUCH_DOMAIN	Il dominio specificato non esiste.
ERROR_NOT_SUPPORTED	La richiesta non è supportata. Questo errore viene restituito se il membro lpMachineAccountOU è stato specificato nello struct NETSETUP_PROVISIONING_PARAMS a cui punta il parametro pProvisioningParams e il controller di dominio è in esecuzione in una versione precedente di Windows che non supporta questo parametro.
NERR_DS8DCRequired	Il controller di dominio specificato non soddisfa il requisito di versione per questa operazione.
NERR_LDAPCapableDCRequired	Questa operazione richiede un controller di dominio che supporta LDAP.
NERR_UserExists	L'account esiste già nel dominio e il bit NETSETUP_PROVISION_REUSE_ACCOUNT non è stato specificato nel membro dwProvisionOptions dello struct NETSETUP_PROVISIONING_PARAMS a cui punta il parametro pProvisioningParams .
NERR_WkstaNotStarted	Il servizio Workstation non è stato avviato.
RPC_S_CALL_IN_PROGRESS	Una chiamata di procedura remota è già in corso per questo thread.
RPC_S_PROTSEQ_NOT_SUPPORTED	La sequenza di protocollo di chiamata di procedura remota non è supportata.

Commenti

La funzione NetCreateProvisioningPackage è supportata in Windows 8 e Windows Server 2012 per le operazioni di join offline. Per Windows 7, usare la funzione NetProvisionComputerAccount .

La funzione NetCreateProvisioningPackage viene usata per effettuare il provisioning di un account computer per usarlo successivamente in un'operazione di aggiunta a un dominio offline tramite la funzione NetRequestProvisioningPackageInstall .

Lo scenario di aggiunta a un dominio offline usa due funzioni:

NetCreateProvisioningPackage è una funzione di provisioning che viene prima chiamata per eseguire le operazioni di rete necessarie per creare e configurare l'oggetto computer in Active Directory. L'output di NetCreateProvisioningPackage è un pacchetto usato per il passaggio successivo.
NetRequestProvisioningPackageInstall, una funzione di inizializzazione dell'immagine, viene chiamata per inserire l'output dalla funzione di provisioning NetCreateProvisioningPackage in un'immagine del sistema operativo Windows da usare durante la pre-installazione e dopo l'installazione.

Le modifiche apportate al codice di inizializzazione di Windows rileveranno questo stato salvato e influiranno sulla parte locale di aggiunta a un dominio.

Quando vengono usati i puntatori di uscita pPackageBinDataData e pdwPackageBinDataSize , impostare il puntatore di uscita pPackageTextData su NULL. Quando si usa pPackageTextData , impostare i puntatori a pPackageBinData e pdwPackageBinDataSize su NULL.

Il parametro pProvisioningParams specifica i dati da includere nel pacchetto di provisioning. Il pacchetto include informazioni rilevanti per l'aggiunta al dominio e può includere anche informazioni sui criteri e i certificati da installare nel computer. Il pacchetto di provisioning può essere usato in quattro modi:

Aggiunta a un dominio
Aggiunta a un dominio e installazione di certificati
Aggiunta a un dominio e installazione dei criteri
Aggiunta a un dominio e installazione di certificati e criteri

La funzione NetCreateProvisioningPackage crea o riutilizza l'account del computer nel dominio, raccoglie tutti i metadati necessari e lo restituisce in un pacchetto. Il pacchetto può essere utilizzato dall'operazione di richiesta di aggiunta al dominio offline fornendo tutto l'input necessario per completare l'aggiunta al dominio durante il primo avvio senza alcuna operazione di rete (solo aggiornamenti dello stato locale).

Nota sulla sicurezza: Il pacchetto restituito dalla funzione NetCreateProvisioningPackage contiene dati molto sensibili. Deve essere trattato in modo sicuro come una password di testo non crittografato. Il pacchetto contiene la password dell'account computer e altre informazioni sul dominio, tra cui il nome di dominio, il nome di un controller di dominio e l'ID di sicurezza (SID) del dominio. Se il pacchetto viene trasportato fisicamente o in rete, è necessario prestare attenzione al trasporto sicuro. La progettazione non effettua alcuna disposizione per la protezione di questi dati. Questo problema esiste oggi con i file di risposte di installazione automatica che possono contenere un certo numero di segreti, tra cui password utente di dominio. Il chiamante deve proteggere il pacchetto. Le soluzioni a questo problema sono diverse. Ad esempio, è possibile usare una chiave pre-scambiata per crittografare una sessione tra il consumer e l'entità di provisioning, consentendo un trasferimento sicuro del pacchetto.

Il pacchetto restituito nel parametro pPackageBinData dalla funzione NetCreateProvisioningPackage viene sottoposto a controllo delle versioni per consentire scenari di interoperabilità e gestibilità tra versioni diverse di Windows, ad esempio l'aggiunta di un client, il provisioning di un computer e l'uso di un controller di dominio. Un pacchetto creato in Windows 8 o Windows Server 2012 può essere usato Windows 7 o Windows Server 2008 R2, ma solo le informazioni sull'aggiunta a un dominio avranno effetto (i certificati e i criteri non sono supportati). Lo scenario di join offline attualmente non limita la durata del pacchetto restituito dalla funzione NetCreateProvisioningPackage .

Per i join di dominio offline, il controllo di accesso eseguito dipende dalla configurazione del dominio. La creazione dell'account computer è abilitata usando tre metodi:

Gli amministratori di dominio dispongono dei diritti per creare account computer.
Sd in un contenitore può delegare i diritti per creare account computer.
Per impostazione predefinita, gli utenti autenticati possono creare account computer con privilegi. Gli utenti autenticati sono limitati alla creazione di un numero limitato di account specificati come quota nel dominio (il valore predefinito è 10). Per altre informazioni, vedere l'attributo ms-DS-MachineAccountQuota nello schema di Active Directory.

La funzione NetCreateProvisioningPackage funziona solo con un controller di dominio scrivibile e non funziona su un controller di dominio di sola lettura. Dopo aver eseguito il provisioning su un controller di dominio scrivibile e l'account viene replicato in un controller di dominio di sola lettura, le altre parti dell'operazione di aggiunta al dominio offline non richiedono l'accesso a un controller di dominio.

Se la funzione NetCreateProvisioningPackage ha esito positivo, il puntatore nel parametro pPackageBinData o pPackageTextData (a seconda del parametro non NULL) viene restituito con i dati serializzati da utilizzare in un'operazione di join offline o come testo in un file di installazione automatica.

Tutte le fasi del processo di provisioning vengono aggiunte a un file NetSetup.log nel computer locale. Il processo di provisioning può includere fino a tre computer diversi: il computer in cui viene creato il pacchetto di provisioning, il computer che richiede l'installazione del pacchetto e il computer in cui è installato il pacchetto. Saranno presenti NetSetup.log informazioni sui file archiviate in tutti e tre i computer in base all'operazione eseguita. Esaminare il contenuto di questi file è il mezzo più comune per la risoluzione degli errori di provisioning online e offline. Le operazioni di provisioning eseguite dagli amministratori vengono registrate nel file NetSetup.log in %WINDIR%\Debug. Le operazioni di provisioning eseguite da utenti non amministratori vengono registrate nel file NetSetup.log nella cartella %USERPROFILE%\Debug .

Per altre informazioni sulle operazioni di aggiunta a un dominio offline, vedere la Guida dettagliata all'aggiunta a un dominio offline.

L'aggiunta di un computer a un dominio tramite NetJoinDomain e NetUnjoinDomain viene eseguita solo da un membro del gruppo locale Administrators nel computer di destinazione. Si noti che l'amministratore di dominio può impostare requisiti aggiuntivi per l'aggiunta al dominio usando la delega e l'assegnazione dei privilegi.

Requisiti


Client minimo supportato	Windows 8 [solo app desktop]
Server minimo supportato	Windows Server 2012 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	lmjoin.h (include Lm.h)
Libreria	Netapi32.lib
DLL	Netapi32.dll