PowerShell v3 in a Year Day 13 Add Computer

Topic: Add-Computer

One of those simple revelations I came to a few years back was that Windows machines exist in either one of two states: 1) as a workgroup member or 2) as a domain member. Not having gotten my MSCE, MCTS, etc, most of what I have learned has come through reading training materials for these certs, so, these sorts of terms are not intuitive. In the case of this cmdlet, you are given the ability to associate a computer (you can do both local and remote additions) with a given collection via the -ComputerName parameter. In any case, PowerShells v3 gives you a wide array of parameters with which to work as you use this cmdlet. v3 offers two parameter sets, as shown below:

• Add-Computer [-DomainName] <String> [-ComputerName <String[]>] [-Force [<SwitchParameter>]] [-LocalCredential <PSCredential>] [-NewName <String>] [-Options <JoinOptions>] [-OUPath <String>] [-PassThru [<SwitchParameter>]] [-Restart [<SwitchParameter>]] [-Server <String>] [-UnjoinDomainCredential <PSCredential>] [-Unsecure [<SwitchParameter>]] -Credential <PSCredential> [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]] [<CommonParameters>]
• Add-Computer [-WorkGroupName] <String> [-ComputerName <String[]>] [-Credential <PSCredential>] [-Force [<SwitchParameter>]] [-LocalCredential <PSCredential>] [-NewName <String>] [-PassThru [<SwitchParameter>]] [-Restart [<SwitchParameter>]] [-Confirm [<SwitchParameter>]] [-WhatIf [<SwitchParameter>]] [<CommonParameters>] 

As you can see above, there are a lot of options. Rather than address all of them, I will touch on the unique entries. If a parameter appears in both sets I will touch on it only once.

• DomainName: this parameter, belonging to the first parameter set, specifies the domain to which the computers are added. This parameter is required when adding the computers to a domain.
• ComputerName: this parameter, common to both sets, specifies the computers to add to a domain or workgroup. 
• The default is the local computer.
• Type the NetBIOS name, an Internet Protocol (IP) address, or a fully qualified domain name of each of the  remote computers. 
• To specify the local computer, type the computer name, a dot (.), or "localhost".
• This parameter does not rely on Windows PowerShell remoting. 
• You can use the ComputerName parameter of Add-Computer even if your computer is not configured to run remote commands.
• This parameter is introduced in Windows PowerShell 3.0.
• Force: this parameter, common to both sets, suppresses the user confirmation prompt. Without this parameter, Add-Computer requires you to confirm the addition of each computer.
• LocalCredential: this parameter, common to both sets, specifies a user account that has permission to connect to the computers that are specified by the ComputerName
• parameter. 
• The default is the current user.
• Type a user name, such as "User01" or "Domain01User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. 
• If you type a user name, you will be prompted for a password.
• To specify a user account that has permission to add the computers to a new domain, use the Credential parameter.
• To specify a user account that has permission to remove the computers from their current domain, use the UnjoinDomainCredential parameter.
• This parameter is introduced in Windows PowerShell 3.0.
• NewName: this parameter, common to both sets, specifies a new name for the computer in the new domain. This parameter is valid only when one computer is being added or moved.
• Options: this parameter was added in v3 and belongs to the first parameter set. It also sets advanced options for the Add-Computer join operation. Enter one or more values in a comma-separated string. Choices for Options are:
• -- AccountCreate: Creates a domain account. The Add-Computer cmdlet automatically creates a domain account when it adds a computer to a domain. This option is included for completeness.
• -- Win9XUpgrade: Indicates that the join operation is part of a Windows operating system upgrade.
• -- UnsecuredJoin: Performs an unsecured join. To request an unsecured join, use the Unsecure parameter or this option.
• -- PasswordPass: Sets the machine password to the value of the Credential (DomainCredential) parameter after performing an unsecured join. This option also indicates that the value of the Credential (DomainCredential) parameter is a machine password, not a user password. This option is valid only when the UnsecuredJoin option is specified.
•  -- JoinWithNewName: Renames the computer name in the new domain to the name specified by the NewName parameter. When you use the NewName parameter, this option is set automatically. This option is designed to be used with the Rename-Computer cmdlet. If you use the Rename-Computer cmdlet to rename the computer, but do not restart the computer to make the change effective, you can use this parameter to join the computer to a domain with its new name.
• -- JoinReadOnly: Uses an existing machine account to join the computer to a read-only domain controller. The machine account must be added to the allowed list for password replication policy and the account password must be replicated to the read-only domain controller prior to the join operation.
• -- InstallInvoke: Sets the create (0x2) and delete (0x4) flags of the FJoinOptions parameter of the JoinDomainOrWorkgroup method. For more information about the JoinDomainOrWorkgroup method, see "JoinDomainOrWorkgroup Method of the Win32_ComputerSystem Class" in MSDN at http://msdn.microsoft.com/en-us/library/aa392154(VS.85).aspx.
• OUPath: this parameter, belonging to the first parameter set, specifies an organizational unit (OU) for the domain account. 
• Enter the full distinguished name of the OU in quotation marks.  
• The default value is the default OU for machine objects in the domain.
• PassThru: this parameter, common to both sets, returns the results of the command. By default, this cmdlet does not generate any output.
• Restart: this parameter, which was added in v3 and is common to both sets, restarts the computers that were added to the domain or workgroup. A restart is often required to make the change effective.
• Server: this parameter, belonging to the first parameter set, specifies the name of a domain controller that adds the computer to the domain. 
• Enter the name in DomainNameComputerName format. 
• By default, no domain controller is specified.
• UnjoinDomainCredential: this v3 parameter, belonging to the first parameter set, specifies a user account that has permission to remove the computers from their current domains. 
• The default is the current user.
• Type a user name, such as "User01" or "Domain01User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. 
• If you type a user name, you will be prompted for a password.
• Use this parameter when you are moving computers to a different domain. 
• To specify a user account that has permission to join the new domain, use the Credential parameter. 
• To specify a user account that has permission to connect to a remote computer, use the LocalCredential parameter.
• Unsecure: this parameter, belonging to the first parameter set, performs an unsecure join to the specified domain.
• Credential: this parameter, common to both sets, specifies a user account that has permission to join the computers to a new domain. 
• The default is the current user.
• Type a user name, such as "User01" or "Domain01User01", or enter a PSCredential object, such as one generated by the Get-Credential cmdlet. 
• If you type a user name, you will be prompted for a password.
• To specify a user account that has permission to remove the computer from its current domain, use the UnjoinDomainCredential parameter. 
• To specify a user account that has permission to connect to a remote computer, use the LocalCredential parameter.
• Confirm: this parameter, common to both sets, prompts you for confirmation before running the cmdlet.
• WhatIf: this parameter, common to both sets, shows what would happen if the cmdlet runs. The cmdlet is not run.
• WorkGroupName: this parameter, belonging to the second parameter set, specifies the workgroup to which the computers are added. 
• This parameter is required when adding the computers to a workgroup.

While there are a ton of options to select from, it is not surprising since active directory, and, the workgroup concepts which preceded it, are both large topics in and of themselves. The best way to get some experience with this is definitely on a set of virtual machines designed for testing. Once you feel comfortable using these in the sandbox, give them a whirl in a model or test environment, then, in real usage. There are so many scenarios in which the options could be permutated it is impossible to cover all the examples in an exhaustive fashion. The best I can do is throw out some basic examples. Since I havent really used this myself, I would just refer you to the -Examples on Get-Help from PowerShell v3 as noted below (i.e., I didnt make these up...theyre straight copies for folks who may not have a box handy to read):

1. Simply add the local machine to a domain and restart: Add-Computer -DomainName Domain01 -Restart
2. Simply add the local machine to a workgroup: Add-Computer -WorkGroupName WORKGROUP-A
3. Add the local machine to Domain01 referencing the DC Domain01/DC01 and return the verbose output to the host: Add-Computer -DomainName Domain01 -Server Domain01DC01 -Passthru -Verbose
4. Add the computer to Domain02 in the OU "OU=testOU,DC=domain,DC=Domain,DC=com": Add-Computer -DomainName Domain02 -OUPath "OU=testOU,DC=domain,DC=Domain,DC=com"
5. Add Server01 with local credentials, Admin01, to Domain02 using Domain02Admin02 credentials forcing the addition and a reboot: Add-Computer -ComputerName Server01 -LocalCredential Server01Admin01 -DomainName Domain02 -Credential Domain02Admin02 -Restart -Force
6. Add Server01 and Server 02 as well as the localhost to Domain02 with local credentials while unjoining the admin01 account and forcing restarts: Add-Computer -ComputerName Server01, Server02, localhost -Domain Domain02 -LocalCredential Domain01User01 -UnjoinDomainCredential Domain01Admin01 -Credential Domain02Admin01 -Restart
7. Add Server01 to Domain02 with new name Server044 using credential Domain02Admin01 while forcing a restart: Add-Computer -ComputerName Server01 -Domain Domain02 -NewName Server044 -Credential Domain02Admin01 -Restart
8. Add each computer listed in by getting the content of Servers.txt to Domain02 with the Domain02Admin02 credentials using the -Win9xUpgrade option and a -Restart: Add-Computer -ComputerName (Get-Content Servers.txt) -Domain Domain02 -Credential Domain02Admin02 -Options Win9xUpgrade  -Restart

Related Post: