# ChromeOS Devices - [API documentation](#api-documentation) - [Query documentation](#query-documentation) - [Notes](#notes) - [Definitions](#definitions) - [CrOS Query Searchable Fields](#cros-query-searchable-fields) - [ChromeOS device update OU error handling](#chromeos-device-update-ou-error-handling) - [Manage ChromeOS devices](#manage-chromeos-devices) - [Example: Move CrOS devices from one OU to another](#example-move-cros-devices-from-one-ou-to-another) - [Example: Add a new note to existing notes](#example-add-a-new-note-to-existing-notes) - [Add ChromeOS devices to an organizational unit](#add-chromeos-devices-to-an-organizational-unit) - [Example: Add ChromeOS devices to a single OU](#example-add-chromeos-devices-to-a-single-ou) - [Example: Add ChromeOS devices to multiple OUs](#example-add-chromeos-devices-to-multiple-ous) - [Action ChromeOS devices](#action-chromeos-devices) - [Send remote commands to ChromeOS devices](#send-remote-commands-to-chromeos-devices) - [Action Examples](#action-examples) - [ChromeOS device lists](#chromeos-device-lists) - [Display information about ChromeOS devices](#display-information-about-chromeos-devices) - [Print ChromeOS devices](#print-chromeos-devices) - [Print no header row and deviceId for specified CrOS devices](#print-no-header-row-and-deviceid-for-specified-cros-devices) - [Print a header row and fields for selected CrOS devices](#print-a-header-row-and-fields-for-selected-cros-devices) - [Print a header row and fields for specified CrOS devices](#print-a-header-row-and-fields-for-specified-cros-devices) - [Display Examples](#display-examples) - [Display CrOS device counts](#display-cros-device-counts) - [Print ChromeOS device activity](#print-chromeos-device-activity) - [Print a header row and activity for selected CrOS devices](#print-a-header-row-and-activity-for-selected-cros-devices) - [Print a header row and activity for specified CrOS devices](#print-a-header-row-and-activity-for-specified-cros-devices) - [Download a ChromeOS device file](#download-a-chromeos-device-file) - [Download Examples](#download-examples) - [Display ChromeOS telemetry data](#display-chromeos-telemetry-data) - [Check ChromeOS device serial number validity](#check-chromeos-device-serial-number-validity) ## API documentation * [Directory API ChromeOS Devices](https://developers.google.com/admin-sdk/directory/reference/rest/v1/chromeosdevices) * [Chrome Management API - Device Telemetry](https://developers.google.com/chrome/management/reference/rest/v1/customers.telemetry.devices) ## Query documentation * [Search ChromeOS Devices](https://developers.google.com/admin-sdk/directory/v1/list-query-operators) * [View ChromeOS Device List and Details](https://support.google.com/chrome/a/answer/1698333) Undocumented API query terms. ``` ::= YYYY-MM-DD # Specific date ..YYYY-MM-DD # Before a date YYYY-MM-DD.. # After a date YYYY-MM-DD..YYYY-MM-DD # Range of dates aue: compliance:compliant|pending_update|not_compliant last_user_activity: policy_status:true|false public_model_name: update_status:default_os_up_to_date|pending_update|os_image_download_not_started|os_image_download_in_progress|os_update_need_reboot ``` ## Notes To use the `crostelemetry` commands you must authorize an additional scope: * `Chrome Management API - Telemetry read only` ``` gam oauth create ``` Many commands come in two forms: ``` gam ... gam cros ... ``` The first form allows more powerful selection of devices with ``. The second form is backwards compatible with Legacy GAM and selection with `` is limited. ## Definitions * [``](Collections-of-ChromeOS-Devices) ``` ::= /|(/ ::= See: https://support.google.com/chrome/a/answer/1698333 ::= ::= ::= "(,)*" ::= ::= "(,)*" ::= | | See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= | (cros_sn ) | (query:)|(query:orgunitpath:)|(query ) ::= (asset|assetid|tag )| (location )| (notes )|(updatenotes )| (org|ou )| (user ) ::= activetimeranges|timeranges| annotatedassetid|assetid|asset| annotatedlocation|location| annotateduser|user| autoupdateexpiration| autoupdatethrough| backlightinfo| bootmode| cpuinfo| cpustatusreports| deprovisionreason| devicefiles| deviceid| devicelicensetype| diskvolumereports| dockmacaddress| ethernetmacaddress| ethernetmacaddress0| extendedsupporteligible| extendedsupportstart| extendedsupportenabled| firmwareversion| firstenrollmenttime| lastdeprovisiontimestamp| lastenrollmenttime| lastknownnetwork| lastsync| macaddress| manufacturedate| meid| model| notes| ordernumber| orgunitid| orgunitpath|org|ou| osupdatestatus| osversion| platformversion| recentusers| screenshotfiles| serialnumber| status| supportenddate| systemramfreereports| systemramtotal| tpmversioninfo| willautorenew ::= "(,)*" ::= activetimeranges|timeranges|times| cpustatusreports| devicefiles|files| diskvolumereports| lastknownnetwork| recentusers|users| screenshotfiles| systemramfreereports ::= "(,)*" ::= lastsync|location|notes|serialnumber|status|supportenddate|user ``` ``` ::= deprovision_different_model_replace| deprovision_different_model_replacement| deprovision_retiring_device| deprovision_same_model_replace| deprovision_same_model_replacement| deprovision_upgrade_transfer| disable| reenable| pre_provisioned_disable| pre_provisioned_reenable reboot| remote_powerwash| set_volume <0-100>| wipe_users| take_a_screenshot ``` ``` ::= activetimeranges|timeranges|times| devicefiles|files| recentusers|users ::= "(,)*" ::= audiostatusreport| batteryinfo| batterystatusreport| bootPerformancereport| cpuinfo| cpustatusreport| customer| deviceid| graphicsinfo| graphicsstatusreport| memoryinfo| memorystatusreport| name| networkdiagnosticsreport| networkinfo| networkstatusreport| orgunitid| osupdatestatus| peripheralsreport| serialnumber| storageinfo| storagestatusreport| thunderboltinfo ::= "(,)*" ::= audiostatusreport| batteryinfo| batterystatusreport| bootperformancereport| cpuinfo| cpustatusreport| graphicsstatusreport| memorystatusreport| networkdiagnosticsreport| networkstatusreport| osupdatestatus| peripheralsreport| storagestatusreport| thunderboltinfo ::= "(,)*" ``` For ``, see: [Collections of Items](Collections-of-Items) For ``, see: [Collections of Users](Collections-Of-Users) For ``, see: [Collections of ChromeOS Devices](Collections-of-ChromeOS-Devices) ## CrOS Query Searchable Fields To search within a specific field only (for example, to search for a specific user), you can enter an operator followed by an argument -- for example, `user:jsmith`. You can use single words or quoted lists of words as an argument when running an operator query. To run an operator query, follow these guidelines for each field: ### Serial Number Enter `id:` as the operator. For example, if you are searching for the serial number 12345abcdefg, enter the following: `gam print cros query "id:12345abcdefg"` Partial serial number searches are supported, as long as you enter at least three characters in the serial number. All serial number searches are partial, be careful that you don't enter a partial serial number by mistake when actioning/modifying devices as you will affect multiple devices rather than the single desired device. ### Status To view all provisioned or deprovisioned devices, select the status from the left drop-down, and all of the devices that fit this criterion will appear in the view. Alternatively, you can do the following searches from the All devices view: `gam print cros query "status:[provisioned|disabled|deprovisioned]"` ### User Enter user: as the operator. For example, to match the name Joe, but not Joey, enter the following: `gam print cros query "user:joe"` To match the name Tom Sawyer or A. Tom Sawyer, but not Tom A. Sawyer, enter with quotation marks: `gam print cros query "user:'tom sawyer'"` ### Location Enter location: as the operator. For example, to match Seattle, enter the following: `gam print cros query "location:seattle"` Notes Enter note: as the operator. For example, to match loaned from John, enter the following with quotation marks: `gam print cros query "note:'loaned from john'"` ### Register This field is not displayed on the Chrome OS settings page. However, you can search for devices that were registered on a given date, or within a given time range. Enter register: as the operator, and enter a date and time (or time range) as the argument. For example, to search for all devices registered on April 15, 2020, enter the following: `gam print cros query "register:2020-04-15"` For additional examples using dates, times, and ranges, see "Format for date searches" below. ### Last Sync Enter sync: as the operator and a date or time range as the argument. For example, to search for all devices that were last synced with policy settings on April 15, 2020, enter the following: `gam print cros query "sync:2020-04-15"` For additional examples using dates, times, and ranges, see "Format for date searches" below. ### Format for date searches * `YYYY-MM-DD` - A single date * `YYYY-MM-DD..YYYY-MM-DD` - A date range * `..YYYY-MM-DD` - All dates on or before a date * `YYYY-MM-DD..` - All dates on or after a date ### Asset ID Enter asset_id: as the operator. For example, to match the partial Asset ID 1234, enter the following: `gam print cros query "asset_id:1234"` ### WiFi MAC Address Enter wifi_mac: as the operator. Address should be entered without spaces or colons. Partial address matching is not supported. Be aware that multiple devices may report the same address to the Admin console, and more than one result may be returned. For example, to search for the device(s) with WiFi MAC 6C:29:95:72:4C:50, enter the following: `gam print cros query "wifi_mac:6c2995724c50"` ### Ethernet MAC Address Enter ethernet_mac: as the operator. Address should be entered without spaces or colons. Partial address matching is not supported. Be aware that multiple devices may report the same address to the Admin console, and more than one result may be returned. For example, to search for the device(s) with ethernet MAC E8:EA:6A:15:79:81, enter the following: `gam print cros query "ethernet_mac:e8ea6a157981"` ## ChromeOS device update OU error handling If you get the following error when trying to update the OU of a ChromeOS device: ``` 400: invalidInput - Invalid Input: Inconsistent Orgunit id and path in request ``` issue the following command to work around the Google problem causing the wrror: ``` gam select default config update_cros_ou_with_id true save ``` ## Manage ChromeOS devices ``` gam update + [quickcrosmove []] [nobatchupdate] gam update cros + [quickcrosmove []] [nobatchupdate] ``` Google has introduced a new, faster method for moving CrOS devices to a new OU. The `quickcrosmove` option controls which method Gam uses. * `quickcrosmove not specified` - use value from `quick_cros_move` in `gam.cfg` to select previous/new batch method * `quickcrosmove False` - use individual method * `quickcrosmove True` - use new method * `quickcrosmove` - use new method If `quickcrosmove` is False or the OU is not being updated, the individual method is used to update all attributes. If `quickcrosmove` is True and the OU is the only `` being updated, the new method is used. If `quickcrosmove` is True and other `` are being updated in addition to the OU, the new method is used to update the OU and the individual method is used to update the other ``. With either the individual or new method, batches of devices are processed to minimize the number of API calls. The `batch_size` value from gam.cfg controls the number of deviceIds handled in each batch by either method. Use the `nobatchupdate` option to suppress batch processing. In the new method, Google doesn't seem to do any error checking of the CrOS deviceIds, there is no error message given if invalid CrOS deviceIds are specified. ### Example: Move CrOS devices from one OU to another ``` gam cros_ou /Students/2021 update ou /Students/2022 quickcrosmove ``` ### Example: Add a new note to existing notes If you specify the `updatenotes ` option and it contains the string `#notes#`, the existing notes value will replace `#notes#`. This requires an additional API to get the existing value. If you have a CSV file, UpdateCrOS.csv with two columns: deviceId,notes this command will add a new line of notes to the front of the existing notes: ``` gam csv UpdateCrOS.csv gam update cros "~deviceId" updatenotes "~~notes~~\n#notes#" ``` ## Add ChromeOS devices to an organizational unit When adding ChromeOS devices to an OU, Gam uses a batch method to speed up processing. For ``, see: [Collections of ChromeOS Devices](Collections-of-ChromeOS-Devices) ``` gam update org|ou add|move [quickcrosmove []] gam update orgs|ous add|move [quickcrosmove []] ``` Google has introduced a new, faster batch method for moving CrOS devices to a new OU. The `quickcrosmove` option controls which method Gam uses. * `quickcrosmove not specified` - use value from `quick_cros_move` in `gam.cfg` to select previous/new batch method * `quickcrosmove False` - use previous batch method * `quickcrosmove True` - use new batch method * `quickcrosmove` - use new batch method The `batch_size` value from gam.cfg controls the number of deviceIds handled in each batch by either method. In the new method, Google doesn't seem to do any error checking of the CrOS deviceIds, there is no error message given if invalid CrOS deviceIds are specified. ### Example: Add ChromeOS devices to a single OU Suppose you have a CSV file cros.csv with a single column: deviceId ``` gam update ou /Students/2022 add croscsvfile cros.csv:deviceId quickcrosmove ``` ### Example: Add ChromeOS devices to multiple OUs Suppose you have a CSV file cros.csv with a two columns: deviceId,OU All OUs will be updated with their associated devices. ``` gam update ou csvkmd cros.csv keyfield OU datafield deviceId add croscsvdata deviceId ``` ## Action ChromeOS devices ``` ::= deprovision_different_model_replace| deprovision_retiring_device| deprovision_same_model_replace| deprovision_upgrade_transfer| disable| reenable gam update action [acknowledge_device_touch_requirement] [actionbatchsize ] gam update cros action [acknowledge_device_touch_requirement] [actionbatchsize ] ``` As of GAM version `6.67.00`, the new API function `batchChangeStatus` replaces the old API function `action`; ChromeOS devices are now processed in batches. The batch size defaults to 10, the `actionbatchsize ` option can be used to set a batch size between 10 and 250. As deprovisioning ChromeOS devices is not reversible, you must enter `acknowledge_device_touch_requirement` when `` is `deprovision_same_model_replace`, `deprovision_different_model_replace`, `deprovision_retiring_device` or `deprovision_upgrade_transfer`. Deprovisioning a device means the device will have to be physically wiped and re-enrolled to be managed by your domain again. This requires physical access to the device and is very time consuming to perform for each device. Please also be aware that deprovisioning can have an effect on your device license count. See https://support.google.com/chrome/a/answer/3523633 for full details. ## Send remote commands to ChromeOS devices Thanks to Jay for most of the following. Send a remote command to the managed Chrome OS device. It's important to note that the device must be in a proper state to accept the command or an error may be returned. For example, the `reboot`, `set_volume` and `take_a_screenshot` commands only work if the device is configured in auto-start kiosk app mode. The `wipe_users` and `remote_powerwash` commands will erase all user data on the device and the `remote_powerwash` command will require that the device is physically reconnected to the WiFi network and re-enrolled before it can be managed again. These commands require the `doit` argument so that the admin confirms the potential loss of user data and management. Commands may take some time to execute on the remote device depending on the device state and connectivity to the Internet. It's strongly recommended that devices be forced to auto-reenroll before performing `remote_powerwash` to prevent the device from falling out of a managed state permanently. By default, GAM will wait 2 seconds and then check the status of the command before exiting. How many times GAM performs this status check can be configured with the `times_to_check_status` argument and is configurable from 0 to some large number. If the status reaches `EXPIRED`, `CANCELLED` or `EXECUTED_BY_CLIENT` then the command has finished and no more checks will be performed. ``` reboot| remote_powerwash| set_volume <0-100>| wipe_users| take_a_screenshot gam cros issuecommand command [times_to_check_status ] [doit] gam issuecommand cros command [times_to_check_status ] [doit] ``` If the final status is not reached before GAM exits, you can issue the following commands to continue checking the status. ``` gam cros getcommand commandid [times_to_check_status ] gam getcommand cros commandid [times_to_check_status ] ``` ### Action Examples Remove user profile data from the device; the device will remain enrolled and connected. User data not synced to the Cloud including Downloads, Android app data and Crostini Linux VMs will be permanently lost. Commands with issuecommand directly after gam will work with Legacy GAM & GAM7, whereas commands where the issuecommand is after the cros will work only with GAM7. ``` gam issuecommand cros dd1d659a-0ea4-4e94-905e-4726c7a5f1e9 command wipe_users doit ``` Remove profiles using the annotatedAssetID, which is a user editable field, in this example the device has an asset ID of CB1234. ``` gam cros_query "asset_id:CB1234" issuecommand command wipe_users doit ``` For multiple devices you can separate each asset ID with a comma ``` gam cros_queries "asset_id:CB1234,asset_id:CB5678" issuecommand command wipe_users doit ``` Powerwash the device with serial number 143040348. ``` gam issuecommand cros query:id:143040348 command remote_powerwash times_to_check_status 10 doit gam cros_sn 143040348 issuecommand command remote_powerwash times_to_check_status 10 doit ``` Powerwash all devices in the /StudentCarts OrgUnit. Devices will need to be manually reconnected to WiFi which may mean entering a PSK. Use `wipe_users` if that's going to create too much work for you. ``` gam issuecommand cros "query:orgunitpath:/StudentCarts" command remote_powerwash times_to_check_status 0 doit gam cros_ou /StudentCarts issuecommand command remote_powerwash times_to_check_status 0 doit ``` ## ChromeOS device lists ChromeOS devices have lists of data: ``, ``, ``. All lists except `recentusers` are in ascending order (oldest to newest). As these lists can contain many entries, you can use the `listlimit ` option to limit the amount of data, but you'll get the oldest `` entries (except for `recentusers`) which may not be what you want. The `reverselists` option changes the order to descending (newest to oldest); the `listlimit ` now gets the newest `` entries. The `activetimeranges` and `recentusers` lists are independent, they are not aligned. The only alignment that you can achieve is `activetimeranges recentusers reverselists activetimeranges listlimit 1`; this yields the most recent user's activity time. List field name synonyms: - `activetimeranges` - `timeranges` and `times` - `devicefiles` - `files` - `recentusers` - `users` ## Display information about ChromeOS devices ``` gam info [basic|full|allfields] * [fields ] [nolists] [start ] [end ] [listlimit ] [reverselists ] [timerangeorder ascending|descending] [showdvrsfp] [downloadfile latest|