Merge pull request #32 from SvenGroot/v2.0-dev

Merge v2.0 into main

Author: SvenGroot

README.md

@@ -14,20 +14,20 @@ available through this tool. Customizations supported by the Answer File Generat
 - The installation method, partition layout, and target disk and partition.
 - Enabling optional features during installation.
 - Creation of local user accounts.
-- Joining a domain and adding domain accounts to the local Administrators group.
+- Joining a domain, and adding domain accounts to a local security group.
 - Configuring automatic log-on.
 - The product key, computer name, language/culture, and time zone.
 - Display resolution.
 - Disabling Windows Defender.
 - Enabling remote desktop access.
 - Running PowerShell scripts and other commands on first log-on.
 
-All of these items can be customized using command line arguments. In addition, the answer files
-generated here will always skip the entire OOBE experience unless no local account was created and
-no domain was joined.
+Answer files generated by this application will always skip the entire OOBE experience, unless no
+local account was created and no domain was joined.
 
 Below, the core functionality is explained with several examples. You can also check the
-[full list of command line arguments](doc/CommandLine.md), or run `./GenerateAnswerFile -Help`.
+[full list of command line arguments](doc/CommandLine.md), or run `./GenerateAnswerFile -Help`. It's
+also possible to specify customization options using a [JSON file](doc/Json.md).
 
 See [what's new in Answer File Generator](doc/ChangeLog.md).
 
@@ -71,18 +71,19 @@ command to list the images in an install.wim or install.esd file.
 
 Passwords are needed for several actions taken by the answer file. When creating local accounts,
 their initial password must be set. To join a domain, the password of a domain account with
-the appropriate permissions must be specified. For automatic log-on, you must specify the password
-of the account that will be logged on.
-
-:warning: **Passwords in answer files are not securely stored** :warning:
-
-They are at best base64-encoded (which is easily reversible), and at worst just stored in plain
-text. Do not store answer files with sensitive passwords in unsecure locations, and delete such
-files when you are done with them.
-
-The answer file generator also does not treat these passwords securely (it can't, to be able to
-write them out to the answer file in this fashion), so copies of the passwords may remain in system
-memory after the application is terminated.
+the appropriate permissions must be specified (unless a provisioned computer account is used). For
+automatic log-on, you must specify the password of the account that will be logged on.
+
+> [!WARNING]
+> Passwords in answer files are not securely stored!
+>
+> They are at best base64-encoded (which is easily reversible), and at worst just stored in plain
+> text. Do not store answer files with sensitive passwords in unsecure locations, and delete such
+> files when you are done with them.
+>
+> The answer file generator also does not treat these passwords securely (it can't, to be able to
+> write them out to the answer file in this fashion), so copies of the passwords may remain in system
+> memory after the application is terminated.
 
 ## Time zone
 
@@ -123,7 +124,7 @@ such as "x86" for 32 bit processors, or "arm64" for ARM based systems.
 ```text
 ./GenerateAnswerFile autounattend.xml `
     -Install CleanEfi `
-    -LocalAccount "John,Password" "Steve,OtherPassword" `
+    -LocalAccount "John,Password" "Users:Steve,OtherPassword" `
     -ProductKey ABCDE-12345-ABCDE-12345-ABCDE
 ```
 
@@ -132,42 +133,22 @@ password, obviously), and a user named "Steve" with the password "OtherPassword"
 [`-LocalAccount`][] argument takes one or more values, allowing the creation of any number of
 accounts.
 
-All accounts created during this method will be members of the local Administrators group.
-
-### Joining a domain and automatic log-on
-
-```text
-./GenerateAnswerFile unattend.xml `
-    -ComputerName mypc `
-    -JoinDomain mydomain `
-    -JoinDomainUser domainuser `
-    -JoinDomainPassword Password `
-    -DomainAccount domainuser `
-    -AutoLogonUser mydomain\domainuser `
-    -AutoLogonPassword Password
-```
-
-The answer file created by this command sets the computer name to "mypc" and joins it to the domain
-"mydomain", using the supplied credentials. It also adds the account "domainuser" from the
-"mydomain" domain to the local Administrators group, and logs in using that account automatically on
-first boot.
+By default, accounts created using this method will be added to the local Administrators group.
+You can customize which group(s) to add them to by prefixing the account name with the group,
+separated by a colon. You can use multiple groups by separating them with a semicolon.
 
-This sample does not use the [`-Install`][] argument, so it creates an answer file suitable for
-pre-installed Windows images, such as those created using sysprep or DISM tools. The
-[`-JoinDomain`][] argument can be used with any install method, however.
-
-The [`-AutoLogonUser`][] argument can be used for both domain or local accounts; to use a local
-account, specify the user name only, without a domain. To log in automatically more than once, use
-the [`-AutoLogonCount`][] argument[^1].
+In the above example, John is an administrator, but Steve is added to the Users group, so they will
+be a restricted user.
 
 ### Custom partition layout
 
-If you use the `CleanEfi` or `CleanBios`, you can choose to customize the partition layout for the
-disk specified by [`-InstallToDisk`][], by using the [`-Partition`][] argument. This argument accepts
-multiple values, each creating a partition on that disk in the order specified.
+If you use the `CleanEfi` or `CleanBios` installation method, you can choose to customize the
+partition layout for the disk specified by [`-InstallToDisk`][], by using the [`-Partition`][]
+argument. This argument accepts multiple values, each creating a partition on that disk in the order
+specified.
 
 If the [`-Partition`][] argument is not specified, the default partition layout for the install
-method is used, as specified in the table above.
+method is used, as listed in the table above.
 
 The [`-Partition`][] argument uses the format `label:size`, where label is the volume label, and
 size is the size of the partition. The size can use multiple-byte units, such as GB or MB[^2], and
@@ -198,9 +179,9 @@ data partitions with that label. These will be assigned drive letters in the ord
 specified, starting with `C:`.
 
 You can use the format `label:size[fs]`, where fs is a file system like FAT32 or NTFS, to specify
-a file system to format the volume with. If no file system is specified, it defaults to NTFS except
+a file system to format the volume with. If no file system is specified, it defaults to NTFS, except
 for EFI partitions, which must be FAT32. MSR partitions are not formatted, so this attribute is
-ignored.
+ignored for that partition type.
 
 You can use the [`-InstallToPartition`][] argument to specify which partition should hold the OS. If you
 don't supply this argument, Windows will be installed on the first regular data partition.
@@ -244,24 +225,81 @@ using sysprep, or by using DISM tools.
 ./GenerateAnswerFile autounattend.xml `
     -Install CleanEfi `
     -FirstLogonCommand "reg add HKCU\Software\MyCompany /v ImportantRegistryKey /t REG_DWORD /d 1 /f" `
-    -SetupScript "\\server\share\script.ps1 -Argument" `
+    -FirstLogonScript "\\server\share\script.ps1 -Argument" `
     -LocalAccount "John,Password" `
     -AutoLogonUser John `
     -AutoLogonPassword Password `
     -ProductKey ABCDE-12345-ABCDE-12345-ABCDE
 ```
 
-The [`-FirstLogonCommand`][] argument can be used to execute a command when a user first logs on to the
-system after installation (either manually, or automatically as in the above example). For
-convenience, there is also a [`-SetupScript`][] argument which executes the specified Windows PowerShell
-script, including any arguments.
+The [`-FirstLogonCommand`][] argument can be used to execute a command when a user first logs on to
+the system after installation (either manually, or automatically as in the above example). For
+convenience, there is also a [`-FirstLogonScript`][] argument which executes the specified Windows
+PowerShell script, including any arguments. PowerShell scripts will be executed using the command
+`PowerShell.exe -ExecutionPolicy Bypass`.
 
 Either argument accepts multiple values to run multiple commands or scripts. Both are executed in
 the order they are supplied, but all commands will be executed before any scripts.
 
 If you execute any scripts, they must be stored in a location that is accessible to the system after
 installation, such as a network share like the example above.
 
+### Joining a domain and automatic log-on
+
+```text
+./GenerateAnswerFile unattend.xml `
+    -ComputerName mypc `
+    -JoinDomain mydomain `
+    -JoinDomainUser domainuser `
+    -JoinDomainPassword Password `
+    -DomainAccount domainuser `
+    -AutoLogonUser mydomain\domainuser `
+    -AutoLogonPassword Password
+```
+
+The answer file created by this command sets the computer name to "mypc" and joins it to the domain
+"mydomain", using the supplied credentials. It also adds the account "domainuser" from the
+"mydomain" domain to the local Administrators group, and logs in using that account automatically on
+first boot.
+
+This sample does not use the [`-Install`][] argument, so it creates an answer file suitable for
+pre-installed Windows images, such as those created using sysprep or DISM tools. The
+[`-JoinDomain`][] argument can be used with any install method, however.
+
+The [`-AutoLogonUser`][] argument can be used for both domain or local accounts; to use a local
+account, specify the user name only, without a domain. To log in automatically more than once, use
+the [`-AutoLogonCount`][] argument[^1].
+
+### Joining a domain using provisioning
+
+```text
+./GenerateAnswerFile unattend.xml `
+    -Install CleanEfi
+    -JoinDomainProvisioningFile AccountData.txt `
+    -JoinDomainOffline
+```
+
+Instead of embedding a domain account password into the answer file, you can provision a domain
+account using the `djoin.exe` utility, and use that to join the domain by passing the name of the
+file created by `djoin.exe` to the [`-JoinDomainProvisioningFile`][] argument.
+
+When using provisioning, you can also join the domain during the offlineServicing pass by using the
+[`-JoinDomainOffline`][] argument. This is not supported if you join a domain by using credentials.
+
+To provision a domain account for the computer, you can use the following command:
+
+```text
+djoin.exe /provision /domain domainname /machine machinename /savefile filename
+```
+
+## Using JSON to provide options
+
+Because the large number of command line arguments may get unwieldy, the Answer File Generator
+provides a custom JSON file format that can be used as an alternative way to provide the options
+for generating an answer file.
+
+For more information, see [the JSON file documentation](doc/Json.md).
+
 ## Using an answer file
 
 Please refer to the [official Microsoft documentation](https://learn.microsoft.com/windows-hardware/manufacture/desktop/windows-setup-automation-overview)
@@ -271,13 +309,13 @@ to see how to use an answer file during Windows setup.
 
 The core functionality for generating answer files is implemented in the
 [Ookii.AnswerFile library](doc/Library.md), which you can use in your own applications targeting
-.Net 7.0 or later.
+.Net 8.0 or later.
 
 ## Building and testing
 
 To build Answer File Generator, make sure you have the following installed:
 
-- [Microsoft .Net 7.0 SDK](https://dotnet.microsoft.com/download) or later
+- [Microsoft .Net 8.0 SDK](https://dotnet.microsoft.com/download) or later
 
 To build the application, library, and tests, simply use the `dotnet build` command in the `src`
 directory. You can run the unit tests using `dotnet test`.
@@ -306,10 +344,12 @@ any other adverse effects caused by the use of answer files generated by this to
 [`-InstallToPartition`]: doc/CommandLine.md#-installtopartition
 [`-ImageIndex`]: doc/CommandLine.md#-imageindex
 [`-JoinDomain`]: doc/CommandLine.md#-joindomain
+[`-JoinDomainOffline`]: doc/CommandLine.md#-joindomainoffline
+[`-JoinDomainProvisioningFile`]: doc/CommandLine.md#-joindomainprovisioningfile
 [`-LocalAccount`]: doc/CommandLine.md#-localaccount
 [`-Partition`]: doc/CommandLine.md#-partition
 [`-ProcessorArchitecture`]: doc/CommandLine.md#-processorarchitecture
 [`-ProductKey`]: doc/CommandLine.md#-productkey
-[`-SetupScript`]: doc/CommandLine.md#-setupscript
+[`-FirstLogonScript`]: doc/CommandLine.md#-firstlogonscript
 [`-TimeZone`]: doc/CommandLine.md#-timezone
 [`-WindowsVersion`]: doc/CommandLine.md#-windowsversion

doc/ChangeLog.md

@@ -1,5 +1,25 @@
 # What's new in Answer File Generator
 
+## Answer File Generator 2.0 (2024-10-07)
+
+- The [`-DomainAccount`][] argument now allows you to specify users from different domains than the
+  one you're joining.
+- The [`-LocalAccount`][] and [`-DomainAccount`][] arguments now allow you to customize which groups
+  the account is added to.
+- You can join a domain using provisioning with the new [`-JoinDomainProvisioningFile`][] argument,
+  and do it during the offlineServicing pass with the new [`-JoinDomainOffline`][] argument.
+- The `-CmdKeyUser` and `-CmdKeyPassword` arguments have been removed; this was a bad security
+  practice that I don't wish to promote. You can still get identical behavior using the
+  [`-FirstLogonCommand`][] argument if desired.
+- You can specify options using a [custom JSON file format](Json.md), as an alternative to using
+  command line arguments.
+- If no output file name is provided, the answer file is now written to the console.
+- The `-SetupScript` argument has been renamed to [`-FirstLogonScript`][], for consistency with the
+  [`-FirstLogonCommand`][] argument. A `-SetupScript` alias is provided for compatibility.
+- The Answer File Generator is now available in standalone single-file versions, that do not require
+  you to install the .Net Runtime.
+- There are some breaking changes to the [Ookii.AnswerFile library](Library.md#breaking-changes).
+
 ## Answer File Generator 1.1 (2023-10-10)
 
 - Apply a workaround for a [known issue with the `LogonCount` element](https://learn.microsoft.com/windows-hardware/customize/desktop/unattend/microsoft-windows-shell-setup-autologon-logoncount),
@@ -24,9 +44,13 @@
 
 [`-AutoLogonCount`]: CommandLine.md#-autologoncount
 [`-DisableServerManager`]: CommandLine.md#-disableservermanager
+[`-DomainAccount`]: CommandLine.md#-domainaccount
 [`-FirstLogonCommand`]: CommandLine.md#-firstlogoncommand
 [`-JoinDomain`]: CommandLine.md#-joindomain
+[`-JoinDomainOffline`]: doc/CommandLine.md#-joindomainoffline
+[`-JoinDomainProvisioningFile`]: doc/CommandLine.md#-joindomainprovisioningfile
 [`-JoinDomainUser`]: CommandLine.md#-joindomainuser
 [`-LocalAccount`]: CommandLine.md#-localaccount
 [`-Partition`]: CommandLine.md#-partition
-[`-SetupScript`]: CommandLine.md#-setupscript
+[`-FirstLogonScript`]: CommandLine.md#-firstlogonscript
+[`-SetupScript`]: CommandLine.md#-firstlogonscript