Joining an ESXi host into Active Directory

As mentioned in the connecting section, joining an ESXi host to Active Directory offers the ability to connect to the host without entering the credentials for administrators. Active Directory is a Windows implementation of Lightweight Directory Access Protocol (LDAP). It contains accounts for users, computers, and groups. It runs on a Windows Server that has the Active Directory role installed and that has been "promoted" to become a domain controller. To perform this recipe, you will need at least one Active Directory server available on the network with the ESXi host.

Seamless authentication is one of the biggest reasons to join a host to Active Directory. However, beyond single sign-on, once the ESXi host is connected to Active Directory, groups in the directory can be leveraged to grant permissions to the ESXi host. If you do not have Active Directory installed and do not wish to, you can skip this recipe and move on to other topics of host configuration without any impact to future recipes.

Getting ready

PowerCLI has Get-VMHostAuthentication and Set-VMHostAuthentication, two cmdlets to deal with host authentication. To get ready to set up authentication, open a PowerCLI window and connect to a single ESXi host.

How to do it...

1. Because the cmdlets require a VMHost object, you'll again be using Get-VMHost to either populate a variable or to pipe an object to the next object. The first step is to obtain a VMHost object for our target ESXi host. This can be done using the following command line:

   $esxihost = Get-VMHost 192.168.0.241
   

2. Once you have your VMHost object, you can look at setting up the authentication. The Set-VMHostAuthentication cmdlet needs to be executed. The cmdlet requires several parameters to join an ESXi host to the domain. The syntax needed is displayed as follows:

   $esxihost | Get-VMHostAuthentication | Set-VMHostAuthentication -JoinDomain -Domain domain.local -user username -password *****
   

3. Executing the cmdlet will prompt you to confirm that you want to join this host to the domain specified. If your answer is Y, the cmdlet will continue and execute the operation as follows:

   Perform operation?
   Joining VMHost '192.168.0.241' to Windows Domain 'domain.local'.
   [Y] Yes  [A] Yes to All  [N] No  [L] No to All  [S] Suspend  [?] Help
   (default is "Y"):Y
   
   Domain          DomainMembershipStatus    TrustedDomains
   ------          ----------------------    --------------
   DOMAIN.LOCAL    Ok
   

How it works…

One of the first things you will notice about this recipe is that there is an extra Get-VMHostAuthentication cmdlet in the middle of the command line. Why does it need to perform Get before performing Set? It would seem that you can simply pipe the VMHost object into cmdlet to specify your target host and the cmdlet will execute the function. But as you try that, using the following command line, PowerCLI displays an error, as shown in the following screenshot:

$esxihost | Set-VMHostAuthentication -JoinDomain -Domain domain.local -user username -password *****

In this case, the cmdlet looks for a VMHostAuthentication object and not a VMHost object, so an error is displayed. If you go back and simply execute the Set-VMHostAuthentication cmdlet as follows, it will prompt you for a VMHostAuthentication object and wait for an input:

Set-VMHostAuthentication -JoinDomain -Domain domain.local -user username -password *****

This is where the Get-VMHostAuthentication cmdlet gets added. It retrieves the VMHostAuthentication object from the host you targeted since this cmdlet accepts the VMHost object as a piped input.

The Get-Help cmdlet for Set-VMHostAuthentication also shows that the cmdlet expects a VMHostAuthentication object to be passed as a parameter for the cmdlet. By executing the cmdlet with all of its parameters and no piped input, you also learned that you can debug and learn what input the cmdlet is expecting and missing.

There's more…

The same cmdlets can also be used to remove a host from a domain, if needed. The -LeaveDomain parameter is a part of the Set-VMHostAuthentication cmdlet and allows this need.

In addition to setting up an ESXi host to accept Active Directory authentication, PowerCLI also provides a number of cmdlets to add local users, groups, and permissions inside a single ESXi host. The New-VMHostAccount cmdlet is used to create new users on an ESXi system. The same cmdlet previously allowed the creation of groups, but this functionality was removed with ESXi 5.1. There is a Set-VMHostAccount cmdlet to change accounts and group memberships, and a Remove-VMHostAccount cmdlet to remove a user or a group.

See also

• The Setting permissions on vCenter objects recipe in Chapter 2, Configuring vCenter and Computing Clusters