NetRequestProvisioningPackageInstall function (lmjoin.h)
The NetRequestProvisioningPackageInstall function executes locally on a machine to modify a Windows operating system image mounted on a volume. The registry is loaded from the image and provisioning package data is written where it can be retrieved during the completion phase of an offline domain join operation.
Syntax
NET_API_STATUS NET_API_FUNCTION NetRequestProvisioningPackageInstall(
[in] BYTE *pPackageBinData,
[in] DWORD dwPackageBinDataSize,
[in] DWORD dwProvisionOptions,
[in] LPCWSTR lpWindowsPath,
PVOID pvReserved
);
Parameters
[in] pPackageBinData
A pointer to a buffer required to initialize the registry of a Windows operating system image to process the final local state change during the completion phase of the offline domain join operation.
The opaque binary blob of serialized metadata passed in the pPackageBinData parameter is returned by the NetCreateProvisioningPackage function.
[in] dwPackageBinDataSize
The size, in bytes, of the buffer pointed to by the pPackageBinData parameter.
This parameter must not be NULL.
[in] dwProvisionOptions
A set of bit flags that define options for this function. This parameter uses one or more of the following values defined in the Lmjoin.h header file.
[in] lpWindowsPath
A pointer to a NULL-terminated character string that specifies the path to a Windows operating system image under which the registry hives are located. This image must be offline and not currently booted unless the dwProvisionOptions parameter contains NETSETUP_PROVISION_ONLINE_CALLER, in which case, the locally running operating system directory is allowed.
This path could be a UNC path on a remote server.
pvReserved
Reserved for future use.
Return value
If the function succeeds, the return value is NERR_Success.
If the function fails, the return value can be one of the following Network Management error codes.
| Return code | Description |
|---|---|
|
The offline join completion information was not found. |
|
The offline join completion information was bad. |
|
Unable to create offline join information. Please ensure you have access to the specified path location and permissions to modify its contents. Running as an elevated administrator may be required. |
|
The domain join info being saved was incomplete or bad. |
|
Offline join operation successfully completed but a restart is needed. |
|
There was no offline join operation pending. |
|
Unable to set one or more requested machine or domain name values on the local computer. |
|
Could not verify the current machine's hostname against the saved value in the join completion information. |
|
Unable to load the specified offline registry hive. Please ensure you have access to the specified path location and permissions to modify its contents. Running as an elevated administrator may be required. |
|
The minimum session security requirements for this operation were not met. |
|
Computer account provisioning blob version is not supported. |
Remarks
The NetRequestProvisioningPackageInstall function is supported on Windows 8 for offline domain join operations. For Windows 7, use NetRequestOfflineDomainJoin.
The offline domain join scenario uses two functions:
- NetCreateProvisioningPackage is a provisioning function that is first called to perform the network operations necessary to create and configure the computer object in Active Directory. The output from the NetCreateProvisioningPackage is a package used for the next step.
- NetRequestProvisioningPackageInstall, an image initialization function, is called to inject the output from the NetCreateProvisioningPackage provisioning function into a Windows operating system image for use during installation.
The NetCreateProvisioningPackage function will create or reuse the machine account in the domain, collect all necessary metadata and return it in a package. The package can be consumed by the offline domain join request operation supplying all the necessary input to complete the domain join during first boot without any network operations (local state updates only).
Security Note: The package created by the NetCreateProvisioningPackage function contains very sensitive data. It should be treated just as securely as a plaintext password. The package contains the machine account password and other information about the domain, including the domain name, the name of a domain controller, and the security ID (SID) of the domain. If the package is being transported physically or over the network, care must be taken to transport it securely. The design makes no provisions for securing this data. This problem exists today with unattended setup answer files which can carry a number of secrets including domain user passwords. The caller must secure the package. Solutions to this problem are varied. As an example, a pre-exchanged key could be used to encrypt a session between the consumer and provisioning entity enabling a secure transfer of the package.
The package returned in the pPackageBinData parameter by the NetCreateProvisioningPackage function is versioned to allow interoperability and serviceability scenarios between different versions of Windows (such as joining a client, provisioning a machine, and using a domain controller). The offline join scenario currently does not limit the lifetime of the package returned by the NetCreateProvisioningPackage function.
All phases of the provisioning process append to a NetSetup.log file on the local computer. The provisioning process can include up to three different computers: the computer where the provisioning package is created, the computer that requests the installation of the package, and the computer where the package is installed. There will be NetSetup.log file information stored on all three computers according to the operation performed. Reviewing the contents of these files is the most common means of troubleshooting online and offline provisioning errors. Provisioning operations undertaken by admins are logged to the NetSetup.log file in the %WINDIR%\Debug. Provisioning operations performed by non-admins are logged to the NetSetup.log file in the %USERPROFILE%\Debug folder.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8 [desktop apps only] |
| Minimum supported server | Windows Server 2012 [desktop apps only] |
| Target Platform | Windows |
| Header | lmjoin.h (include Lm.h) |
| Library | Netapi32.lib |
| DLL | Netapi32.dll |
See also
NetProvisionComputerAccount