Eikon Image Deploy¶

The Eikon plugin deploys images to systems. These images can be tarballs that get untarred onto defined partition-based filesystems or raw storage images that get copied onto defined storage devices. In either case, additional files can be injected into the images for post-install operations.

The eikon-image-deploy pipeline injects and attempts to start the drpcli agent during deployment. This allows introspection during deployment under most circumstances. When not possible, the pipeline injects scripts to allow cloud-init or another process to run on first boot. For Windows, the script will be C:\eikon-win-agent.ps1. This has all the necessary information to configure and start the agent once run.

The eikon system is purpose built to deploy images and continue to run further pipelines. Like image-deploy, Eikon can interpret curtin configurations. Curtin is driven by a configuration YAML file that is built dynamically based upon the value of parameters. These parameters drive the actual imaging process. Eikon also provides a similar configuration schema using parameters that can derive from existing image-deploy parameter values.

Getting Started¶

Eikon Image Construction¶

Eikon requires an image. This image can be in many different formats. The format type defines what additional operational parameters that need to be set. These images can be built using RackN's image-builder content pack, using Hashicorp's Packer tool, or other tools that generate images.

All drivers should be added to the system in the base image or additional tarball packages. It is possible to add drivers and other packages during deployment, but is left to the customer to manage.
It is recommended that the image should be built for the the boot-style of the target hardware. If the system is going to boot in UEFI mode, then the disk image should be formatted with EFI partitions that hold EFI bootloaders. The same applies for legacy systems. There are disk layouts that can work for both.
The version of sledgehammer or ubuntuhammer used for deployment should be compatible with the target OS. Newer OS versions may require newer kernel versions and tools to properly deploy. Eikon supports both sledgehammer and ubuntuhammer as deployment OSes.

Another consideration during image construction is how the next phase of operation starts. For Windows, Eikon writes an unattend.xml answer file to C:\Windows\Panther\ and a SetupComplete.cmd to C:\Windows\Setup\Scripts\ that calls C:\eikon-win-agent.bat to start the DRP agent after setup completes. This Windows flow is version-agnostic - the same path deploys Windows Server 2019, 2022, and 2025 (and Windows 10/11); there is no per-version handling. The answer file can be customized using the eikon/win-unattend-username, eikon/win-unattend-password, eikon/win-unattend-locale, and eikon/win-unattend-xml parameters. When providing a fully custom unattend.xml via eikon/win-unattend-xml, ensure your answer file does not bypass SetupComplete.cmd, or add an explicit call to C:\eikon-win-agent.bat in your answer file to ensure the agent starts. It could also mean that cloud-init or cloudbase-init is installed and set to automatically start. Depending upon the choice of startup method, different packages and configurations may need to be added to the image.

Eikon Operations¶

Once an image is built, the system needs to know where it is, what type of image it is, where the image is to be deployed, and optionally what startup process to use. These are all defined as parameters that can be added to a machine. Because all of this information is consistent across all machines using this image, it is best practice to create a profile that contains all these parameters.

To define the location of the image file:

eikon/image-url - This is a URL that references the image. You can use template functions such as {{ .ProvisionerURL }}/path/to/file.tar.zst

To define the type and content of the image:

eikon/image-type - This is the curtin image type value. These types are define in the parameter and validated by the systems. Available values include dd-raw, dd-gz, dd-bz2, dd-xz, dd-zst, dd-tar, dd-tgz, dd-txz, dd-tbz, qcow, tar, tgz, txz, tbz, and tar-zst. Use qcow to deploy QCOW2 images directly.

Additional parameters can be used to override and expand the deployement scenario.

You can build more complex storage configurations and deploy layers of images using the eikon/plan parameter.

Eikon Customizations¶

With the basic parameters set in a profile, additional parameters can be added to drive further customization and enhancements.

Partitioning¶

When using a raw disk image, the target hard disk can be selected using the image-deploy/install-disk parameter. If this parameter is not specified, /dev/sda is used by default. Custom partitioning when defined this way.

When using a rootfs image, the target hard disk can be selected using the image-deploy/install-disk parameter. If not specified, the system defaults to /dev/sda. A simple GPT-based filesystem layout is then applied, as chosen by Curtin.

A more complex storage and image deployment can be provided for rootfs images by providing an eikon/plan parameter.

When using cloud-init or a curtin-config, network configuration can be provided by setting the curtin/network/template parameter to the name of a DRP template that renders a curtin network stanza.

Additional Content¶

The agent binary will be installed as part of the image deployment. For linux, the binary is installed to /usr/local/bin. If selinux is available, a relabel on the file is done to make sure the binary is correctly labeled.

For Windows, the binary is installed to C:\Windows.

The curtin Directory on Windows¶

When image-deploy/use-cloud-init is true (the default) and image-deploy/cloud-init-base-url is left at its file:///curtin/ default, eikon writes the cloud-init seed that the Cloudbase FileService plugin reads on first boot into C:\curtin: meta-data and user-data. meta-data carries image-deploy/admin-username, image-deploy/admin-password, cloud-init/x509-certs and access-keys, so the directory is part of the image's security posture.

eikon applies chmod 700 to it, but that is defence in depth only. C:\curtin is written to NTFS from the Linux deployment OS, where POSIX mode bits are not ACLs, so the mode is discarded and a directory the image did not create inherits the volume root's ACL, which by default is readable by all local users. No chmod from the deployment OS can change that.

The control that closes the exposure is that the directory does not survive: once the agent has joined, the image-deploy-cleanup task removes C:\curtin. eikon reaches that task through the image-deploy-cloud-init stage of the shared universal-image-deploy workflow.

If you set image-deploy/cleanup-curtin to false, or point custom cloud-init/user-data or unattend content at /curtin for later boots, hardening the directory becomes yours: create it in the image and apply the ACL from inside Windows, where it takes effect. The icacls recipe is in the image build documentation.

On Linux there is no /curtin. The NoCloud seed goes to /var/lib/cloud/seed/nocloud, created 0700 with 0600 files, and needs no hardening.

On Windows the same task also writes C:\var\lib\cloud\seed\nocloud - the modes are discarded there for the same NTFS reason as C:\curtin, and unlike C:\curtin, nothing removes it: image-deploy-cleanup deletes C:\curtin, C:\root and C:\usr, but not C:\var or C:\etc. Until that gap closes (rackn/product-backlog#1581), do not put secrets in cloud-init/user-data on the Windows eikon path.

Debug and Troubleshooting¶

To debug issues, use the standard debug parameter rs-debug-enable by setting it to true. There are also two tasks that pause the deployment as an opportunity to login and troubleshoot using ssh or console login.

Sledgehammer Override¶

Overriding the default sledgehammer may be necessary depending on the target OS. You can use bootenv override profiles such as the sledgehammer-alma9-v4.12.0 profile by adding the profile to the machine, the global profile, or another profile assigned to the machine.

Using Ubuntuhammer¶

To use Ubuntuhammer as the Eikon deployment OS, first upload the ubuntuhammer iso to the endpoint.

shell drpcli bootenvs uploadiso ubuntuhammer

Next add the param eikon/image-deploy-bootenv to a profile or machine and set its value to "ubuntuhammer". Then attach that profile to the machine. When you run Eikon it should use ubuntuhammer instead of sledgehammer to deploy the image. The param accepts only sledgehammer or ubuntuhammer; the specific version of either is chosen by the bootenv override profile described above. This works like other params and can be in a profile directly attached to a machine, or at a global level by placing the param in the global profile.

If you leave eikon/image-deploy-bootenv unset, it inherits from image-deploy/deployment-os, which defaults to sledgehammer. Setting image-deploy/deployment-os therefore switches both Eikon and image-deploy at once, while eikon/image-deploy-bootenv switches only Eikon.

Another helpful global param is the kexec-ok param. Adding it to your global profile and setting the value to true will speed up the process by reducing unnecessary reboots.

Using kexec¶

Since deployment is almost always contained within linux, it may be possible to use kexec to save a system reset. Set the kexec-ok param to true on the machine. If secure boot is enabled, there is a possibility that kexec will not work on non-rhelish images. If this is the case, the machine will reboot as a fallback.