Microsoft Windows

You can use orcharhino to provision, configure, and manage hosts running Microsoft Windows. orcharhino supports hosts running Microsoft Windows 10, Windows 11, Windows Server 2016, Windows Server 2019, and Windows Server 2022.

Provisioning Hosts Running Microsoft Windows

You can use orcharhino to provision hosts running Microsoft Windows.

Prerequisites and Used Tools

You require the following tools and files to create an installation media for Windows:

Extracting VMware Drivers

Procedure

  1. Download the VMware tools and open the .iso file in a virtual drive.

  2. Create a directory, for example C:\Extract, where you want to extract the VMware tools into.

  3. Open a PowerShell and change into the virtual drive.

  4. Run .\setup.exe /A /P C:\Extract with the last parameter being the directory you have extracted the VMware tools into.

  5. Follow the installation through the GUI and set the installation path to the second path. You find the required drivers in C:\Extract\VMware\VMware Tools\VMware\Drivers as defined in the second step.

Creating a Windows Image

Procedure

  1. Clone the https://github.com/UXabre/WIMan.git repository to your Windows host.

  2. Navigate to the local git repository and create a folder under sources\amd64\ for each operating system. There is already a directory for Windows Server 2016.

  3. Copy the .iso file of the operating system to the corresponding folder.

  4. Create a directory called drivers under winpe and copy the VMware drivers into it.

  5. Open a PowerShell with administrator privileges and navigate to the local git repository.

  6. Create Windows image using the following command:

    .\GenerateWIM.ps1

TFTP Extension

orcharhino requires ipxe.lkrn to be present in the TFTP directory to boot hosts running Microsoft Windows.

Procedure

  1. Download this file from boot.ipxe.org/ipxe.lkrn.

  2. Copy ipxe.lkrn using scp from your local machine to root@orcharhino.example.com:/var/lib/tftpboot/.

Uploading ISO File

To create an installation media, you must first upload the .iso file to your orcharhino Server and then create an installation media entry.

Procedure

  1. Copy the directory {local git repository}\finalized\amd64\{version} to your orcharhino Server to /var/www/html/pub/installation_media/windows/{version}.

  2. Copy the directory {local git repository}\winpe\drivers to your orcharhino Server to /var/www/html/pub/installation_media/windows/{version}.

    You can freely choose the directory structure after /var/www/html/pub/.

You can now reach the files over HTTP, for example http://orcharhino.example.com/pub/installation_media/windows/2016/.

Creating an Installation Medium Entry

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Installation Media.

  2. Click Create Medium.

    Creating an installation medium

    • Enter a Name (1).

    • Enter the Path (2) to the installation media on your orcharhino Server.

      The path must start with http. Provisioning over HTTPS is not supported.

  3. Select Windows from the Operating System Family drop down menu (3).

  4. Optional: Select an organization and location context.

  5. Click Submit (4) to save your input to orcharhino.

Creating an Operating System Entry

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Operating Systems.

  2. Click Create Operating System.

    Creating an operating system

    • Enter a Name (1).

    • Enter the Major Version (2) for your Windows host. This example uses Windows Server 2016, which makes the major version 2016.

    • Leave the Minor Version field (3) empty.

    • Optional: Add a Description (4).

    • Select the Family (5) of the operating system, that is Windows.

    • Select the Root Password Hash (6), that is Base64-Windows.

    • Select the Architectures (7).

  3. Associate the partition table on the Partition Table tab:

    Creating an operating system

    • Select the Windows Default Partition Table.

      If the partition table does not appear in the list, ensure it is associated to the proper organization and location context.

  4. Add the previously created installation media entry for Windows Server 2016 local in the Installation Media tab:

    Creating an operating system

    • Select the Windows Server 2016 local installation media.

  5. Create the following parameters on the Parameters tab:

    Creating an operating system

    • Add the wimImageName parameter of type string and value Windows Server 2016 SERVERSTANDARD.

      You can find the proper ImageName for each operating system in the images.ini file. The file is located at {local git repository}\finalized\amd64\2016\sources\.

  6. Click Submit to save the operating system entry to orcharhino.

Creating an Architecture Entry

Create an architecture with the name x86_64 if it is not already present.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Architectures.

  2. Click Create Architecture.

  3. Enter the name x86_64.

  4. Associate it to the previously created operating system entry.

Associating Provisioning Templates

Associate the provisioning templates to the newly created operating system entry for Windows.

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Provisioning Templates.

  2. Repeat the following procedure for each template:

    1. Select the Windows default finish template and navigate to the Association tab.

    2. Select the newly created operating system entry for Windows and associate it with the provisioning template.

      If a template does not appear in the list of provisioning template, ensure it is associated to the proper organization and location context.

Creating a Host Group

Procedure

  1. In the orcharhino management UI, navigate to Configure > Host Groups.

  2. Click Create Host Group.

  3. Enter a name and set the deploy on and compute profile options.

    Creating a host group

    • Select the Architecture (1).

    • Select the previously created Operating System (2).

    • Choose All Media from the Media Selection menu (3).

    • Select the previously created Media (4).

    • Select the Windows Default Partition Table Partition Table (5).

    • In the PXE loader (6) drop down menu, select the PXELinux BIOS item.

    • Optional: Set a Root Password (7). If empty, each host must receive a root password ahead of provisioning.

    • Click Submit (8) to create a host group. Settings on other tabs are optional.

Provisioning Windows Hosts

Procedure

  1. In the orcharhino management UI, navigate to Hosts > Create Hosts.

  2. Click Create Host.

  3. Select the previously created host group for Windows

  4. Adjust other settings as necessary.

  5. Click Submit.

You can now provision virtual machines running Microsoft Windows both boot disk based as well as network based. You can use static IP addresses when provisioning hosts using boot disk.

Additionally, you can provision image based hosts on VMware for which you need to create an image using the VMware tools and the Windows user data template.

Provisioning Windows Hosts network-based with UEFI

You can use orcharhino to provision Windows hosts with UEFI.

Limitations

  • Provisioning Windows hosts with UEFI is limited to network-based provisioning. You cannot use bootdisk-based provisioning workflows.

  • The provisioning process requires orcharhino Proxy to act as DHCP server.

  • You cannot provision Windows hosts with Secure Boot.

  • You cannot use an HTTP proxy on your orcharhino Server.

Create the iPXE boot file for each orcharhino Proxy that you use to provision Windows hosts with UEFI.

Procedure

  1. Create a custom ipxe.efi file on your orcharhino Server:

    $ /opt/orcharhino/automation/play_setup_win_efi_deployment.sh

    For orcharhino Proxy Servers only: Set SKIP_MOVING_IPXE_TO_TFTP to true to place the built ipxe.efi file to /tmp/ to copy it to your orcharhino Proxy Server.

  2. For orcharhino Proxy Servers only:

    1. Copy your custom ipxe.efi file from your orcharhino Server to your orcharhino Proxy Server:

      $ scp root@orcharhino.example.com:/tmp/ipxe.efi root@orcharhino-proxy.network2.example.com:/var/lib/tftpboot/

    2. Restore the SELinux context of your custom ipxe.efi file on your orcharhino Proxy Server:

      $ restorecon -RvF /var/lib/tftpboot

  3. In the orcharhino management UI, navigate to Hosts > Create Hosts.

  4. Click Create Host.

  5. Select the previously created host group for Windows

  6. On the Operating System tab, select iPXE Chain UEFI as PXE loader.

  7. Adjust other settings as necessary.

  8. Click Submit to provision your host.

Additional resources

Optional Host Parameters

You can optionally set the following parameters when provisioning hosts:

Variable Default Value Note

ansible_become

boolean set to false

ansible_become_method

string set to enable

ansible_connection

string set to winrm

ansible_port

Ports to access hosts through Ansible (5985 and 5986)

ansible_ssh_pass

Password to access hosts through Ansible

ansible_user

User account to access hosts through Ansible; defaults to administrator if no user is selected

ansible_winrm_enable_http

If you use ansible_port 5986, the Ansible HTTP port 5985 will be closed for security. If you want to keep this port open, set this parameter to true.

ansible_winrm_enable_unencrypted

If you use ansible_port 5986, unencrypted authentication will be disabled. If you want to enable it, set this parameter to true.

ansible_winrm_server_cert_validation

Set this to ignore if you use Ansible with self-signed certificates.

ansible_winrm_transport

You can use the following auth_methods to connect to the host using Ansible: basic, ntlm, kerberos, and credssp.

computerDomain

Domain if domain join is required

computerOU

Organization Unit if domain join is executed; defaults to the default OU of the connected AD if empty; must use distinguishedName

create_ansible_user

Create the ansible_user as a local admin or AD account as part of the local admin group?

domainAdminAccount

Administrator user account for joining a domain; must use pre-Windows 2000 login (Domain\User)

domainAdminAccountPasswd

Administrator account password for joining a domain; non alphanumeric characters are known to cause issues

EnableFirewall

Enable the firewall?

foremanDebug

false

Save log files on the host after provisioning

hide_server_manager

Show server manager when logging in to Windows Server?

http-proxy

Global HTTP proxy if required

http-proxy-port

global HTTP proxy port; is required if HTTP proxy is set

inputLocale

de-DE

Keyboard layout after booting the host; popular alternatives are en-GB and en-US

localAdminAccountDisabled

false

Disabling the default local administrator account?

machinePassword

Password for unsafe domain join

network_location

private

Network profile association; required if there is no domain join, else there are issues with winrm

noupdates

New hosts will try to patch during the installation. If you do not want to patch hosts, set this parameter to false.

ntpServer

NTP server; required if the host cannot access the internet or the DNS or DHCP server does not provide NTP

ping

Create a firewall rule to allow ICMP?

remote_desktop

Create a firewall rule to allow remote_desktop?

systemLocale

en-US

Language of the host

systemTimeZone

GMT Standard Time

Time zone of the host

systemUILanguage

en-US

System UI language

win_puppet_source

Path to the Puppet .msi file if Puppet is enabled

windowsLicenseKey

Windows license key

windowsLicenseOwner

Windows license key owner

Configuring Hosts Running Microsoft Windows

You can use orcharhino to configure hosts running Microsoft Windows using Ansible, Puppet, or Salt.

Configuring Windows Hosts Using Ansible

You can use Ansible to configure managed hosts running Microsoft Windows.

Procedure

  1. Ensure that the Ansible plug-in in installed on your orcharhino Server. For more information, see Enabling Ansible Integration with orcharhino in Ansible.

  2. Enable the Windows Remote Management (WinRM) service on your Windows host. In PowerShell, run the following command:

    Enable-PSRemoting -Force

  3. Configure the Windows Firewall to allow WinRM access. In PowerShell, run the following command:

    netsh advfirewall firewall set rule name="Windows Remote Management (HTTP-In)" new enable=yes

  4. Set the following security settings for WinRM on your Windows host. In PowerShell, run the following command:

    winrm set winrm/config/service '@{AllowUnencrypted="true"}'
winrm set winrm/config/client/auth '@{Basic="true"}'
winrm set winrm/config/service/auth '@{Basic="true"}'

  5. Create an Ansible user to connect to your Windows host. In PowerShell, run the following command:

    New-LocalUser -Name "ansibleuser" -PasswordNeverExpires 1

  6. In the orcharhino management UI, navigate to Hosts > All Hosts.

  7. Select your Windows host and click Edit.

  8. On the Parameters tab, add the following parameters:

    • ansible_connection – winrm

    • ansible_port – 5985 or 5986

    • ansible_ssh_pass – the password of the Ansible user

    • ansible_user – the username of the Ansible user

    • ansible_winrm_transport – ntlm

Configuring Windows Hosts Using Puppet

You can use Puppet to configure managed hosts running Microsoft Windows.

Procedure

  1. Download the latest Puppet Agent from downloads.puppetlabs.com

  2. Follow the installer instructions to install the Puppet Agent on your Windows host.

Configuring Windows Hosts Using Salt

You can use Salt to configure managed hosts running Microsoft Windows.

Procedure

  1. Download the Salt Minion. For more information, see docs.saltproject.io.

  2. Follow the installer instructions to install the Salt Minion on your Windows host. Provide the following information during the installation process:

    • Master IP or Hostname: orcharhino.example.com

    • Minion Name: The FQDN of your Windows host

  3. Configure the Salt Minion in C:\ProgramData\Salt Project\Salt\conf\minion.d\schedule.conf:

    schedule:
  highstate:
    function: state.highstate
    minutes: 60

    This configures the Salt minion to run a highstate every 60 minutes.

Managing Hosts Running Microsoft Windows

Registering Windows Hosts

Use this procedure to register hosts running Microsoft Windows to orcharhino.

Procedure

  1. In the orcharhino management UI, navigate to Infrastructure > Compute Resources.

  2. Select the compute resource that your Windows host runs on.

  3. On the Virtual Machines tab, locate your VM.

  4. In the Actions menu, click Import as Managed Host.

    • Select your organization context, location context, and host group.

    • Ensure that the network interface to which the virtual machine is connected is configured in orcharhino. If not, select a network interface that differs from the one already configured in the virtual machine’s operating system. Note that this may result in a change of IP address and other network settings.

  5. Click Submit to register your Windows host.

Updating Windows Hosts

Use this procedure to update managed hosts running Microsoft Windows.

orcharhino contains a job template Manage Windows Updates – Ansible Default to update Windows hosts using Ansible. You can configure it using various parameters to control the update process.

Input Parameters

  • blacklist: Exclude a list of update titles or KB numbers from installation.

  • category_names: Categories of updates to be installed (defaults include Critical Updates, Security Updates, and Update Rollups).

  • log_path: Path to a file for logging the update process.

  • reboot_timeout: The time to wait for the host to recover after a reboot.

  • reboot: Indicates whether to reboot the remote host if necessary.

  • server_selection: Selection of the Windows Update source catalog.

  • state: Controls the update process (download, install, list of updates).

  • use_scheduled_task: Use scheduled tasks for privilege elevation.

  • whitelist: Include a list of update titles or KB numbers for installation.

Procedure

  1. In the orcharhino management UI, navigate to Monitor > Jobs.

  2. Click Run Job.

  3. Select Ansible Playbook as Job category and Manage Windows Updates – Ansible Default as Job template. For more information, see the list of input parameters above and Executing a Remote Job in Ansible.