Deploy the Chrome OS Readiness Tool

For admins who manage Windows devices and want to deploy the Chrome OS Readiness Tool within their organization.

The Chrome OS Readiness Toolis Microsoft Windows software that an admin can deploy to determine how ready devices are to switch to Chrome OS.

The tool collects application usage information for a set assessment interval (default: 30 days). All data is kept private in your designated storage and is not shared with Google. The tool identifies processes as Chrome OS Ready or not based on a provided application classification library that you can further modify to suit your domain.

If a device uses only Chrome OS Ready applications, such as browsers, applications with web app equivalents, or system utilities, it is identified as ready to switch. For devices that use applications where the readiness may depend on use case, or applications the tool does not recognize, the tool highlights them as ready with verification of the applications. You can also add blocker applications that you know have no equivalent on Chrome OS, which rules out devices as blocked from switching.

For more information on classification, see Modify the application library. For more information on the summary reports produced, see Generate reports. For more information on what the tool collects from client machines, see About the Chrome OS Readiness Tool.

Download the tool software bundle

We recommend that you configure the Chrome OS Readiness Tool on an account with admin access.

  1. Download the latest version of the Chrome OS Readiness Tool, ChromeOSReadinessBundle_x.x.x.x_en.msi installer, from the Chrome OS Readiness Tool homepage.
  2. Run the installer with elevated permissions on a machine to install the following files:
File Detail Location
ChromeOSReadinessService_x.x.x.x_en.msi Service installer to be deployed on the client machines. C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\deployment
en_US\chrome_os_readiness.adml, chrome_os_readiness.admx ADMX/ADML template to support the configuration of registry settings via GPO. C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\deployment
configure_trial_template.ps1

Sample Powershell script for deployment.

Note: Do not modify this template directly. If you need to modify it, make a copy. This file is also used by the setup wizard to generate deployment scripts.

C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\deployment
encrypt_credentials.ps1 A helper script to encrypt your service account key for manual deployment with our deployment template. C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\deployment
chromeos_readiness_wizard.exe Setup wizard for configuration within a UI. C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\wizard
base_library.json Chrome OS Readiness base library for reference
This is included in the classification database.
C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\library
crt_helper.exe Helper tooling executable to generate reports and modify the application library. C:\Program Files (x86)\Google\Chrome OS Readiness Bundle\bin

The Chrome OS Readiness Tool service can be deployed to devices running Windows 7 and later, and is compatible With Windows Server 2008 R2 onward.

Deployment configuration

You can configure the ChromeOSReadinessService_x.x.x.x_en.msi software service using the Chrome OS Readiness Tool Setup Wizard, chromeos_readiness_wizard.exe, for deployment to client machines.

The setup wizard is compatible with Windows 8 and later.

For more information on options and manual configuration, see Alternative deployment options.

Step 1: Setup storage

You can set up storage to where the tool will write reports, and from where it can access configuration data.

  1. Double-click chromeos_readiness_wizard.exe to start the setup wizard.
  2. Select one of the following storage options for the tool:
    • Network shared folders—Create two shared folders, one read-only for clients, and one write-only for clients. Browse for those as the Library and Results folder path, respectively from the UI.
    • Google Cloud Storage (GCS) buckets—You need the service account key JSON file associated with an account with sufficient credentials. For more information on configuring the Google Cloud Storage account with proper permissions and fetching the service account key, see Configure Google Cloud Storage.
      When you have the service account key file, point the wizard at this file and click Next. The tool creates the appropriate buckets in your GCS account before continuing to the next page. You can also optionally modify the bucket name prefix that the tool uses.
Step 2: Configure settings

For configuring your settings, we recommend you look at the Total data collection (days) value and decide how long a collection period you want. The default is thirty days, but you can specify a low value for a test run, or decide to get full data more quickly, for example in two weeks. See Modify registry settings for the other values.

Step 3: Generate a configuration script

You must specify a location to generate a configuration Powershell script that can be pushed out with the service .msi itself in software deployment tooling such as Windows SCCM or Intune.

You should follow the instructions for your software management solution to do the following:

  1. Designate a group of devices to which you will deploy the tool.
  2. Execute the Powershell configuration script on those devices. Depending on the software, this might involve custom actions or task sequences.
  3. Push the Chrome OS Readiness system service .msi, using a created application, packages, or similar, out to the desired endpoints.

If you have configured Google Cloud Storage in Step 1, the tool displays a decryption key to copy on the next page. Copy the key and use it together with your deployment tool to unlock access to your Google Cloud data store in the exported configuration script.

Note: In earlier versions of the tool, the naming is slightly different. The parameters are named ...EncryptionKey and ...ENCRYPTION_KEY, not ...DecryptionKey and DECRYPTION_KEY. Although the naming has changed, the decryption key is identical to the encryption key.

You have several options to provide the key to the configuration script.

  • Command line argument for execution with the script (-GCSServiceAccountKeyDecryptionKey).
  • Environment variable to be set for script runtime (GCS_SERVICE_ACCOUNT_KEY_DECRYPTION_KEY).
  • If you are using Microsoft Configuration Manager: Task Sequence Variables to be set before script execution (TSEnvironment variable GCSServiceAccountKeyDecryptionKey).

You can also run this script locally to modify registry settings. For details, see Manual modification of deployment Powershell script. If you use a GCS data store, you must also provide a decryption key for the GCS service account key.

For instructions to deploy the software via GPO and other options, see Alternative deployment options.

After being deployed to machines, the service runs on the next sign in. We recommend rebooting the devices. The service should be displayed as running in the Services dialogue, and a tray icon appears that links users to About the Chrome OS Readiness Tool to learn more about the tool.

Now that the tool is collecting data, we recommend looking at the process library and adding new classifications to fit your use cases. For details, see Modify the application library. When the data collection period ends according to your specified assessment length, you can then Generate reports.

Note: Devices must be finished data collection before a readiness determination can be made for them. There are no intermediate results until all application usage is accounted for.

Alternative deployment options

You can configure the tool manually to support alternative deployment options.

Modify registry settings

The Chrome OS Readiness service depends on several registry settings that are machine-level policies (HKLM\Software\Policies) and need to be set before the service is installed.

The registry settings for configuration can be modified in the following ways:

  • Run our provided Powershell configuration script locally (preferred). For details, see Manual modification of the deployment Powershell script.
  • Use regedit.exe to modify them locally and manually for testing.
    1. Run regedit.exe as an admin.
    2. Create the key HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome OS Readiness.
    3. For Cloud setup, create the subkey Cloud Storage here, restricting access to only admins and the LOCAL SYSTEM account.
    4. Create the required configuration values within the registry key. For details see the Registry values table below.
  • Set the registry settings remotely via the deployment tool or GPO + .admx template. For details, see Deploy via GPO.

Registry values:

Name Value type Description
FinalReportPath String - select New>String value, displayed with type REG_SZ

The path to the results folder within the chosen data store. For GCS buckets, this begins with gs://.

This value must be set.

ConfigurationSharedPath String - select New>String value, displayed with type REG_SZ

The path to the edit set within the chosen data store. For GCS buckets, this begins with gs://.

This value must be one of the following:

  • An empty string if you are not using an edit set.
  • A valid path to data store containing a valid non-empty edit_set.json.
DataCollectionDays

DWORD - select New>DWORD (32 bit) value, displayed with type REG_DWORD

Note: regedit is likely to prompt for hexadecimal values instead of decimal.

Number of days that the service collects process data from client machines.
FinalReportRetryTimeDays

DWORD - select New>DWORD (32 bit) value, displayed with type REG_DWORD

Note: regedit is likely to prompt for hexadecimal values instead of decimal.

Number of hours that passes between attempts to generate and upload the final report if needed.
FinalReportRetryFrequencyHours

DWORD - select New>DWORD (32 bit) value, displayed with type REG_DWORD

Note: regedit is likely to prompt for hexadecimal values instead of decimal.

Number of days the service attempts to generate and upload the final report if the initial attempt was not successful.
DataDumpFrequencyHours

DWORD - select New>DWORD (32 bit) value, displayed with type REG_DWORD

Note: regedit is likely to prompt for hexadecimal values instead of decimal.

Interval number of hours between consecutive dumps of process data on client machines.
GCSServiceAccountKey (GCS configuration only) String - select New>String value, displayed with type REG_SZ String content of the unencrypted GCS service account key file, located in the Cloud Storage subkey.
Configure Google Cloud Storage

You can optionally configure GCS buckets and set registry values yourself. However, we strongly recommend you do this automatically using the setup UI. For details on creating and downloading the service account key, see Manual setup.

When you have configured the buckets and downloaded the key, the ConfigurationSharedPath registry value should be set to the following value: gs://configuration-bucket-name/.

The full path to the registry value is HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome OS Readiness\ConfigurationSharedPath.

The ending forward slash is optional, but the name of the edit set contained in the configuration bucket, edit_set.json, should not be part of the registry value. Also, if you added your edit set to a directory within the bucket, you can add the full path to that directory, separated by forward slashes, similar to using a standard directory path.

Note: There must be an edit_set.json file in your configuration bucket. You can rename and use the empty_edit_set.json file from the deployment folder of the Chromebook Ready Bundle as a minimal template, but it must be called edit_set.json.

The FinalReportPath registry value should be set as follows: gs://report-bucket-name/.

The full path to the registry value is HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome OS Readiness\FinalReportPath.

Just as the configuration bucket, the ending forward slash is optional, and subdirectories can be used.

Note: The guide on setting up permissions only covered setting bucket-level permissions, but it is possible to only give the service accounts access to a specific directory or a specific object within a bucket. However, this is not recommended for privacy-critical applications such as these, and it’s simpler to create multiple buckets without any subdirectories. For details, see Overview of access control.

Manual modification of the deployment Powershell script

We provide a sample .ps1 script file that you can reference outside of the UI configuration to set all policies in a client before running the service installer. The script must be run with admin permissions.

Make a copy of configure_trial_template.ps1 and modify and un-comment the appropriate values under CONFIGURATION VALUES.

  • $FINAL_REPORT_PATH to point to the path for your report storage.
  • $CONFIGURATION_SHARED_PATH to point to the path for your configuration file.
  • (Optional) Any of the four numeric values to update settings, particularly $DATA_COLLECTION_DAYS.
  • If you are deploying via GCS, provide an encrypted service account key for $GCS_ENCRYPTED_SERVICE_ACCOUNT_KEY. You can get this by encrypting the downloaded plain-text key using the encrypt_credentials.ps1 helper script in the deployment folder.
    A description and examples of how this can be done can be found at the beginning of the script. This helper script also generates and displays the decryption key you can use together with the modified configuration script at runtime.
    Note: If you are using version 1.0.0.0, there is a known bug with this script. For details, see Troubleshooting.
  • For details on how to provide the decryption key at runtime, see Step 3: Generate a configuration script.
Reconfigure or uninstall an assessment

To support additional behaviors such as reconfiguring an existing trial or removing registry policies, the generated Powershell script can run in the following modes: (parameter -mode, see also the synopsis at the top header of the Powershell script file).

  • -mode install—The script sets the configured policy values (CONFIGURATION VALUES) in the registry and lock down permissions on the Cloud credentials in the registry. Run this to configure a trial on a machine before running the service .msi. This mode is the default.
  • -mode reconfigure—The script updates to the configured policy values in the registry but not change already configured permissions, and restart the service. Run this to reconfigure a running trial.
  • -mode remove—After a trial and after the service .msi has been uninstalled, use this mode to delete all policies in the registry.
Deploy via GPO

You can also deploy the tool via Group Policy Object (GPO).

  1. Save the .msi to a shared folder for distribution on the server.
    This is a distinct folder from the two folders (configuration and results) used previously.
    Note: The registry settings need to be made, either as in the Registry values section or by using the ADMX template.
  2. When the corresponding organizational unit and GPO are created, assign the .msi package. For details, see step 4 of Deploying an MSI through GPO.

It can take up to 2 hours for the updated GPO to be deployed. To immediately deploy, you can run gpupdate /Force on the devices and reboot the client machine when prompted. The service should now be displayed as running in the Windows Services app, services.msc.

Local setup

You can perform a test deployment on your machine.

  1. Configure the policies and settings manually using regedit or the configure_trial_template.ps1 script we provide. You can also use the script generated by the setup wizard for local setup.
  2. Double click ChromeOSReadinessService_x.x.x.x_en.msito start the software installation and confirm the system changes.
  3. To verify the .msi, do the following:
    1. Right-click the .msi.
    2. Select Properties and then the Digital Signatures tab. A Google LLC signature is displayed.
Custom configuration with post-processing

New deployment options will be added over time, but if none of the steps outlined above fit your environment and workflows, you can script custom post-processing for the results data. You can then send them to alternative destinations if needed.

Deploy a scheduled task on all devices in a domain using the Windows Task Scheduler

  1. Go to the Group Policy Management Console.
  2. Right-click the Group Policy object (GPO) associated with your organizational unit.
  3. Click Edit.
  4. On the left under Computer Configuration, go to Preferencesand thenControl Panel Settings.
  5. Right-click Scheduled Tasks, point to New, and select Scheduled Task (At least Windows 7).
  6. In the New Task (At least Windows 7) Properties box:
    1. In the General tab, select Action: Create.
    2. In Name, enter the task name.
    3. In When running the task, use the following user account:,enter SYSTEM.
    4. In the Triggers tab, select New….
    5. From the Begin the task list, select On an event.
    6. In the Settings box, select Custom.
    7. Click New Event Filter….
    8. In the New Event Filter dialog, select the XML tab, select the Edit query manually box, and paste the following xml:
      <QueryList> 
         <Query Id="0"> 
            <Select Path="System"> 
               *[EventData[Data[@Name='param1'] and (Data='Chrome OS Readiness Tool')]] 
               and
               *[EventData[Data[@Name='param2'] and (Data='disabled')]] 
             </Select> 
         </Query> 
      </QueryList>


      Note: If the device language is other than English, you might need to use different keyword to disabled as the second parameter.
    9. On the Actions tab, add any particular action to be done after the trial is over. See Example of how to add a powershell.exe invocation.
    10. You can configure any additional parameters on the remaining tabs, if necessary.

Example of how to add a a powershell.exe invocation:

  1. Select New...
  2. In the Action list, select Start a program.
  3. (Optional) In Program/Script, enter powershell.exe and add any parameters to Add arguments.
    Note: If selecting a script for post-processing, make sure it is distributed to the devices, via shared folder or other means, and a correct path to it is specified in arguments.

Scheduled tasks can also be configured on a device locally instead of a GPO.

  1. Go to Task Scheduler and select Create Task….
  2. Follow the same instructions for setting the task.

For full instructions, see Configure a Scheduled Task Item (At least Windows 7).

Troubleshooting

If you are encountering difficulties deploying and using the tool, contact the Chrome OS Readiness Tool team at crosready-support@google.com. Make sure to include your debug logs.

  • If you have an issue with the setup wizard, include logs located in C:\Users\username\AppData\Local\Google\Chrome OS Readiness\wizard_logs on the device where wizard was installed.
  • If you have an issue with deployment or the analysis, include the following logs from one or more devices to where the service was deployed:
    • debug.* from C:\Program Data\Google\Chrome OS Readiness
    • C:\Windows\Logs\ChromeOS-Readiness-Configuration.log
    • C:\Windows\Logs\Install-Chrome-OS-Readiness.log
  • If you have an issue with the helper tool, run the failing command with --debug flag and attach the debug.log file generated in the process. It will be generated in the folder you run the helper tool from, so make sure writing to this folder does not require special permissions. For example, it is not possible to generate this file in C:\Program Files (x86)\Google\Chrome OS Readiness Bundle subfolders.

Some specific issues and their resolutions are detailed below.

The Setup Wizard is failing to configure GCS buckets with the service account key file

Confirm the following:

  • The service account key you are using was appropriately configured according to the automatic setup instructions for GCS. For details, see Configure Google Cloud Storage: Automatic setup.
  • You have a working internet connection and the wizard is not blocked from communicating with the Google Cloud servers.
  • Your time and time zone are set correctly. Otherwise, the wizard might fail to authenticate with Google Cloud. If necessary, sync with the Google Network Time Protocol (NTP). For details, see Google Public NTP.
  • In your Cloud project, you have enabled necessary APIs. For details, see Create a privileged service account key for use with the wizard.
The software deployment solution returned an error when attempting to execute the configuration script

Make sure you are running the configuration script with system privileges.

If you are using GCS as your data storage, confirm that you have provided the decryption key to your deployment tooling.

If you are experiencing further issues, contact support and include the name of your deployment tooling and any relevant logs from that software.

Once deployed, device reports are not showing up

Note: Reports only appear in the configured results folder after the configured period of time. For example, if you configured the trial to run for 30 days, there will be no intermediate results on either day 1 or day 7.

Make sure that the device is online and the system service shows as running in the Windows tray. Also, check that the required registry settings have been deployed. For details, see Modify registry settings.

If you are configuring via GCS, make sure that you have an edit_set.json file in the configuration bucket. You can rename and use the empty_edit_set.json file we provide if you are not making any modifications. If the timezone or date and time are not set correctly on the client devices, GCS reporting might not work. Make sure the time is synced to the Google NTP or synchronized to the internet in the Windows settings.

If you are configuring via shared folders, and you have a configuration path configured, make sure there is a valid edit_set.json at this location. Alternatively, you can omit configuring a shared folder path.

At the conclusion of the assessment period, not all devices have reported results

Review the service debug logs on the devices that have not reported back. Alternatively, send them to the Chrome OS Readiness Tool team at crosready-support@google.com for review.

Note: The service retries report upload for the configured retry period, so devices might still report if they lost network connectivity. Additionally, the deployment of the tool might have been delayed on some devices and the trial might still be running on those devices.

The Helper Tool is taking a long time to download reports for analysis

Particularly for large volumes of reports, consider using the free gsutil tool to download the reports to local storage and run the helper tool locally.

After downloading, installing, and initializing the Cloud SDK, you can download all the reports from a bucket by running gsutil -m cp -r gs://bucket-name/ ., which creates a new directory called bucket-name and stores the reports there.

Important: Make sure to include the period after the bucket path as part of the argument. You can then run the helper tool using local paths.

For more information, see Downloading reports with gsutil.

Credentials encrypted manually using encrypt_credentials.ps1 do not work with the deployment script

You are preparing a Cloud setup manually and have run encrypt_credentials.ps1 from the 1.0.0.0 bundle to encrypt your downloaded credentials, and at least one of the following occurs:

  • The deployment script containing the encrypted credentials signals the credentials are invalid, even with the correct decryption key provided. For example, the script displays the error message:
    Error message: Input string was not in a correct format.
  • After running the script, only the first line of the original unencrypted JSON credentials file appears in the registry value on the test machine. For example, only { appears.
  • The encrypted credentials file generated by encrypt_credentials.ps1 contains multiple lines.

This is a known bug in the encrypt_credentials.ps1 script of bundle version 1.0.0.0. In this version, encrypt_credentials.ps1 does not correctly encrypt multi-line json credential files.

The script reads the unencrypted credentials using Powershell’s Get-Content function, which parses multiple lines of text into an array instead of a single string. If you use Powershell 3.0 or later, you can fix the script manually by adding the -Raw parameter to line 66 of the script, as shown below.

$service_account_key = Get-Content -Raw -Path $CredentialsFilePath

Was this helpful?
How can we improve it?