[Tutorial] Shimless RMA - GoogleChromeLabs/cros-sample-telemetry-extension GitHub Wiki
Run IWA via USB drive
This section contains the steps to run your IWA via USB drive in Shimless RMA in normal mode (i.e., not in developer mode or any feature flags enabled).
Prerequisites
- IWA ID [1] and the companion extension ID must be included in the allowlist in Chrome codebase.
- An empty USB drive in Ext4 or FAT format.
- Signed IWA bundle (
.swbn
). - Published Chrome extension package (
.crx
), downloaded from Chrome Web Store Developer Dashboard.
[1] Follow "Build and Deploy the App" below to get IWA ID. It must not be ours (pt2jysa7yu326m2cbu5mce4rrajvguagronrsqwn5dhbaris6eaaaaic
).
Steps
- Copy your Singed IWA bundle and the Chrome extension to the root of the USB drive, and rename them to
diagnostics_app.swbn
anddiagnostics_app.crx
respectively. - Initiate Shimless RMA flow and plug in the USB drive.
- 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
This section contains the steps to build, deploy and run your IWA and its companion extension for Shimless RMA.
Prerequisites
- Clone the repo here: https://github.com/GoogleChromeLabs/cros-sample-telemetry-extension
- Put the device in developer mode by following the instructions here
- 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.
- 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
- 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
- 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
- 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 IWA to your DUT
- Enter the
diagnostics-app
subdirectory in cros-sample-telemetry-extension repo:
$ cd diagnostics-app
- 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
.
- 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
- Enter the
diagnostics-extension
subdirectory in cros-sample-telemetry-extension repo:
cd diagnostics-extension
- Modify
permission
andexternally_connectable
attribute inpublic/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/*"
]
}
}
- Build the extension files:
$ npm ci
$ npm run build
- Package the extension into
.crx
format:
$ /usr/bin/google-chrome --pack-extension=./build --pack-extension-key=private_key.pem
- 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
- Publish to Chrome Web Store [Optional for development]
This step is only necessary before release. Unpublished extensions cannot be loaded in Shimless RMA in normal mode.
Install and run the Diagnostics App on your DUT
- Enter Shimless RMA by rebooting or restarting UI:
$ restart ui
-
Open the diagnostics app by pressing
alt + shift + D
-
Review and accept permissions to see the app window.