# PowerShell Lab Detailed Setup Instructions For my Pluralsight PowerShell courses, you are welcome to use any lab environment you wish. It should include an Active Directory domain with at least a domain controller, a Windows 10 client, and a Windows Server 2016 or 2019 member server. You will need to modify the course files to fit your environment. At this point in time, Windows Server 2022 remains untested for my labs. However, I am going to recommend that you use a free PowerShell module called **PSAutoLab**. I encourag you to look at the [README document](https://github.com/pluralsight/PS-AutoLab-Env/blob/master/README.md) on the project's Github repository before proceeding. If you need help with the module or its commands, you will use the repository's [Issue](https://github.com/pluralsight/PS-AutoLab-Env/issues) section. ## PSAutolab Please refer to this document to assist in installing and setting up the `PSAutolab` module on your computer. Run all commands from an **elevated** Windows PowerShell session. In other words, *run Windows PowerShell as administrator*. You will know you are elevated if you see the word `Administrator` in the title bar of the PowerShell window. >__Do NOT run this module in PowerShell 7__. It is assumed you are running this on Windows 10 Professional or Enterprise editions. It is also assumed that you have administrator rights to your computer and can make changes. If your computer is controlled by Group Policy, you may encounter problems. You should also be logged in with a __local__ or __domain user__ account. The setup process may *_not_* work properly if using an O365 or Microsoft account to logon to Windows. It is *possible* to run this module with nested virtualization inside a Windows 10 Hyper-V virtual machine but it is **not** recommended. Some networking features may not work properly and overall performance will likely be reduced. ## Pre-Check You can run these Windows PowerShell commands to verify your computer meets the minimum requirements. Run all PowerShell commands in an elevated session. ### Operating System and Memory ```text PS C:\> Get-CimInstance -ClassName Win32_OperatingSystem | Select-Object Caption,@{Name="MemoryGB";Expression={$_.TotalVisibleMemorySize/1mb -as [int]}} Caption MemoryGB ------- ----- Microsoft Windows 10 Pro 32 ``` If the `Caption` shows anything other than Pro or Enterprise this module may not work. Although it appears that Windows 10 Education might be supported. If you can't even open a PowerShell prompt, this module won't work on your computer. The memory size should be at least 12GB. 16GB or greater is recommended. If the number is less than 12, **STOP**. It is unlikely you have enough installed memory and this lab will not run properly for you. ### PowerShell Remoting The module relies on Windows PowerShell remoting which should be enabled **before** installing and using the PSAutolab module. ```text PS C:\> test-wsman wsmid : http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd ProtocolVersion : http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd ProductVendor : Microsoft Corporation ProductVersion : OS: 0.0.0 SP: 0.0 Stack: 3.0 ``` This is what you should see as a result. Any errors mean that PowerShell remoting is disabled. Enable it from your **elevated** PowerShell session. This will fail if your only network connection is over a public network. ```powershell Enable-PSRemoting -force ``` If this fails, **STOP**. Do not proceed with this module until this is working and `Test-WSMan` gives you a result. If you are running as Administrator and this command fails it is most likely because the related settings are controlled by Group Policy or your network is public. Run `Get-NetConnectionProfile` and look at the NetworkCategory. If must be `Private` or `DomainAuthenticated`. ### Disk Space The module requires a lot of disk space for the virtual machines, snapshots, and ISO files. Run this command to see how much free space you have. ```text PS C:\> Get-Volume Drive SizeGB FreeGB PercentFree HealthStatus ----- ------ ------ ----------- ------------ C 237 87 36.71 Healthy ``` You should have close to 100GB of free space on a fixed hard drive such as C or D. The module will setup an Autolab folder on drive C: by default, although you can specify an alternate drive. It is *strongly* recommended that you have fast SSD drives. The PSAutolab module __has not__ been tested running from an externally connected drive but you are welcome to try if that is your only option. ### Virtualization The PSAutoLab module requires the Hyper-V feature on Windows 10. Please refer to the documentation for your computer hardware to determine if it supports virtualization. You may need to configure settings in your BIOS. You don't need to manually enable the Hyper-V feature now, although you are welcome to if you want to verify it is available. ### Pester The PSAutoLab module uses a standard PowerShell tool called Pester to validate lab configurations. Without getting into technical details, if you are running the out-of-the-box version of Pester on Windows 10, **you need to manually update Pester** before attempting to install this module. In an elevated Windows PowerShell session run this command: ```powershell Get-Module Pester -ListAvailable ``` If the _only_ result you get is for version `3.4.0`, then you must run: ```powershell Install-Module pester -RequiredVersion 4.10.1 -Force -SkipPublisherCheck ``` Re-run the `Get-Module Pester -ListAvailable` command to verify version `4.10.1` is installed. If you have newer versions installed, that will have no effect on this module. Once you have verified Pester version 4.10.1 you can install the PSAutolab module. ## Installation and Configuration ### Install the Module If you meet all of the above requirements, you are ready to download and install this module. > **Do not download or install the module from the GitHub repository.** In your elevated PowerShell session run this command: ```powershell Install-Module PSAutolab -force -SkipPublisherCheck ``` You may be prompted to update to a newer version of `nuget`. Answer "yes". You might also be prompted about installing from an untrusted source. Again, you will need to say "yes". After installation you can verify using `Get-Module`. ```text PS C:\> Get-Module PSAutoLab -list Directory: C:\Program Files\WindowsPowerShell\Modules ModuleType Version Name ExportedCommands ---------- ------- ---- ---------------- Script 4.20.0 PSAutoLab {Enable-Internet, Invoke-RefreshLab, Invoke-Run... ``` You may see a higher version number than what is indicated here. You do not need to import the module before you can use it. You can simply run a module command. ### Setup the Host You will need to initialize your lab environment. There is a one-time step to setup your computer for the AutoLab environment. In your elevated PowerShell session run this command: ```powershell Setup-Host ``` This command will create a directory structure for the module and all of its files. The default is `C:\Autolab` which you should be able to accept. If you are low on space on drive C: or want to use an alternate drive, then you can specify an alternative top-level path. ```powershell Setup-Host -DestinationPath D:\Autolab ``` If you select a drive other than C:\ it is recommended you still use the `Autolab` folder name. The setup process will install additional modules and files. If necessary, it will enable the Hyper-V feature. If Hyper-V is enabled during the setup, please reboot your computer before proceeding. To verify your configuration, run `Get-PSAutolabSetting`. ```text PS C:\> Get-PSAutoLabSetting AutoLab : C:\Autolab PSVersion : 5.1.18362.752 PSEdition : Desktop OS : Microsoft Windows 10 Pro FreeSpaceGB : 365.45 MemoryGB : 32 PctFreeMemory : 59.71 Processor : Intel(R) Core(TM) i7-8750H CPU @ 2.20GHz IsElevated : True RemotingEnabled : True NetConnectionProfile : Private HyperV : 10.0.18362.1 PSAutolab : 4.20.0 Lability : {0.19.1, 0.19.0, 0.18.0} Pester : {5.0.2, 4.10.1, 4.9.0, 4.8.1...} PowerShellGet : 2.2.4.1 PSDesiredStateConfiguration : 1.1 ``` If Hyper-V is not installed you will see errors. Any errors indicate a problem with your setup. Please post the information from this command when reporting an issue. ### Setup the PowerShell Lab Configuration In an elevated PowerShell session, **change directory** to the `PowerShellLab` configuration folder ```text PS C:\> cd C:\Autolab\Configurations\PowerShellLab PS C:\Autolab\Configurations\PowerShellLab\> ``` You can run `Unattend-Lab` for a completely hands-free experience. ```text PS C:\Autolab\Configurations\PowerShellLab\> unattend-lab ``` The very first time you setup a lab, the command will download ISO images of evaluation software from Microsoft. These files will total over 20GB in size. *This download only happens once*. > The evaluation versions of Windows Server and Windows 10 generally are good for 90 days. This means that once setup you have 90 days to use the lab environment before you need to wipe the lab and rebuild it for another 90 days. During the installation, additional packages might be downloaded, if prompted, answer yes or OK. Note that during the validation phase you may see errors. This is to be expected until all of the configurations merge. You can press `Ctrl+C` to break out of the testing phase at any time. The virtual machines will continue to prepare themselves. Later, you can manually validate the lab: ```text PS C:\Autolab\Configurations\PowerShellLab\> Invoke-Pester .\vmvalidate.test.ps1 ``` Sometimes, the Win10 virtual machine shuts down and doesn't reboot which will cause validation to fail. While validation is running, open another PowerShell window and run `Get-VM`. If a VM like Win10 is not running, start it: `Start-VM Win10`. Ideally, an unattended installation should complete in 20 minutes or less. > Beginning with v4.21.0 of the PSAutoLab module, the validation command should automatically start virtual machines that have stopped or restart virtual machines that appear to be not responding. You will see these actions as warnings. This is normal. In the rare event that the validation takes longer than 60 minutes, the process will automatically stop and display instructions. ### Manual Configuration Setup If you encounter errors running an unattended setup, you should step through the process manually to identify where exactly an error is occurring. Make sure you are in an elevated PowerShell session and you have *changed location to the configuration folder*. If you have tried to setup the lab before, run `Wipe-Lab` to remove previous set-up files. ```text PS C:\Autolab\Configurations\PowerShellLab\> wipe-lab -force ``` Then run each of these commands individually: * `Setup-Lab` * `Enable-Internet` * `Run-Lab` Errors that affect setup should happen in one of these steps. If so, open an issue in the Github repository for PSAutolab with the configuration name, the command you were working on and the error message. Also include the output from the `Get-PSAutolabSetting` command. After about 20 minutes, you can manually test to see if the configuration has converged. ```powershell Invoke-Pester .\vmvalidate.test.ps1 ``` You might still see errors or failures, in which case try again in 10-minute intervals until the test completely passes. You might also need to verify that the virtual machine is running using the Hyper-V manager and starting it if it has shutdown. ### Help All of the commands in this module have help and examples. You are also encouraged to read the about help topic. ```powershell help about_PSAutoLab ``` All of the module's documentation is also available in a PDF. Run `Open-PSAutoLabHelp`. ## Post Setup You are encouraged to run Windows update on the virtual machines. Change to the PowerShellLab folder and run `Update-Lab`. ```text PS C:\Autolab\Configurations\PowerShellLab> update-lab -AsJob Id Name PSJobTypeName State HasMoreData Location Command -- ---- ------------- ----- ----------- -------- ------- 18 WUUpdate RemoteJob Running True DOM1 WUUpdate 21 WUUpdate RemoteJob Running True SRV1 WUUpdate 24 WUUpdate RemoteJob Running True SRV2 WUUpdate 27 WUUpdate RemoteJob Running True SRV3 WUUpdate 30 WUUpdate RemoteJob Running True WIN10 WUUpdate ``` These jobs might take some time to run. Run `Get-Job` to check the status. This process might take as long as 45 minutes. This will be a resource-intensive task. Once all background jobs have completed, shutdown and restart the lab. ```text PS C:\Autolab\Configurations\PowerShellLab> Shutdown-Lab PS C:\Autolab\Configurations\PowerShellLab> Run-Lab ``` These commands may take several minutes to complete. You can also manually control the virtual machines using the Hyper-V commands. ```powershell Stop-VM Win10,Srv2,Srv1,Srv3 -force Stop-VM Dom1 -force Start-VM Dom1 -force Get-VM Start-VM Dom1,Srv3 Start-VM Win10,Srv2,Srv1 ``` ## Snapshots Because you will be modifying virtual machines, you should take advantage of the snapshot feature so that you can roll the lab back. You can have as many snapshots as you want. ```text PS C:\Autolab\Configurations\PowerShellLab\> Snapshot-Lab -snapshotname "Pre-DSCconfig" ``` The lab machines will be shutdown for the snapshot. You will need to use `Run-Lab` to restart. The `Get-LabSnapshot` command will list your snapshots. Use `Refresh-Lab` to roll back to a given snapshot. ```text PS C:\Autolab\Configurations\PowerShellLab\> Refresh-Lab -snapshotname "Pre-DSCconfig" ``` ## Troubleshooting Tips Occasionally, things can go wrong for no apparent reason. If you ran through the manual steps to setup a lab but the validation tests are still failing after running for 20 minutes, you may need to stop and restart the virtual machine that is causing problems. For example, *sometimes* the SRV2 member in the `PowerShellLab` configuration simply won't pass validation, often because it can't be connected to. If you manually run the validation test ```text PS C:\Autolab\Configurations\PowerShellLab> Invoke-Pester .\VMValidate.test.ps1 Pester v4.10.1 Executing all tests in '.\VMValidate.test.ps1' Executing script .\VMValidate.test.ps1 Describing DOM1 [+] [DOM1] Should belong to the Company.Pri domain 115ms [+] [DOM1] Should have feature AD-Domain-Services installed 1ms [+] [DOM1] Should have feature DNS installed 1ms ... Describing SRV2 [-] [SRV2] Should allow a PSSession but got error: The credential is invalid. 3ms Expected $true, but got $false. 256: $false | Should Be $True at , D:\autolab\Configurations\PowerShellLab\VMValidate.test.ps1: line 256 Describing SRV3 [+] [SRV3] Should respond to WSMan requests 5ms ... ``` The best solution is to shut down the virtual machine in either the Hyper-V Manager or from PowerShell. ```powershell Stop-VM srv2 -force ``` Then start it back up. ```powershell Start-VM srv2 ``` Wait about 5 minutes and then test again. ## Getting Help If encounter problems getting any of this to work, you are welcome to post an Issue. If you get the module installed, please include the results of `Get-PSAutolabSetting`. If your problem is meeting one of the requirements, we will do our best to help. Although if your computer is locked down or otherwise controlled by corporate policies there may not be much that we can do.