Skip to content

Instantly share code, notes, and snippets.

@WardsParadox

WardsParadox/gam_wiki_ChromeOS_Devices.md

Created October 3, 2019 19:48
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save WardsParadox/b7ab1362f7a6f7ae2024b5de09feb8cc to your computer and use it in GitHub Desktop.
Save WardsParadox/b7ab1362f7a6f7ae2024b5de09feb8cc to your computer and use it in GitHub Desktop.
Download ZIP
GAM Wiki ChromeOS Devices Update
Raw
gam_wiki_ChromeOS_Devices.md

ChromeOS Devices

API documentation

Definitions

<OrgUnitPath> ::= /|(/<String)+
<QueryCrOS> ::= <String> See: https://support.google.com/chrome/a/answer/1698333
<CrOSID> ::= <String>
<CrOSIDList> ::= "<CrOSID>(,<CrOSID>)*"
<SerialNumber> ::= <String>
<SerialNumberList> ::= "<SerialNumber>(,<SerialNumber>)*"

<CrOSEntity> ::=
        <CrOSIDList> | (cros_sn <SerialNumberList>) |
        (query:<QueryCrOS>)|(query:orgunitpath:<OrgUnitPath>)|(query <QueryCrOS>) |
        <FileSelector> | <CSVFileSelector> | <CSVkmdSelector>

<CrOSAttribute> ::=
        (asset|assetid|tag <String>)|
        (location <String>)|
        (notes <String>)|(updatenotes <String>)|
        (org|ou <OrgUnitPath>)|
        (user <Name>)

<CrOSFieldName> ::=
        activetimeranges|timeranges|
        annotatedassetid|assetid|asset|
        annotatedlocation|location|
        annotateduser|user|
        autoupdateexpiration|
        bootmode|
        cpustatusreports|
        devicefiles|
        deviceid|
        diskvolumereports|
        dockmacaddress|
        ethernetmacaddress|
        ethernetmacaddress0|
        firmwareversion|
        lastenrollmenttime|
        lastsync|
        macaddress|
        manufacturedate|
        meid|
        model|
        notes|
        ordernumber|
        orgunitpath|org|ou|
        osversion|
        platformversion|
        recentusers|
        serialnumber|
        status|
        supportenddate|
        systemramtotal|
        systemramfreereports|
        tpmversioninfo|
        willautorenew
<CrOSFieldNameList> ::= "<CrOSFieldName>(,<CrOSFieldName>)*"

<CrOSListFieldName> ::=
        activetimeranges|timeranges|
        cpustatusreports|
        devicefiles|
        diskvolumereports|
        recentusers|
        systemramfreereports

<CrOSOrderByFieldName> ::=
        lastsync|location|notes|serialnumber|status|supportenddate|user

<CrOSAction> ::=
        deprovision_same_model_replace|
        deprovision_different_model_replace|
        deprovision_retiring_device|
        disable|
        reenable

Manage ChromeOS devices

gam update cros <CrOSEntity> <CrOSAttribute>+ [quickcrosmove [<Boolean>]]
gam <CrOSTypeEntity> update <CrOSAttribute>+ [quickcrosmove [<Boolean>]]

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 individual 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 <CrOSAttribute> being updated, the new method is used. If quickcrosmove is True and other <CrOSAttribute> 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 <CrOSAttribute>.

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.

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/2017 update ou /Students/2018 quickcrosmove

Example: Add a new note to existing notes

If you specify the updatenotes <String> 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#"

Action ChromeOS devices

gam update cros <CrOSEntity> action <CrOSAction> [acknowledge_device_touch_requirement]
gam <CrOSTypeEntity> update action <CrOSAction> [acknowledge_device_touch_requirement]

As deprovisioning ChromeOS devices in not reversible, you must enter acknowledge_device_touch_requirement when <CrOSAction> is deprovision_same_model_replace, deprovision_different_model_replace or deprovision_retiring_device.

Display ChromeOS devices

gam info cros <CrOSEntity> [guessaue] [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
        [basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
        [downloadfile latest|<Time>] [targetfolder <FilePath>] [formatjson]
gam <CrOSTypeEntity> info [guessaue] [nolists] [listlimit <Number>] [start <Date>] [end <Date>]
        [basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
        [downloadfile latest|<Time>] [targetfolder <FilePath>] [formatjson]

By default, Gam displays the information as an indented list of keys and values:

  • formatjson - Display the fields in JSON format.

Download a ChromeOS device file

gam info cros <CrOSEntity> [downloadfile latest|<Time>] [targetfolder <FilePath>]
gam <CrOSTypeEntity> info [downloadfile latest|<Time>] [targetfolder <FilePath>]

Select the device file to download by its timestamp.

  • downloadfile latest - Download the device file with the most recent timestamp.
  • downloadfile <Time> - Download the device file with the <Time>` timestamp.

By default, when getting a device file, it is downloaded to the directory specified in gam.cfg/drive_dir.

  • targetfolder <FilePath> - Specify an alternate location for the downloaded file.

Example

Suppuse that you have an OU "/Kiosk Chromebooks" that contains ChromeOS devices running in kiosk mode and you want to download their device files.

Get the list of device files.

gam redirect csv ./CrOSDeviceFiles.csv cros_ou "/Kiosk ChromeBooks" print cros fields deviceId,devicefiles

Download the device files serially.

gam redirect stdout ./CrOSDeviceFiles.out redirect stderr stdout csvkmd cros ./CrOSDeviceFiles.csv keyfield deviceId matchfield deviceFiles.type LOG_FILE datafield deviceFiles.createTime get devicefile select csvdata deviceFiles.createTime

Download the device files in parallel.

gam redirect stdout ./CrOSDeviceFiles.out multiprocess redirect stderr stdout csv ./CrOSDeviceFiles.csv matchfield deviceFiles.type LOG_FILE gam cros ~deviceId get devicefile select ~deviceFiles.createTime

Suppose you want only the last device file for each Chromebook.

Download the device files serially.

gam redirect stdout ./CrOSDeviceFiles.out redirect stderr stdout cros_ou "/Kiosk ChromeBooks" get devicefile select last 1

Download the device files in parallel

gam config auto_batch_min 1 redirect stdout ./CrOSDeviceFiles.out multiprocess redirect stderr stdout cros_ou "/Kiosk ChromeBooks" get devicefile select last 1

Print ChromeOS devices

Print no header row and deviceId for specified CrOS devices

gam <CrOSTypeEntity> print
gam <CrOSTypeEntity> print cros

Print a header row and fields for selected CrOS devices

gam print cros [todrive <ToDriveAttribute>*]
        [(query <QueryCrOS>)|(queries <QueryCrOSList>)] [limittoou <OrgUnitItem>]
        (querytime.* <Time>)* [guessaue]
        [orderby <CrOSOrderByFieldName> [ascending|descending]]
        [nolists|(<CrOSListFieldName>* [onerow]) [listlimit <Number>] [start <Date>] [end <Date>]
        [basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
        [sortheaders] [formatjson] [quotechar <Character>]

Use these options to select CrOS devices; if none are chosen, all CrOS devices in the account are selected:

  • (query <QueryCrOS>)|(queries <QueryCrOSList>) - Limit CrOS devices to those that match a query
  • limittoou <OrgUnitItem> - Limit CrOS devices to those directly in the OU <OrgUnitItem>

Use the querytime.* <Time> option to allow times, usually relative, to be substituted into the query <QueryCrOS> and queries <QueryCrOSList> options. The querytime.* <Time> value replaces the string #querytime.*# in any queries. The characters following querytime can be any combination of lowercase letters and numbers.

Print a header row and fields for specified CrOS devices

gam print cros [todrive <ToDriveAttribute>*] select <CrOSTypeEntity>
        [guessaue]
        [orderby <CrOSOrderByFieldName> [ascending|descending]]
        [nolists|(<CrOSListFieldName>* [onerow]) [listlimit <Number>] [start <Date>] [end <Date>]
        [basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
        [sortheaders] [formatjson] [quotechar <Character>]

gam <CrOSTypeEntity> print cros [todrive <ToDriveAttribute>*]
        [guessaue]
        [orderby <CrOSOrderByFieldName> [ascending|descending]]
        [nolists|(<CrOSListFieldName>* [onerow])] [listlimit <Number>] [start <Date>] [end <Date>]
        [basic|full|allfields] <CrOSFieldName>* [fields <CrOSFieldNameList>]
        [sortheaders] [formatjson] [quotechar <Character>]

The first column will always be deviceId; the remaining field names will be sorted if allfields, basic, full or sortheders is specified; otherwise, the remaining field names will appear in the order specified.

  • basic - Output these column headers: deviceId,annotatedAssetId,annotatedLocation,annotatedUser,lastSync,notes,serialNumber,status

  • allfields/full - Output all column headers including six list headers: activeTimeRanges, cpuStatusReports, deviceFiles, diskVolumeReports, recentUsers and systemRamFreeReports that repeat with multiple subvalues each, yielding a large number of columns that make the output hard to process.

  • nolists - Suppresses these six headers; if you want these headers in a more manageable form use the following arguments.

  • <CrOSListFieldName> - By default, one set of values for all <CrOSListFieldName> fields specified will be output on a separate row with all of the other headers.

  • onerow - Output all of the <CrOSListFieldName> on a single row

  • listlimit <Number> - Limits the number of repetitions to <Number>; if not specified or <Number> equals zero, there is no limit.

  • start <Date> and end <Date> - Constrain activeTimeRanges, cpuStatusReports, deviceFiles and systemRamFreeReports to fall within the specified <Dates>. If a <Date> isn't specified, there is no filtering in that range.

  • guessaue - Output columns guessedAUEDate and guessedAUEModel that indicate the Auto Update Expiration information for the device. You should compare model and guessedAUEModel to verify that the proper date has been determined.

By default, Gam displays the information as columns of fields; the following option causes the ouput to be in JSON format:

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char.

Examples

Print information about CrOS devices synced more than 30 days ago:

gam print cros query "sync:..#querytime1#" querytime1 -30d

Print information about CrOS devices synced in the last 30 days:

gam print cros query "sync:#querytime1#.." querytime1 -30d

Print information about CrOS devices synced between 45 days ago and 30 days ago:

gam print cros query "sync:#querytime1#..#querytime2#" querytime1 -45d querytime2 -30d

Print ChromeOS device activity

Print a header row and activity for selected CrOS devices

gam print crosactivity [todrive <ToDriveAttribute>*]
        [(query <QueryCrOS>)|(queries <QueryCrOSList>)] [limittoou <OrgUnitItem>]
        (querytime.* <Time>)*
        [orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all] [listlimit <Number>] [start <Date>] [end <Date>]
        [delimiter <Character>] [formatjson] [quotechar <Character>]

Use these options to select CrOS devices; if none are chosen, all CrOS devices in the account are selected:

  • (query <QueryCrOS>)|(queries <QueryCrOSList>) - Limit CrOS devices to those that match a query
  • limittoou <OrgUnitItem> - Limit CrOS devices to those directly in the OU <OrgUnitItem>

Use the querytime.* <Time> option to allow times, usually relative, to be substituted into the query <QueryCrOS> and queries <QueryCrOSList> options. The querytime.* <Time> value replaces the string #querytime.*# in any queries. The characters following filtertime can be any combination of lowercase letters and numbers.

Print a header row and activity for specified CrOS devices

gam print crosactivity [todrive <ToDriveAttribute>*] select <CroSTypeEntity>
        [orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all]
        [listlimit <Number>] [start <Date>] [end <Date>]
        [delimiter <Character>] [formatjson] [quotechar <Character>]

gam <CroSTypeEntity> print crosactivity [todrive <ToDriveAttribute>*]
        [orderby <CrOSOrderByFieldName> [ascending|descending]] [recentusers] [timeranges] [both] [devicefiles] [all]
        [listlimit <Number>] [start <Date>] [end <Date>]
        [delimiter <Character>] [formatjson] [quotechar <Character>]

  • The basic column headers are: deviceId,annotatedAssetId,annotatedLocation,serialNumber,orgUnitPath.

  • recentusers - All of the recent users email addresses, separated by the delimiter <Character>, with header recentUsers.email, are output with the basic headers.

  • The delimiter defaults to gam.cfg/csv_output_field_delimiter.

  • timeranges - For each time range entry, activeTimeRanges.date, activeTimeRanges.duration and activeTimeRanges.minutes are output on a separate row with the basic headers.

  • devicefiles - For each device file, the columns deviceFiles.type and deviceFiles.createTime are output on a separate row with the basic headers.

  • both - Specifies recentusers and timeranges.

  • all - Specifies recentusers, timeranges and devicefiles.

  • The default is to include both recentusers and timeranges.

  • listlimit <Number> - Limits the number of repetitions to <Number>; if not specified or <Number> equals zero, there is no limit.

  • start <Date> and end <Date> - Filter the time ranges and device files to fall with in the specified <Dates>. If a <Date> isn't specified, there is no filtering in that range.

By default, Gam displays the information as columns of fields; the following option causes the ouput to be in JSON format:

  • formatjson - Display the fields in JSON format.

By default, when writing CSV files, Gam uses a quote character of double quote ". The quote character is used to enclose columns that contain the quote character itself, the column delimiter (comma by default) and new-line characters. Any quote characters within the column are doubled. When using the formatjson option, double quotes are used extensively in the data resulting in hard to read/process output. The quotechar <Character> option allows you to choose an alternate quote character, single quote for instance, that makes for readable/processable output. quotechar defaults to gam.cfg/csv_output_quote_char.

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.

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|disable|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 March 23, 2013, enter the following:

gam print cros query "register:2013-03-23"

For additional examples using dates, times, and ranges, see "Format for date and time 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 October 12, 2013, enter the following:

gam print cros query "sync:2013-10-12"

For additional examples using dates, times, and ranges, see "Format for date and time searches" below.

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"

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment