[Tutorial] Shimless RMA

Run IWA via USB drive

Prerequisites

1. IWA ID [1] must be included in the allowlist in Chrome codebase.
2. An empty USB drive in Ext4 or FAT format.
3. Signed IWA bundle (.swbn).
4. Published Chrome extension package (.crx), downloaded from Chrome Web Store Developer Dashboard.

[1] Follow "Build and Deploy the App" below to get IWA ID.

Steps

1. Copy your Singed IWA bundle and the Chrome extension to the root of the USB drive, and rename them to diagnostics_app.swbn and diagnostics_app.crx respectively.
2. Initiate Shimless RMA flow and plug in the USB drive.
3. Press alt + shift + D. You should see a popup asking for installing the app and granting permissions. Review and accept permissions to see the IWA.

---

IWA and Extension Development

Prerequisites

1. Clone the repo here: https://github.com/GoogleChromeLabs/cros-sample-telemetry-extension
2. Put the device in developer mode by following the instructions here
3. The device root file system must have write permission enabled (Run /usr/share/vboot/bin/make_dev_ssd.sh --remove_rootfs_verification on your DUT)

Enter Shimless RMA flow on your DUT

Use key combo to enter Shimless RMA, or follow the steps below to always enter Shimless RMA after boot.

1. Run the following script on your DUT to enter RMA Mode

$ mkdir -p /mnt/stateful_partition/unencrypted/rma-data
$ touch /mnt/stateful_partition/unencrypted/rma-data/state
$ chown rmad /mnt/stateful_partition/unencrypted/rma-data/state
$ mkdir -p /var/lib/rmad/.test
$ start rmad # or restart rmad if rmad is already started

Set up 3p Diagnostics environment on your DUT

1. Enable OS flags by appending to the file /etc/chrome_dev.conf on DUT:

$ vim /etc/chrome_dev.conf

...
################################################################################
# This file should only be modified by hand by developers on their local
# dev-mode devices; do not check in changes to it or write code that modifies
# it. Permanent changes to Chrome's configuration, including conditionally-set
# flags, should be made in session_manager (see chrome_setup.h).
#
# To edit this file rootfs write protection must be removed:
# https://chromium.googlesource.com/chromiumos/docs/+/HEAD/developer_mode.md#disable-verity
################################################################################
--enable-features=IsolatedWebAppDevMode,ShimlessRMA3pDiagnosticsDevMode,,ShimlessRMA3pDiagnosticsAllowPermissionPolicy

2. Change cros_healthd init config to run using test chromeos-config by appending the --test_cros_config flag:

$ vim /etc/init/cros_healthd.conf

...
# Run the daemon.
exec /usr/bin/cros_healthd --test_cros_config

3. Override the device OEM to Google

$ cp -r /run/chromeos-config/v1 /run/chromeos-config/test
$ printf %s 'Google' > /run/chromeos-config/test/branding/oem-name
# Note: You must stop then restart cros_healthd here, running restart will not propagate the change.
$ stop cros_healthd && start cros_healthd 

Build and Deploy the App to your DUT

1. Enter the diagnostics-app subdirectory in cros-sample-telemetry-extension repo:

$ cd diagnostics-app

2. Build app by running the following commands:

$ npm ci
$ npm run build_iwa

The last line of output is the IWA ID. If you used our private key, it should be pt2jysa7yu326m2cbu5mce4rrajvguagronrsqwn5dhbaris6eaaaaic. Please make sure you replace the key with yours before moving to production.

In addition, you should see the file sample-iwa.swbn at cros-sample-telemetry-extension/diagnostics-app/dist/iwa.

3. Deploy the app files to DUT

$ export DUT="Your-DUT-hostname"
$ scp dist/iwa/sample-iwa.swbn $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn
$ ssh $DUT chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.swbn  # Make sure the file is visible

Build and Deploy the Extension to your DUT

1. Enter the diagnostics-extension subdirectory in cros-sample-telemetry-extension repo:

cd diagnostics-extension

2. Modify permission and externally_connectable attribute in public/manifest.json to match the IWA ID. Alternatively, you can copy paste the below file content (again, don't forget to replace the IWA ID with yours later!):

$ vim public/manifest.json

{
  "name": "Chrome OS Diagnostics Companion Extension",
  "version": "1.9.0",
  "description": "The companion extension for the ChromeOS Diagnostics App.",
  "manifest_version": 3,
  "chromeos_system_extension": {},
  "icons": {
    "16": "images/favicon-16x16.png",
    "32": "images/favicon-32x32.png",
    "48": "images/favicon-48x48.png",
    "128": "images/favicon-120x120.png",
    "192": "images/favicon-192x192.png"
  },
  "permissions": [
    "os.telemetry",
    "os.attached_device_info",
    "os.diagnostics",
    "os.events",
    "os.telemetry.serial_number",
    "os.telemetry.network_info"
  ],
  "background": {
    "service_worker": "sw.js"
  },
  "externally_connectable": {
    "matches": [
      "isolated-app://pt2jysa7yu326m2cbu5mce4rrajvguagronrsqwn5dhbaris6eaaaaic/*"
    ]
  }
}

3. Build the extension files:

$ npm ci
$ npm run build

4. Package the extension into .crx format:

$ /usr/bin/google-chrome --pack-extension=./build --pack-extension-key=private_key.pem

5. Deploy the extension files to the DUT:

$ export DUT="Your-DUT-hostname"
$ scp build.crx $DUT://mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx
$ ssh $DUT chmod 777 /mnt/stateful_partition/unencrypted/rma-data/diagnostics_app.crx  # Make sure the file is visible

6. Publish to Chrome Web Store

This step is necessary before release. Unpublished extensions cannot be loaded in Shimless RMA.

Install and run the Diagnostics App on your DUT

1. Enter Shimless RMA by rebooting or restarting UI:

$ restart ui

2. Open the diagnostics app by pressing alt + shift + D

3. Review and accept permissions to see the app window.