Comprehensive Guide to Installing and Migrating to Chef Infra Client 19.x (Online and Air-Gapped)

This article provides consolidated instructions for installing or upgrading to Chef Infra Client 19.x in both online and air-gapped environments. Starting with version 19, Chef Infra Client transitioned from Omnibus to Habitat packaging. This architectural shift has resulted in new installation paths, a new project name, and new system requirements that must be met to ensure a successful deployment.

Apr 30, 2026
Knowledge

Title

URL Name

Comprehensive-Guide-to-Installing-and-Migrating-to-Chef-Infra-Client-19-x-Online-and-Air-Gapped

Article Number

000300624

Environment

Chef Infra Client 19.x Windows (Windows 10 or later) Linux (Kernel 2.6.32 or later) Online and Air-Gapped networks install.sh, install.ps1, and Commercial download API

Question/Problem Description

Customers experience confusion or receive conflicting information when attempting to install or migrate to Chef Infra Client 19.x, particularly on air-gapped networks. Additionally, the shift to Habitat packaging has led to unexpected installation extraction failures, including errors unzipping components into the new C:\hab or D:\hab directories.

Steps to Reproduce

Clarifying Information

Error Message

Installer is failing to unzip components into C:\hab or D:\hab 400 Bad Request or the installer ignores the version request and defaults to installing 18.x chef19migrate.log rollback actions and /hab directory deletion

Defect Number

Enhancement Number

Cause

The installation processes and failures stem from the recent architectural packaging changes and two known software defects:

Multiple Windows Drives (Defect CHEF-32916): Please note this is based on your provided information. There is a known engineering defect where the Windows installer fails to unzip components into the hab directory if the system has multiple drives (e.g., a C:\ and a D:\). Progress Chef Engineering is actively working on a fix for this issue.
Incompatibility with Chef Automate (Defect CHEF-32685): On Linux, natively packaged Chef Client 19.x is incompatible with Chef Automate. Attempting to install the native package on a system where Automate is already installed will fail and subsequently delete the existing /hab directory.
Project Name Change: The software package name used in the download API and installer scripts changed from chef to chef-ice (Infra Client Enterprise). If chef-ice is not explicitly specified, installer scripts will default to version 18.x or earlier.
Insufficient Disk Space: Disk size requirements have increased. Chef Infra Client 19 now requires a minimum of 2.1 GB of free disk space on Windows (stored in C:\hab) and 600 MB on Linux (stored in /hab)

Resolution

For Windows multiple-drive issues (CHEF-32916): Progress Chef Engineering is actively tracking and working on a resolution.
For Linux systems running Automate: Do not install the natively packaged Chef Client 19 on any systems where Chef Automate is present. You may bypass the native packages and migration tool by performing a DIRECT Habitat installation of Chef Client 19.x instead.

Before proceeding with any standard installation scenario, ensure your target system meets the new prerequisites:

You possess a valid Progress Chef License key.
The target system has at least 2.1 GB of free disk space for Windows or 600 MB for Linux.

Choose the scenario below that best fits your environment:

Scenario 1: Air-Gapped Upgrades and Migrations To upgrade existing nodes on an air-gapped network, use the new migrate-ice utility.

Download the migration tool and the Chef Infra Client package to an internal server.
Execute the migration tool in air-gap mode, pointing to your local download URL: migrate-ice apply airgap --download-url <LOCAL_DOWNLOAD_URL> --license-key <LICENSE_KEY>.

Scenario 2: Fresh Air-Gapped Installations For brand new air-gapped systems, the native installers are highly efficient. On a machine with internet access, download the pre-built .msi, .deb, or .rpm installer packages. Transfer the package to your air-gapped network and install it using your system's native package manager.

Scenario 3: Fresh Online Installation If you are running the install.sh or install.ps1 scripts, you must explicitly opt-in to version 19 by specifying the chef-ice project:

Windows: . { iwr -useb https://chefdownload-commercial.chef.io/install.ps1?license_id=<LICENSE_ID> } | iex; install -project chef-ice -version 19.x.x.
Linux: curl -L https://chefdownload-commercial.chef.io/install.sh?license_id=<LICENSE_ID> | sudo bash -s -- -P chef-ice -v 19.x.x.

Scenario 4: Online Upgrade / Migration To upgrade-in-place from version 17.x or 18.x with an internet connection, use the migrate-ice tool. Run the tool specifying your target version and license key: migrate-ice apply online --chef-version <VERSION> --license-key <LICENSE_KEY>

Workaround

Notes

Keyword Phrase

Chef Infra Client 19, chef-ice, migrate-ice, air-gapped install, upgrade, Windows Habitat, C:\hab, D:\hab, CHEF-32685, CHEF-32916, multiple drives, Automate incompatible, install.ps1, install.sh, unzip components failing.

Last Modified Date

4/30/2026 3:27 PM

Comprehensive Guide to Installing and Migrating to Chef Infra Client 19.x (Online and Air-Gapped)

Files(0)

Was this article helpful?

Was this article helpful?

Comprehensive Guide to Installing and Migrating to Chef Infra Client 19.x (Online and Air-Gapped)

Information

Related Articles