Customizing OS-image profiles

A base operating system is the full OS image that was imported into the OS-images repository. The imported base image contains predefined profiles that describe the installation configurations for that image. You can also create custom profiles in the base OS image that can be deployed for specific configurations. The custom profile contains the custom files and installation options.

Note

You cannot create a custom OS-image profile for a custom Microsoft Windows Server image.

Several example scenarios for customizing and deploying OS-images, including Windows and SLES, are available in English only. For more information, see End-to-end scenarios for setting up new devices.

You can add the following types of files to a custom OS image profile.

Boot files

A boot file acts as the bootstrap install environment. For Windows, this is a Windows Pre-installation (WinPE) file. A WinPE boot file is required to deploy Windows

Lenovo XClarity Administrator supports predefined and custom boot files.

Predefined boot files. Lenovo provides a WinPE_64.wim boot file that can be used to deploy predefined OS-image profiles.
Lenovo bundles the predefined WinPE_64.wim boot file along with a set of device drivers into a single package that can be downloaded from the Lenovo Windows drivers and WinPE Images Repository webpage and then imported into OS-images repository. Because the bundle file contains both device drivers and boot files, you can import the bundle file from the Device Driver or Boot Files tab.
Note
- A predefined boot file is not preloaded with XClarity Administrator. You must import a boot file into the OS-images repository before you can deploy a Windows profile.
- You cannot delete predefined boot files that were loaded when you installed XClarity Administrator; however, you can delete predefined boot files that were imported from a Lenovo bundle.
- XClarity Administrator requires that imported bundle files be signed by Lenovo. When importing a bundle file, an .asc signature file must also be imported.

Custom boot files. You can create a WinPE boot file to customize boot options for a Windows deployment. You can then add the boot file to custom Windows profiles.

XClarity Administrator provides scripts for creating boot files in the correct format. For information about creating a custom boot files, see Creating a boot (WinPE) file and Introduction to Windows PE (WinPE) website.

The following file types are supported for importing custom boot files.

Operating system	Supported Boot File Types	Supported Bundle File Types
CentOS Linux	Not supported	Not supported
Microsoft® Windows® Azure Stack HCI	Not supported	Not supported
Microsoft Windows Hyper-V Server	A .zip file that contain a WinPE file that is created using the genimage.cmd script	A .zip file containing device drivers and boot files
Microsoft Windows Server	A .zip file that contain a WinPE file that is created using the genimage.cmd script	A .zip file containing device drivers and boot files
Red Hat® Enterprise Linux (RHEL) Server	Not supported	Not supported
Rocky Linux	Not supported	Not supported
SUSE® Linux Enterprise Server (SLES)	Not supported	Not supported
Ubuntu	Not supported	Not supported
VMware vSphere® Hypervisor (ESXi) with Lenovo Customization	Not supported	Not supported

Device drivers

You must ensure that the operating-system image that you intend to deploy includes the appropriate Ethernet, Fibre Channel, and storage adapter device drivers for your hardware. If the I/O adapter device driver is not included in the operating system image or profile, the adapter is not supported for OS deployment. You can create custom OS-image profiles that include the out-of-box device drivers that you need.

Lenovo XClarity Administrator supports in-box device drivers as well as predefined and custom out-of-box device drivers.

In-box device drivers. XClarity Administrator does not manage in-box device drivers. Always install the latest operating system to ensure that you have the latest in-box device drivers that you need.
Note
You can add in-box device drivers to a customized Windows profile by creating a custom WinPE boot file and copying the device-driver files to the host system in the C:\drivers directory. When you create a custom OS-images profile that uses the custom boot-file, the device drivers that are in the C:\drivers directory are included in both WinPE and the final OS. They are treated as though they were inbox. Therefore, you do not need to import these in-box device drivers into XClarity Administrator when you specify device drivers to use in the custom OS-images profile creation.
Predefined device drivers. For ThinkSystem servers, XClarity Administrator is preloaded with a set of out-of-box device drivers for Linux to enable the installation of the operating system as well as basic network and storage configuration for the final operating system. You can add these predefined device drivers to your custom OS-image profiles, and then deploy the profiles to your managed servers
Lenovo also bundles sets of predefined device drivers into a single package that can be downloaded from the Lenovo Windows drivers and WinPE Images Repository webpage and then imported into OS-images repository. Currently, the bundle files are available only for Windows. If the bundle file contains both device drivers and boot files, you can import the bundle file from the Device Driver or Boot Image tab.
Note
- By default, the predefined OS-image profiles include the predefined device drivers.
- You cannot delete predefined device drivers that were loaded when you installed XClarity Administrator; however, you can delete predefined device drivers that were imported from a Lenovo bundle.
- XClarity Administrator requires that imported bundle files be signed by Lenovo. When importing a bundle file, an .asc signature file must also be imported.

Custom device drivers. You can import out-of-box device drivers into the OS-images repository, and then add those device drivers to a custom OS-image profile.

You can obtain device drivers from the Lenovo YUM Repository webpage, from the vendor (such as Red Hat), or through a custom device driver that you generated yourself. For some Windows device drivers, you can generate a custom device driver by extracting the device driver from the installation .exe to your local system and creating a .zip archive file.

The following file types are supported for importing custom device drivers.

Operating system	Supported Device Driver File Types
CentOS Linux	Not supported
Microsoft® Windows® Azure Stack HCI	Not supported
Microsoft Windows Hyper-V Server	A .zip file containing the raw device-driver files, which are typically grouping of .inf, .cat, and .dll files.
Microsoft Windows Server	A .zip file containing the raw device-driver files, which are typically grouping of .inf, .cat, and .dll files.
Red Hat® Enterprise Linux (RHEL) Server	Driver update disk (DUD) in either an .rpm or .iso image format Note If you apply a DUD .rpm to the custom profile, the .rpm is installed only to the final operating system. It is not installed in the install environment (initrd). To install a custom device driver to the initrd, import a DUD .iso and apply the .iso to the custom profile.
Rocky Linux	Not supported
SUSE® Linux Enterprise Server (SLES)	Driver update disk (DUD) in .rpm or .iso image format Note If you apply a DUD .rpm to the custom profile, the .rpm is installed only to the final operating system. It is not installed in the install environment (initrd). To install a custom device driver to the initrd, import a DUD .iso and apply the .iso to the custom profile.
Ubuntu	Not supported
VMware vSphere® Hypervisor (ESXi) with Lenovo Customization	Device drivers in .vib image format

Note

The OS images repository can store an unlimited number of predefined and custom files, if space is available to store the files.

Custom configuration settings
Configuration settings describe data that needs to be gathered dynamically during OS deployment. Lenovo XClarity Administrator uses a set of predefined configuration settings, including global, network, and storage location settings. You can use these predefined configuration settings and add custom configuration setting that are not available through the XClarity Administrator.
The custom configuration settings are defined in the form of a JSON schema. The schema must conform to the JSON specification.
When you import custom configuration settings to XClarity Administrator, XClarity Administrator validates the JSON schema. If the validation passes, XClarity Administrator generates custom macros for each setting.
You can use the custom macros in the unattend file and post-installation script.
In unattend files
You can associate the custom configuration file with an unattend file and include these custom macros (and predefined macros) in that unattend file.
You can add one or more custom configuration settings files in a custom profile. When you deploy the OS profile to a set of target servers, you can choose which configuration settings file to use. XClarity Administrator renders the Custom Settings tab on the Deploy OS Images dialog based on the JSON schema in the configuration settings file and allows you to specify values for each setting (JSON object) that is defined in the file.
Note
OS deployment will not proceed if input is not specified for any required custom configuration settings.
In post-installation scripts
After the data is gathered during OS deployment, XClarity Administrator creates an instance of the configuration settings file (which includes the custom settings in the selected file and a subset of predefined settings) on the host system that can be used by the post installation script.
Note
- Configuration settings file is unique to a custom OS-image profile.
- You cannot modify configuration settings for predefined OS-image profiles.
- Configuration settings are supported for only the following operating systems:
  Microsoft® Windows® Server
  Red Hat® Enterprise Linux (RHEL) Server
  Rocky Linux
  SUSE® Linux Enterprise Server (SLES)
  VMware vSphere® Hypervisor (ESXi) with Lenovo Customization 6.0u3 and later updates and 6.5 and later.
The OS images repository can store an unlimited number of predefined and custom files, if space is available to store the files.

Custom unattend files

You can customize OS image profiles to use unattend files to automate the deployment of the operating system.

The following file types are supported for custom unattend files.

Operating system	Supported File Types	More information
CentOS Linux	Not supported
Microsoft® Windows® Azure Stack HCI	Not supported
Microsoft Windows Hyper-V Server	Not supported
Microsoft Windows Server	Unattend (.xml)	For more information about unattend files, see the Unattended Windows Setup Reference webpage.
Red Hat® Enterprise Linux (RHEL) Server	Kickstart (.cfg)	For more information about unattend files, see the Red Hat: Automating the Installation with Kickstart webpage. Consider the following when adding %pre, %post, %firstboot sections in the file. You can include multiple %pre, %post, %firstboot sections to the unattend file; however, be aware of the ordering of the sections. When the recommended #predefined.unattendSettings.preinstallConfig# macro is present in the unattend file, XClarity Administrator adds a %pre section before all other %pre sections in the file. When the recommended #predefined.unattendSettings.postinstallConfig# macro is present in the unattend file, XClarity Administrator adds %post and %firstboot sections before all other %post and %firstboot sections in the file.
Rocky Linux	Kickstart (.cfg)	For more information about unattend files, see the Red Hat: Automating the Installation with Kickstart webpage. Consider the following when adding %pre, %post, %firstboot sections in the file. You can include multiple %pre, %post, %firstboot sections to the unattend file; however, be aware of the ordering of the sections. When the recommended #predefined.unattendSettings.preinstallConfig# macro is present in the unattend file, XClarity Administrator adds a %pre section before all other %pre sections in the file. When the recommended #predefined.unattendSettings.postinstallConfig# macro is present in the unattend file, XClarity Administrator adds %post and %firstboot sections before all other %post and %firstboot sections in the file.
SUSE® Linux Enterprise Server (SLES)	AutoYast (.xml)	For more information about unattend files, see the SUSE: AutoYaST webpage.
Ubuntu	Not supported
VMware vSphere® Hypervisor (ESXi) with Lenovo Customization	Kickstart (.cfg)	Supported only for ESXi 6.0u3 and later updates and 6.5 and later. For more information about unattend files, see the VMware: Installing or Upgrading Hosts by Using a Script webpage. Consider the following when adding %pre, %post, %firstboot sections in the file. You can include multiple %pre, %post, %firstboot sections to the unattend file; however, be aware of the ordering of the sections. When the recommended #predefined.unattendSettings.preinstallConfig# macro is present in the unattend file, XClarity Administrator adds a %pre section before all other %pre sections in the file. When the recommended #predefined.unattendSettings.postinstallConfig# macro is present in the unattend file, XClarity Administrator adds %post and %firstboot sections before all other %post and %firstboot sections in the file.

Attention

You can inject predefined and custom macros (configuration settings) in the unattend file using the unique name of the object. Predefined values are dynamic based on the XClarity Administrator instances. Custom macros are dynamic based on user input that is specified during OS deployment.
Note
- Surround the macro name with a hash symbol (#).
- For nested objects, separate each object name using a period (for example, #server_settings.server0.locale#).
- For custom macros, do not include the top-most object name. For predefined macros, prefix the macro name with "predefined."
- When an object is created from a template, the name is appended with a unique number, starting with 0 (for example, server0 and server1).
- You can see the name for each macro from the Deploy OS Images dialog on the Custom Settings tabs by hovering over the Help icon () next to each custom setting.
- For a list of predefined macros, see Predefined macros. For information about custom configuration settings and macros, see Custom macros.
XClarity Administrator provides the following predefined macros that are used to communicate status from the OS installer, as well as several other critical installation steps. It is strongly recommended that you include these macros in unattend file (see Injecting predefined and custom macros to an unattend file).
- #predefined.unattendSettings.preinstallConfig#
- #predefined.unattendSettings postinstallConfig#

Custom installation scripts

You can customize OS image profiles to run an installation script after the OS deployment completes.

Currently, only post-installation scripts are supported.

The following table lists the file types for installation scripts that Lenovo XClarity Administrator supports for each operating system. Note that certain operation system versions do not support all of the file types that XClarity Administrator supports (for example, some RHEL versions might not include Perl in the minimal profile and, therefore, Perl scripts will not run). Ensure that you use the correct file type for the operating system versions that you want to deploy.

Operating system	Supported File Types	More information
CentOS Linux	Not supported
Microsoft® Windows® Azure Stack HCI	Not supported
Microsoft Windows Hyper-V Server	Not supported
Microsoft® Windows® Server	Command file (.cmd), PowerShell (.ps1)	The default custom data and files path is C:\lxca. For more information about installation scripts, see the Add a custom script to Windows Setup webpage
Red Hat® Enterprise Linux (RHEL) Server	Bash (.sh), Perl (.pm or .pl), Python (.py)	The default custom data and files path is /home/lxca. For more information about installation scripts, see the RHEL: Post-installation Script webpage.
Rocky Linux	Bash (.sh), Perl (.pm or .pl), Python (.py)	The default custom data and files path is /home/lxca. For more information about installation scripts, see the RHEL: Post-installation Script webpage
SUSE® Linux Enterprise Server (SLES)	Bash (.sh), Perl (.pm or .pl), Python (.py)	The default custom data and files path is /home/lxca. For more information about installation scripts, see the SUSE: Custom user script webpage
Ubuntu	Not supported
VMware vSphere® Hypervisor (ESXi) with Lenovo Customization	Bash (.sh), Python (.py)	The default custom data and files path is /home/lxca. For more information about installation scripts, see the VMware: Installation and Upgrade Scripts webpage

Custom software

You can customize OS image profiles to install custom software payloads after the OS deployment and post-installation scripts complete.

The following file types are supported for custom software.

Operating system	Supported File Types	More information
CentOS Linux	Not supported
Microsoft® Windows® Azure Stack HCI	Not supported
Microsoft Windows Hyper-V Server	Not supported
Microsoft Windows® Server	A .zip file containing the software payload.	The default custom data and files path is C:\lxca.
Red Hat® Enterprise Linux (RHEL) Server	A .tar.gz file containing the software payload	The default custom data and files path is /home/lxca.
SUSE® Linux Enterprise Server (SLES)	A .tar.gz file containing the software payload	The default custom data and files path is /home/lxca.
Rocky Linux	A .tar.gz file containing the software payload	The default custom data and files path is /home/lxca.
Ubuntu	Not supported
VMware vSphere® Hypervisor (ESXi) with Lenovo Customization	A .tar.gz file containing the software payload	The default custom data and files path is /home/lxca.

Give documentation feedback