diff --git a/docs/Addresses.md b/docs/Addresses.md index aaf9dbe0..a9badf46 100644 --- a/docs/Addresses.md +++ b/docs/Addresses.md @@ -1,4 +1,4 @@ -# Addresses +!# Addresses - [API documentation](#api-documentation) - [Display addresses](#display-addresses) diff --git a/docs/Administrators.md b/docs/Administrators.md index 3b2d96d6..57ca302e 100644 --- a/docs/Administrators.md +++ b/docs/Administrators.md @@ -1,4 +1,4 @@ -# Administrators +!# Administrators - [Administrator roles documentation](#administrator-roles-documentation) - [API documentation](#api-documentation) - [Definitions](#definitions) diff --git a/docs/Alert-Center.md b/docs/Alert-Center.md index 1469dd68..06136968 100644 --- a/docs/Alert-Center.md +++ b/docs/Alert-Center.md @@ -1,4 +1,4 @@ -# Alert Center +!# Alert Center - [API documentation](#api-documentation) - [Definitions](#definitions) - [Introduction](#introduction) diff --git a/docs/Aliases.md b/docs/Aliases.md index 75538ccb..d919f100 100644 --- a/docs/Aliases.md +++ b/docs/Aliases.md @@ -30,7 +30,7 @@ See [Collections of Items](Collections-of-Items) ::= @ ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= id: ``` ## Create an alias for a target diff --git a/docs/Authorization.md b/docs/Authorization.md index c4aa714a..ef10e67f 100644 --- a/docs/Authorization.md +++ b/docs/Authorization.md @@ -168,7 +168,7 @@ gam oauth update ::= current | gam | | (filter ) | (select | | ) - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= Must match this Python Regular Expression: [a-zA-Z0-9 '"!-]{4,30} ::= diff --git a/docs/BNF-Syntax.md b/docs/BNF-Syntax.md index cfd47768..8c2bcf9b 100644 --- a/docs/BNF-Syntax.md +++ b/docs/BNF-Syntax.md @@ -1,4 +1,4 @@ -# Syntax +!# Syntax ## BNF Syntax This Wiki describes the GAM7 command line syntax in modified BNF. diff --git a/docs/Basic-Items.md b/docs/Basic-Items.md index 1d8cf534..e006fb5b 100644 --- a/docs/Basic-Items.md +++ b/docs/Basic-Items.md @@ -1,4 +1,4 @@ -# Basic Items +!# Basic Items - [Primitives](#primitives) - [Items built from primitives](#items-built-from-primitives) - [Named items](#named-items) diff --git a/docs/Bulk-Processing.md b/docs/Bulk-Processing.md index edadd4c5..c8ca553a 100644 --- a/docs/Bulk-Processing.md +++ b/docs/Bulk-Processing.md @@ -1,4 +1,4 @@ -# Bulk Processing +!# Bulk Processing - [Introduction](#introduction) - [Python Regular Expressions](Python-Regular-Expressions) - [GAM Configuration](gam.cfg) diff --git a/docs/CSV-Input-Filtering.md b/docs/CSV-Input-Filtering.md index 063db6f2..443e67e8 100644 --- a/docs/CSV-Input-Filtering.md +++ b/docs/CSV-Input-Filtering.md @@ -16,7 +16,7 @@ There are two values in `gam.cfg` that can be used to filter the input from `gam * `csv_input_row_drop_filter` - A list or JSON dictionary used to exclude specific rows based on column values These filters can be used alone or in conjunction with the `matchfield|skipfield ` options. -* https://github.com/taers232c/GAMADV-XTD3/wiki/Bulk-Processing#csv-files +* https://github.com/GAM-team/GAM/wiki/Bulk-Processing#csv-files ## Definitions [Data Selectors](Collections-of-items) diff --git a/docs/CSV-Output-Filtering.md b/docs/CSV-Output-Filtering.md index 4d0d24e2..8db97897 100644 --- a/docs/CSV-Output-Filtering.md +++ b/docs/CSV-Output-Filtering.md @@ -1,4 +1,4 @@ -# CSV Output Filtering +!# CSV Output Filtering - [Python Regular Expressions](Python-Regular-Expressions) Search function - [Definitions](#definitions) - [Quoting rules](#quoting-rules) diff --git a/docs/CSV-Special-Characters.md b/docs/CSV-Special-Characters.md index 72dc9c08..e46a225e 100644 --- a/docs/CSV-Special-Characters.md +++ b/docs/CSV-Special-Characters.md @@ -1,4 +1,4 @@ -# CSV Special Characters +!# CSV Special Characters - [Python CSV documentation](https://docs.python.org/3/library/csv.html#dialects-and-formatting-parameters) ## Python variables that control CSV file reading/writing: diff --git a/docs/CalendarExamples.md b/docs/CalendarExamples.md new file mode 100644 index 00000000..069350f2 --- /dev/null +++ b/docs/CalendarExamples.md @@ -0,0 +1,260 @@ +- [Modifying and Viewing Calendar Access Control Lists (ACLs)](#modifying-and-viewing-calendar-access-control-lists-acls) + - [Viewing a Calender's ACL](#viewing-a-calenders-acl) + - [Adding Users to a Calendar's ACL](#adding-users-to-a-calendars-acl) + - [Updating a User Entry in a Calendar ACL](#updating-a-user-entry-in-a-calendar-acl) + - [Deleting Users from a Calendar's ACL](#deleting-users-from-a-calendars-acl) +- [Viewing and Modifying a User's List of Calendars](#viewing-and-modifying-a-users-list-of-calendars) + - [Retrieving a Calendar a User Has Listed](#retrieving-a-calendar-a-user-has-listed) + - [Showing the Calendars a User Has Listed](#showing-the-calendars-a-user-has-listed) + - [Printing the Calendars a User Has Listed](#printing-the-calendars-a-user-has-listed) + - [Deleting a Calendar from a User(s) List of Calendars](#deleting-a-calendar-from-a-users-list-of-calendars) + - [Adding a Calendar to a User(s) List of Calendars](#adding-a-calendar-to-a-users-list-of-calendars) + - [Updating a Calendar in a User(s) List of Calendars](#updating-a-calendar-in-a-users-list-of-calendars) +- [Deleting Events for a Calendar](#deleting-events-for-a-calendar) +- [Wiping a User's Primary Calendar](#wiping-a-users-primary-calendar) + +GAM now supports Google Calendar Management with the ability to modify Access Control Lists (ACLs) for calendars and to add, list and remove calendars from a users Google Calendar display. GAM can work with user primary and secondary calendars as well as resource calendars. + +All Google Calendars have an email address associated with them. All users who have the Calendar service enabled have a primary calendar identified by their email address. Secondary calendars created by or for the user have a special calendar email address which can be learned with the ` gam user show calendars ` command. Resource Calendars also have a special email address that can be learned with the ` gam print resources ` command. + +# Modifying and Viewing Calendar Access Control Lists (ACLs) +## Viewing a Calender's ACL +### Syntax +``` +gam calendar showacl|printacl +``` +Shows the ACLs for the given calendar (showacl) or prints CSV output of the ACLs (printacl). The ACL list will show who has access to the calendar and what level of access they have. + +### Example +This example displays the Calendar ACLs for joe@acme.com +``` +gam calendar joe@acme.com showacl +``` + +--- + + +## Adding Users to a Calendar's ACL +### Syntax +``` +gam calendar add freebusy|read|editor|owner [sendnotifications true|false] +``` +Gives user email the desired level of access to the given calendar by adding the user to the ACL. freebusy allows the user to see only times whe n the calendar is busy without showing event details. read gives the user rights to view but not edit the calendar. editor gives read/write access to the calendar but not ACL or settings modification rights. owner gives the user full access to the calendar with the ability to modify the ACL and calendar settings. + +Use the optional sendnotifications flag to choose whether to send notifications about the calendar sharing change or not. The default is True. + +**Note:** The special users domain and default cannot be added to a calendar, they can only be updated or deleted by GAM (see below) + +**Note:** giving a user rights to another calendar adds that calendar to their list of calendars automatically. A separate command to add the calendar should not be necessary. *Update*: this no longer seems to happen as of early 2020. You'll need to add the calendar to the user's list of calendar's separately. + +### Example +This example gives Bob editor access to Joe's primary calendar. +``` +gam calendar joe@acme.com add editor bob@acme.com +``` + +--- + + +## Updating a User Entry in a Calendar ACL +### Syntax +``` +gam calendar update freebusy|read|editor|owner +``` +Update the given user's rights to the given calendar. The user should already have explicit access to the calendar. This command will upgrade (or downgrade) the user's access to the desired level of freebusy, read, editor or owner. + +**Note:** the special users domain and default can be used instead of an actual user email address to modify public sharing of the calendar. domain applies to all users in the Google Apps organization. default applies to anyone with a Google account (even @gmail.com) and is limited to read or freebusy. Note that your Calendar control panel settings may prevent read sharing of calendars outside the domain in which case you'll get an error trying to set default to read. + +### Example +This example upgrades Bob to be owner of Joe's Calendar: +``` +gam calendar joe@acme.com update owner bob@acme.com +``` + +This example allows anyone with an account in your domain to edit the given resource calendar (including delete others appointments!). + +``` +gam calendar example.com_436d6e646572656e6365526f6f6d732d3239352d3372642d5164616d536d6974682d38@resource.calendar.google.com update editor domain +``` + +This example allows anyone with a Google account to view Bob's calendar +``` +gam calendar bob@example.com update read default +``` + +--- + + +## Deleting Users from a Calendar's ACL +### Syntax +``` +gam calendar delete [user ] [id ] +``` +Removes user email rights to the given calendar. Note that the user may still have some level of rights (freebusy or read) to the calendar based on the default level of access to calendars set within the domain. Specifying the ACL by ID is also supported and takes the id column of the [printacl command](#viewing-a-calenders-acl) + +**Note:** deleting the domain and default users disables public sharing of your calendar. domain applies to everyone in your Google Apps domain while default applies to everyone with a Google Account. + +### Example +This example removes Bob's direct rights to Joe's calendar +``` +gam calendar joe@acme.com delete user bob@acme.com +``` + +These two examples remove all public sharing of Bob's calendar. Only those with explicit rights will be able to see anything (including freebusy): + +``` +gam calendar bob@example.com delete user domain +gam calendar bob@example.com delete user default +``` + +--- + + +# Viewing and Modifying a User's List of Calendars +## Retrieving a Calendar a User Has Listed +### Syntax +``` +gam user |group |ou |all users info calendar +``` +Displays the details of the users' specific Calendar. + +### Example +This example displays a specific calendar that Bob has added to his Google Calendar app +``` +gam user bob@acme.com info calendar acme.com_r7vmefng3okeo4l48n4urkjvcg@group.calendar.google.com + +User: bob@acme.com's Calendar: + Calendar: test + ID: acme.com_r7vmefng3okeo4l48n4urkjvcg@group.calendar.google.com + Access Level: root + Timezone: America/New_York + Hidden: false + Selected: true + Color: #2952A3 +``` + +## Showing the Calendars a User Has Listed +### Syntax +``` +gam user |group |ou |all users show calendars +``` +Displays the details of all of the Calendars the user has listed in their Google Calendar. + +### Example +This example lists the calendars that Bob has added to his Google Calendar app +``` +gam user bob@acme.com show calendars + +User: bob@acme.com's Calendars + Calendar: bob@acme.com + ID: bob@acme.com + Access Level: owner + Timezone: America/New_York + Hidden: false + Selected: false + Color: #2F6309 + Calendar: test + ID: acme.com_r7vmefng3okeo4l48n4urkjvcg@group.calendar.google.com + Access Level: root + Timezone: America/New_York + Hidden: false + Selected: true + Color: #2952A3 + Calendar: Canadian Holidays + ID: en.canadian#holiday@group.v.calendar.google.com + Access Level: read + Timezone: America/New_York + Hidden: false + Selected: true + Color: #2952A3 +``` + +## Printing the Calendars a User Has Listed +### Syntax +``` +gam user |group |ou |all users print calendars [todrive] +``` +Display or upload to Google Drive a CSV report of all of the users' calendars. The optional `todrive` parameter specifies that the results should be uploaded to Google Drive rather than being displayed on screen or piped to a CSV text file. + +### Example +This example lists the calendars that all users have specified in the Calendar app. +``` +gam all users print calendars +``` + +--- + + +## Deleting a Calendar from a User(s) List of Calendars +### Syntax +``` +gam user |group |ou |all users delete calendar +``` +Removes the given calendar from each of the users' list of calendars. Deleting a calendar from a user's calendar list does not change ACLs on the calendar, it simply removes it from the display. + +### Example +This example removes Joe's calendar from Bob's display of calendars. +``` +gam user bob@acme.com delete calendar joe@acme.com +``` + +--- + + +## Adding a Calendar to a User(s) List of Calendars +### Syntax +``` +gam user |group |ou |all users add calendar [selected true|false] [hidden true|false] [reminder email|sms|popup ] [notification email|sms eventcreation|eventchange|eventcancellation|eventresponse|agenda] [summary ] [colorindex <1-24>] [backgroundcolor ] [foregroundcolor ] +``` +Adds the given calendar to each of the users' list of calendars. Adding a calendar to a user's calendar list does not give them any rights to the calendar that they didn't have before. If the user does not have rights to the calendar, use the ACL command above to both grant them rights and add the calendar to their list of calendars. + +The optional argument `selected` determines if the calendar is selected in the user's list of subscribed calendars by default. The optional argument `hidden` determines if the calendar is hidden from the user's list of subscribed calendars. The optional argument `reminder` sets the default reminder type and time for calendar events and can be repeated. The optional argument `notification` sets the default notification type for calendar events and can be repeated. The optional argument `summary` overrides the calendar's default name. The optional argument `colorindex` sets the calendar entries colors. Index colors can be viewed [here](http://calendar-colors.appspot.com/). The optional arguments `backgroundcolor` and `foregroundcolor` manually set the calendars colors. + +### Example +The following example adds Bob's calendar to Joe's list of calendars without it being selected in Joe's calendar display. + +``` +gam user joe@acme.com add calendar bob@acme.com selected false +``` + +--- + + +## Updating a Calendar in a User(s) List of Calendars +### Syntax +``` +gam user |group |ou |all users update calendar [selected true|false] [hidden true|false] [reminder (email|sms|popup )|clear] [notification (email|sms eventcreation|eventchange|eventcancellation|eventresponse|agenda)|clear] [summary ] [colorindex <1-24>] [backgroundcolor ] [foregroundcolor ] +``` +Update how a given calendar is displayed in a user's list of calendars. The optional argument `selected` determines if the calendar is selected in the user's list of subscribed calendars by default. The optional argument `hidden` determines if the calendar is hidden from the user's list of subscribed calendars. The optional argument `reminder` sets the default reminder type and time for calendar events and can be repeated. The argument `reminder clear` clears all reminders from the calendar. The optional argument `notification` sets the default notification type for calendar events and can be repeated. The argument `notification clear` clears all notifications from the calendar. The optional argument `summary` overrides the calendar's default name. The optional argument `colorindex` sets the calendar entries colors. Index colors can be viewed [here](http://calendar-colors.appspot.com/). The optional arguments `backgroundcolor` and `foregroundcolor` manually set the calendars colors. + +### Example +The following example updates Bob's view of Joe's calendars, changing the color to green. + +``` +gam user bob@acme.com update calendar joe@acme.com colorindex 9 +``` + +--- + +# Deleting Events for a Calendar +### Syntax +``` +gam calendar deleteevent [eventid ] [query ] [notifyattendees] [doit] +``` +Delete event(s) off the given calendar. You should specify either the single event ID with the eventid argument or a query to perform against the calendar to determine which events should be deleted. Query operates in a similar fashion to Calendar UIs search but you should test results carefully, a bad query can delete more events than you intended. The optional argument notifyattendees will send event attendees an email notification that the event is cancelled, removed. Because this command involves deletion of user data, GAM will not perform the action by default unless the doit argument is supplied. + +# Wiping a User's Primary Calendar +### Syntax +``` +gam calendar wipe +``` +Wipe all data from a user's primary calendar. **WARNING: This will delete all user events and there is no way to recover them!** Email address must be a Google Apps user. It's not possible to wipe resource or secondary calendars. + +### Example +The following example deletes all data for Joe's Calendar. + +``` +gam calendar joe@acme.com wipe +``` + +--- \ No newline at end of file diff --git a/docs/Calendars-Access.md b/docs/Calendars-Access.md index a74b2a39..1b94e738 100644 --- a/docs/Calendars-Access.md +++ b/docs/Calendars-Access.md @@ -28,7 +28,7 @@ Calendar ACL roles (as seen in Calendar GUI): ::= ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= editor|freebusy|freebusyreader|owner|reader|writer ::= |user:|group:|domain:|domain|default diff --git a/docs/Calendars-Events.md b/docs/Calendars-Events.md index c02d8eff..c492f7cb 100644 --- a/docs/Calendars-Events.md +++ b/docs/Calendars-Events.md @@ -63,12 +63,12 @@ Client access works when accessing Resource calendars. ::= ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= (.)+ ::= @ ::= "(,)*" ::= | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= attachments.fileid| @@ -220,7 +220,7 @@ Client access works when accessing Resource calendars. (id|eventid ) | (event|events | | | | | ) - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= (+ *) diff --git a/docs/Calendars.md b/docs/Calendars.md index a029c7eb..e3008235 100644 --- a/docs/Calendars.md +++ b/docs/Calendars.md @@ -21,7 +21,7 @@ Client access works when accessing Resource calendars. ::= ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= See: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones diff --git a/docs/Chat-Bot.md b/docs/Chat-Bot.md index e6fbb94e..a5ec1baa 100644 --- a/docs/Chat-Bot.md +++ b/docs/Chat-Bot.md @@ -1,4 +1,4 @@ -# Chat Bot +!# Chat Bot - [Notes](#notes) - [API documentation](#api-documentation) diff --git a/docs/Chrome-AUE-Counts.md b/docs/Chrome-AUE-Counts.md index 216b3375..d11e96cb 100644 --- a/docs/Chrome-AUE-Counts.md +++ b/docs/Chrome-AUE-Counts.md @@ -1,4 +1,4 @@ -# Chrome Auto Update Expiration Counts +!# Chrome Auto Update Expiration Counts - [Chrome Auto Update Expiration Counts](#chrome-auto-update-expiration-counts) - [API documentation](#api-documentation) diff --git a/docs/Chrome-Browser-Cloud-Management.md b/docs/Chrome-Browser-Cloud-Management.md index 77c5de10..b4edf077 100644 --- a/docs/Chrome-Browser-Cloud-Management.md +++ b/docs/Chrome-Browser-Cloud-Management.md @@ -41,7 +41,7 @@ (query:)|(query:orgunitpath:)|(query ) | (browserou ) | (browserous ) | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= (annotatedassetid|asset|assetid )| diff --git a/docs/Chrome-Browser-Management.md b/docs/Chrome-Browser-Management.md new file mode 100644 index 00000000..a235039e --- /dev/null +++ b/docs/Chrome-Browser-Management.md @@ -0,0 +1,85 @@ +- [Printing browsers](#printing-browsers) +- [Moving browsers](#moving-browsers) +- [Updating browsers](#updating-browsers) +- [Get info about a browser](#get-info-about-a-browser) +- [Delete a browser](#delete-a-browser) + +GAM 5.30 adds support for the new [Chrome Browser Cloud Management API calls](https://support.google.com/chrome/a/answer/9681204). The API allows you to print, move, update and delete enrolled browsers. + +# Printing browsers +## Syntax +``` +gam print browsers [query ] [projection BASIC|FULL] [todrive] [sort_headers] [fields ] +``` +Prints enrolled browsers. The optional argument query will limit results to matching browsers. Query format is described [in Google's help articles](https://support.google.com/chrome/a/answer/9681204#example:~:text=You%20can%20specify%20the%20following%20fields,the%20field%20names%20are%20case%20sensitive). By default, GAM only prints basic information about the browsers. The optional argument projection allows selecting FULL which prints a lot more information about each browser including user profiles, policies and extension details. The optional argument todrive will upload the output to a Google Sheet. The optional argument fields specifies a comma separated list of fields you'd like to limit results to. + +## Example +This example prints all browsers. +``` +gam print browsers +``` +This example creates a Google Sheet of browsers running on Microsoft Windows +``` +gam print browsers todrive query "os_platform:Windows" +``` +---- +## Moving browsers +### Syntax +``` +gam move browsers [ids ] [query ] [file ] [csvfile ] [orgunit ] [batch_size ] +``` +Moves the specified browsers from one OrgUnit in Google to another. The browsers must be specified with the ids, query, file or csvfile argument. The orgunit argument specifies the destination of the browsers. By default, GAM will attempt to move 600 browsers at a time which is the max allowed by the API. You can modify this number by specifying batch_size. + +### Example +This example moves all Windows browsers into their own Org Unit. +``` +gam move browsers query "os_platform:Windows" orgunit /Chrome/Windows +``` +---- +## Updating browsers +### Syntax +``` +gam update browser [user ] [location ] [notes ] [assetid ] +``` +Updates information about a Chrome browser. Information can be set for the user, location, notes and assetid fields. + +### Example +This example updates all four fields +``` +gam update browser c052d4d7-90b1-407a-911f-c0d05ba0eaeb user jsmith@acme.com location "New York, NY" notes "Browser re-installed on 12/3/20" assetid ABC123 +``` +---- +## Get info about a browser +### Syntax +``` +gam info browser [FULL|BASIC] [fields ] +``` +shows information about a single browser based on the id specified. The optional argument projection retrieves a basic or full list of device attributes. Full includes details like browser profiles, policies and extensions. The optional fields parameter limits which fields are retrieved and printed. + +### Example +This example gets info about a browser +``` +gam info browser c052d4d7-90b1-407a-911f-c0d05ba0eaeb +``` +This example shows a LOT of information about the browser +``` +gam info browser c052d4d7-90b1-407a-911f-c0d05ba0eaeb projection FULL +``` +This example shows a limited amount of information +``` +gam info browser c7cf1d21-50af-4419-bf75-67731423a259 fields osPlatform,lastPolicyFetchTime,osPlatformVersion,lastDeviceUser,orgUnitPath +``` +---- +## Delete a browser +### Syntax +``` +gam delete browser +``` +Deletes the given browser by id. The browser will be removed from Google's admin console and no longer sync policy or reporting. However existing policies will still be applied until the device registration and dm tokens are removed. + +### Example +This example deletes the device. +``` +gam delete browser c7cf1d21-50af-4419-bf75-67731423a259 +``` +---- diff --git a/docs/Chrome-Installed-Apps.md b/docs/Chrome-Installed-Apps.md index dfd9f1a8..f991ffb1 100644 --- a/docs/Chrome-Installed-Apps.md +++ b/docs/Chrome-Installed-Apps.md @@ -1,4 +1,4 @@ -# Chrome Installed Apps Counts +!# Chrome Installed Apps Counts - [API documentation](#api-documentation) - [Definitions](#definitions) diff --git a/docs/Chrome-Needs-Attention-Counts.md b/docs/Chrome-Needs-Attention-Counts.md index 86eb76d7..9a70fa1b 100644 --- a/docs/Chrome-Needs-Attention-Counts.md +++ b/docs/Chrome-Needs-Attention-Counts.md @@ -1,4 +1,4 @@ -# Chrome Device Needs Attention Counts +!# Chrome Device Needs Attention Counts - [Chrome Device Needs Attention Counts](#chrome-device-needs-attention-counts) - [API documentation](#api-documentation) diff --git a/docs/Chrome-Policies.md b/docs/Chrome-Policies.md index b62511c7..8dcca755 100644 --- a/docs/Chrome-Policies.md +++ b/docs/Chrome-Policies.md @@ -1,4 +1,4 @@ -# Chrome Policies +!# Chrome Policies - [Chrome Policies](#chrome-policies) - [Chrome Version History](Chrome-Version-History) diff --git a/docs/Chrome-Policy-Settings.md b/docs/Chrome-Policy-Settings.md new file mode 100644 index 00000000..58978e49 --- /dev/null +++ b/docs/Chrome-Policy-Settings.md @@ -0,0 +1,79 @@ +- [Showing Chrome Schema of Policy Settings](#showing-chrome-schema-of-policy-settings) +- [Showing Current Chrome Policy For An OrgUnit](#showing-current-chrome-policy-for-an-orgunit) +- [Updating Chrome Policy](#updating-chrome-policy) +- [Clearing Chrome Policies](#clearing-chrome-policies) + +## Showing Chrome Schema of Policy Settings +### Syntax +``` +gam show chromeschema [filter ] +``` +Shows the schema of all possible Chrome policy settings available for your organization. The optional filter argument filters results down to matches. The schema is comprised of the top level schema name which groups the policy settings together, an individual setting, the type of the setting (string, boolean, enum) and possible values for the setting with their description. + +### Example +This example prints the full schema for your organization. A truncated example output is also shown with the parts of the schema. In the example output, the schema name is chrome.users.ChromeBrowserUpdates and controls how browsers update. Within this schema there are three settings, rollbackToTargetVersionEnabled, targetVersionPrefixSetting and updateSetting. rollbackToTargetVersionEnabled and updateSetting are TYPE_ENUM meaning there is a limited set of values they can be set to. These values are described in the lines just after the setting. targetVersionPrefixSetting is TYPE_STRING so it accepts a string value as mentioned in it's description. +``` +gam show chromeschema +... +chrome.users.ChromeBrowserUpdates: Chrome browser updates. + rollbackToTargetVersionEnabled: TYPE_ENUM + ROLLBACK_TO_TARGET_VERSION_DISABLED: Do not rollback to target version. + ROLLBACK_TO_TARGET_VERSION_ENABLED: Rollback to target version. + targetVersionPrefixSetting: TYPE_STRING + Target version prefix. Specifies which version the Chrome browser should be updated to. When a value is set, Chrome will be updated to the version prefixed with this value. For example, if the value is '55.', Chrome will be updated to any minor version of 55 (e.g. 55.24.34.0 or 55.60.2.10). If the value is '55.2.', Chrome will be updated to any minor version of 55.2 (e.g. 55.2.34.100 or 55.2.2.1). If the value is '55.24.34.1', Chrome will be updated to that specific version only. Chrome may stop updating or not rollback if the specified version is more than three major milestones old. + updateSetting: TYPE_ENUM + UPDATES_DISABLED: Updates disabled. + UPDATES_ENABLED: Always allow updates. + MANUAL_UPDATES_ONLY: Manual updates only. + AUTOMATIC_UPDATES_ONLY: Automatic updates only. +... +``` +---- + +## Showing Current Chrome Policy For An OrgUnit +### Syntax +``` +gam show chromepolicy orgunit [printer_id ] [app_id ] +``` +Shows the current Chrome policies for the given OrgUnit. The optional argument printer_id will scope the returned policies to those set on the given printer. The optional argument app_id will scope the returned policies to those set on the given app. + +### Example +This example prints policies for the root OrgUnit. +``` +gam show chromepolicy orgunit / +``` +This example shows policies for the identified printer. +``` +gam show chromepolicy orgunit / printer_id 0gjdgxs3dgp3kj +``` +---- + +## Updating Chrome Policy +### Syntax +``` +gam update chromepolicy [orgunit ] [printer_Id ] [app_id ] schema1 setting1 value setting2 value schema2 setting1 value ... +``` +Updates the policy settings of the given OrgUnit. The optional printer_id and app_id specify a printer or app to set policy for. Policies involve a schema name, the specific setting of the schema and a value. You can set multiple schemas and settings with one command but they must all apply to the same OrgUnit / printer / app. + +### Example +This example sets Chrome to limit updates to version 89 for the /Browsers OrgUnit. Browsers on newer versions will be rolled back. +``` +gam update chromepolicy orgunit /Browsers chrome.users.ChromeBrowserUpdates rollbackToTargetVersionEnabled ROLLBACK_TO_TARGET_VERSION_ENABLED targetVersionPrefixSetting "89." updateSetting UPDATES_ENABLED +``` +This example blocks notifications except for specific URLs +``` +gam update chromepolicy orgunit /Browsers chrome.users.Notifications defaultNotificationsSetting BLOCK_NOTIFICATIONS notificationsAllowedForUrls *.google.com,*.salesforce.com,*.youtube.com +``` + +## Clearing Chrome Policies +### Syntax +``` +gam delete policy [orgunit ] [printer_id ] [app_id ] schema1 schema2 schema3 ... +``` +Clears the settings for the given schema so that they inherit from their parent OrgUnit or, in the case of the / root OrgUnit, inherit from the Google default setting. The optional printer_id and app_id specify a specific printer or app to clear the policies for. Multiple schemas can be cleared by specifying each one separated by spaces but the policies must all apply to the given OrgUnit / printer / app combo. + +### Example +This example clears the Chrome update and notification policies for the /Browsers OrgUnit. They will then inherit either from the / root OrgUnit if set there or from the Google default setting. +``` +gam delete chromepolicy orgunit /Browsers chrome.users.Notifications chrome.users.ChromeBrowserUpdates +``` \ No newline at end of file diff --git a/docs/Chrome-Printers.md b/docs/Chrome-Printers.md index 16da2eba..ae650c4d 100644 --- a/docs/Chrome-Printers.md +++ b/docs/Chrome-Printers.md @@ -1,4 +1,4 @@ -# Chrome Printers +!# Chrome Printers - [API documentation](#api-documentation) - [Notes](#notes) - [Definitions](#definitions) diff --git a/docs/Chrome-Version-Counts.md b/docs/Chrome-Version-Counts.md index 3564ef9a..4cbaac93 100644 --- a/docs/Chrome-Version-Counts.md +++ b/docs/Chrome-Version-Counts.md @@ -1,4 +1,4 @@ -# Chrome Version Counts +!# Chrome Version Counts - [Chrome Version Counts](#chrome-version-counts) - [API documentation](#api-documentation) diff --git a/docs/Chrome-Version-History.md b/docs/Chrome-Version-History.md index 1afe4509..6865bdc2 100644 --- a/docs/Chrome-Version-History.md +++ b/docs/Chrome-Version-History.md @@ -1,4 +1,4 @@ -# Chrome Version History +!# Chrome Version History - [Chrome Version History](#chrome-version-history) - [API documentation](#api-documentation) diff --git a/docs/ChromeOS-Devices.md b/docs/ChromeOS-Devices.md index 0b42a893..b70cac85 100644 --- a/docs/ChromeOS-Devices.md +++ b/docs/ChromeOS-Devices.md @@ -86,7 +86,7 @@ The second form is backwards compatible with Legacy GAM and selection with ` ::= "(,)*" ::= | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= | (cros_sn ) | diff --git a/docs/Classroom-Courses.md b/docs/Classroom-Courses.md index 5e68f953..aee8b64a 100644 --- a/docs/Classroom-Courses.md +++ b/docs/Classroom-Courses.md @@ -48,50 +48,50 @@ gam user user@domain.com check|update serviceaccount ::= "(,)*" ::= |||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= ::= "(,)*" ::= ||||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= draft|published|deleted ::= all|"(,)*" ::= |d: ::= "(,)*" ::= ||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= ::= "(,)*" ::= draft|published|deleted ::= all|"(,)*" ::= | | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= active|archived|provisioned|declined|suspended ::= all|"(,)*" ::= ::= "(,)*" ::= ||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= new|created|turned_in|returned|reclaimed_by_student ::= all|"(,)*" ::= ::= "(,)*" ::= | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= ::= "(,)*" ::= ||||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= ::= "(,)*" ::= ||||| - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= draft|published|deleted ::= all|"(,)*" diff --git a/docs/Classroom-Guardians.md b/docs/Classroom-Guardians.md index 56566234..2b36b3d4 100644 --- a/docs/Classroom-Guardians.md +++ b/docs/Classroom-Guardians.md @@ -22,13 +22,13 @@ ::= "(,)*" ::= | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= || ::= ::= "(,)*" ::= | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= complete|pending ::= "(,)*" ``` diff --git a/docs/Classroom-Invitations.md b/docs/Classroom-Invitations.md index 0365bbed..d752f708 100644 --- a/docs/Classroom-Invitations.md +++ b/docs/Classroom-Invitations.md @@ -34,13 +34,13 @@ Follow the directions to authorize the Service Account scopes. ::= "(,)*" ::= | | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= ::= |d: ::= "(,)*" ::= | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= active|archived|provisioned|declined|suspended ::= all|"(,)*" ``` diff --git a/docs/Classroom-Membership.md b/docs/Classroom-Membership.md index e999f081..45df514f 100644 --- a/docs/Classroom-Membership.md +++ b/docs/Classroom-Membership.md @@ -25,7 +25,7 @@ ::= "(,)*" ::= | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= active|archived|provisioned|declined|suspended ::= all|"(,)*" ``` diff --git a/docs/Cloud-Channel.md b/docs/Cloud-Channel.md index 3988fb0c..73b10e44 100644 --- a/docs/Cloud-Channel.md +++ b/docs/Cloud-Channel.md @@ -1,4 +1,4 @@ -# Cloud Channel +!# Cloud Channel - [API documentation](#api-documentation) - [Notes](#notes) - [Definitions](#definitions) diff --git a/docs/Cloud-Identity-Devices.md b/docs/Cloud-Identity-Devices.md index e68da9ed..fc312f08 100644 --- a/docs/Cloud-Identity-Devices.md +++ b/docs/Cloud-Identity-Devices.md @@ -1,4 +1,4 @@ -# Cloud Identity Devices +!# Cloud Identity Devices - [API documentation](#api-documentation) - [Query documentation](#query-documentation) - [Definitions](#definitions) diff --git a/docs/Cloud-Identity-Groups-Membership.md b/docs/Cloud-Identity-Groups-Membership.md index 96dcfced..7fc1b1b3 100644 --- a/docs/Cloud-Identity-Groups-Membership.md +++ b/docs/Cloud-Identity-Groups-Membership.md @@ -63,7 +63,7 @@ and Cloud Identity Premium accounts. Unfortunately, even if you have the require ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= owner|manager|member ::= "(,)*" ::= customer|group|other|serviceaccount|user @@ -227,7 +227,7 @@ If `actioncsv` is specified, a CSV file with columns `group,email,role,action,me that shows the actions performed when updating the group. ### Examples using CSV file and Google sheets: -* https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Users#examples-using-csv-files-and-google-sheets-to-update-the-membership-of-a-group +* https://github.com/GAM-team/GAM/wiki/Collections-of-Users#examples-using-csv-files-and-google-sheets-to-update-the-membership-of-a-group ### Example Assume that at your school there is a group for each grade level and the members come from an OU; here is a sample CSV file GradeOU.csv diff --git a/docs/Cloud-Identity-Groups.md b/docs/Cloud-Identity-Groups.md index 63937a7d..3d63e21a 100644 --- a/docs/Cloud-Identity-Groups.md +++ b/docs/Cloud-Identity-Groups.md @@ -60,7 +60,7 @@ and Cloud Identity Premium accounts. Unfortunately, even if you have the require ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= owner|manager|member ::= "(,)*" ::= customer|group|other|serviceaccount|user diff --git a/docs/Cloud-Storage.md b/docs/Cloud-Storage.md index 57cc5a3e..84172b44 100644 --- a/docs/Cloud-Storage.md +++ b/docs/Cloud-Storage.md @@ -1,4 +1,4 @@ -# Cloud Storage +!# Cloud Storage - [API documentation](#api-documentation) - [Notes](#notes) - [Definitions](#definitions) diff --git a/docs/Collections-of-ChromeOS-Devices.md b/docs/Collections-of-ChromeOS-Devices.md index 7cfad1b4..48aeb87a 100644 --- a/docs/Collections-of-ChromeOS-Devices.md +++ b/docs/Collections-of-ChromeOS-Devices.md @@ -1,4 +1,4 @@ -# Collections of ChromeOS Devices +!# Collections of ChromeOS Devices - [Python Regular Expressions](Python-Regular-Expressions) Match function - [Definitions](#definitions) - [Organization Unit Quoting](#organization-unit-quoting) diff --git a/docs/Collections-of-Items.md b/docs/Collections-of-Items.md index 6ba30f0b..771e91f7 100644 --- a/docs/Collections-of-Items.md +++ b/docs/Collections-of-Items.md @@ -1,4 +1,4 @@ -# Collections of Items +!# Collections of Items - [Python Regular Expressions](Python-Regular-Expressions) Match function - [Definitions](#definitions) - [ListSelector](#listselector) diff --git a/docs/Collections-of-Users.md b/docs/Collections-of-Users.md index 3963fd23..2d9eb7f0 100644 --- a/docs/Collections-of-Users.md +++ b/docs/Collections-of-Users.md @@ -1,4 +1,4 @@ -# Collections of Users +!# Collections of Users - [Python Regular Expressions](Python-Regular-Expressions) Match function - [Definitions](#definitions) - [List quoting rules](#list-quoting-rules) diff --git a/docs/Command-Data-From-Google-Docs-Sheets-Storage.md b/docs/Command-Data-From-Google-Docs-Sheets-Storage.md index d82cee7f..7f76f00d 100644 --- a/docs/Command-Data-From-Google-Docs-Sheets-Storage.md +++ b/docs/Command-Data-From-Google-Docs-Sheets-Storage.md @@ -1,4 +1,4 @@ -# Command data from Google Docs, Sheets and Cloud Storage +!# Command data from Google Docs, Sheets and Cloud Storage - [Introduction](#introduction) - [Definitions](#definitions) - [Read data from a Google Doc or Drive File](#read-data-from-a-google-doc-or-drive-file) diff --git a/docs/Command-Line-Parsing.md b/docs/Command-Line-Parsing.md index 335a6a71..65ed58eb 100644 --- a/docs/Command-Line-Parsing.md +++ b/docs/Command-Line-Parsing.md @@ -1,4 +1,4 @@ -# Command Line Parsing +!# Command Line Parsing - [Linux and MacOS](#linux-and-macos) - [Windows Command Prompt](#windows-command-prompt) - [Windows PowerShell](#windows-powershell) diff --git a/docs/Command-Logging-Progress.md b/docs/Command-Logging-Progress.md index c7b2314f..edafa93c 100644 --- a/docs/Command-Logging-Progress.md +++ b/docs/Command-Logging-Progress.md @@ -1,4 +1,4 @@ -# Command Logging and Progress +!# Command Logging and Progress - [Introduction](#introduction) - [GAM Configuration](gam.cfg) - [Command Logging](#command-logging) diff --git a/docs/Custom-Schemas.md b/docs/Custom-Schemas.md new file mode 100644 index 00000000..1f5732db --- /dev/null +++ b/docs/Custom-Schemas.md @@ -0,0 +1,71 @@ +- [Creating a Custom User Schema](#creating-a-custom-user-schema) +- [Updating a Custom User Schema](#updating-a-custom-user-schema) +- [Print All Custom User Schemas](#print-all-custom-user-schemas) +- [Show All Custom User Schemas](#show-all-custom-user-schemas) +- [Get One Custom User Schema](#get-one-custom-user-schema) +- [Deleting a Custom User Schema](#deleting-a-custom-user-schema) + +# Creating a Custom User Schema +## Syntax +``` +gam create schema + field type + [indexed] [restricted] [multivalued] + [range ] + endfield +``` +Create a new custom user schema. *schemaname* is the name of the schema to create. You can have up to 100 schemas in your Google Apps instance and each schema can have up to 100 fields defined. *fieldname* is the name of the field. *type* is required and specifies the type of the field. bool, double, email, int64, phone and string are the allowed types. The optional parameter *indexed* specifies that searching will be performed on this field. The optional parameter *restricted* specifies that only super administrators and the user can read the field value(s), other users will not have access. The optional parameter *multivalued* specifies that the field can contain multiple values per-user. The optional parameter *range* is required to permit range queries (greater than or less than) on number fields. The *endfield* parameter is necessary to end the given field. Once a schema is created, schema values can be set for users with [gam user create and update commands](https://github.com/jay0lee/GAM/wiki/GAM3DirectoryCommands#setting-custom-user-schema-fields-at-create-or-update). + +## Example +This example creates a StudentData schema with the fields id, grade and labels. The id field will be hidden from regular users (restricted) and indexed. The labels field will be multivalue. This example also shows how you would set this schema for an existing user. +``` +gam create schema StudentData + field id type string indexed restricted endfield + field grade type int64 endfield + field labels type string multivalued endfield + +gam update user tommy.jones + StudentData.id 839342028 + StudentData.grade 1 + StudentData.labels multivalue TRANSFER_STUDENT + StudentData.labels multivalue HONOR_ROLL +``` + +# Updating a Custom User Schema +## Syntax +``` +gam update schema + field type + [indexed] [restricted] [multivalue] + [range ] + endfield +``` +Update a custom user schema. Note that many schema update operations aren't possible in order to preserve existing user data. As a rule of thumb, schemas should be well thought out when first created as after-the-fact changes can prove challenging. schemaname is the name of the schema to create. You can have up to 100 schemas in your Google Apps instance and each schema can have up to 100 fields defined. fieldname is the name of the field. type is required and specifies the type of the field. bool, double, email, int64, phone and string are the allowed types. The optional parameter indexed specifies that searching will be performed on this field. The optional parameter restricted specifies that only super administrators and the user themself can read the field value(s), other users will not have access. The optional parameter multivalued specifies that the field can contain multiple values per-user. The endfield parameter is necessary to end the given field. Schema values can be set for users with [gam user create and update commands](https://github.com/jay0lee/GAM/wiki/GAM3DirectoryCommands#setting-custom-user-schema-fields-at-create-or-update). + +# Print All Custom User Schemas +## Syntax +``` +gam print schemas [todrive] +``` +Print all custom user schemas. Output displays all schema fields and attributes such as restricted, indexed, multivalue, etc. The optional `todrive` argument will upload the CSV data to a Google Docs Spreadsheet file in the Administrators Google Drive rather than displaying it locally. + +# Show All Custom User Schemas +## Syntax +``` +gam show schemas +``` +Display all custom user schemas in a formatted style. Output displays all schema fields and attributes such as restricted, indexed, multivalue, etc. + +# Get Info On One Custom User Schema +## Syntax +``` +gam info schema +``` +Get info about one custom user schema. Output displays the schemas fields and attributes such as restricted, indexed, multivalue, etc. Schema values can be set for users with [gam user create and update commands](https://github.com/jay0lee/GAM/wiki/GAM3DirectoryCommands#setting-custom-user-schema-fields-at-create-or-update). + +# Deleting a Custom User Schema +## Syntax +``` +gam delete schema +``` +Delete a custom user schema. Deleting the schema also removes user data for the given schema. \ No newline at end of file diff --git a/docs/Customer.md b/docs/Customer.md index 20283fa9..7938e585 100644 --- a/docs/Customer.md +++ b/docs/Customer.md @@ -1,4 +1,4 @@ -# Customer +!# Customer - [API documentation](#api-documentation) - [Definitions](#definitions) - [Update customer](#update-customer) diff --git a/docs/Data-Transfers.md b/docs/Data-Transfers.md new file mode 100644 index 00000000..e0a7f96b --- /dev/null +++ b/docs/Data-Transfers.md @@ -0,0 +1,75 @@ +- [Request a Data Transfer](#request-a-data-transfer) +- [Get Information About a Data Transfer](#get-information-about-a-data-transfer) +- [Print All Data Transfers](#print-all-data-transfers) +- [Print Information About Apps That Support Data Transfer](#print-information-about-apps-that-support-data-transfer) + +# Request a Data Transfer +## Syntax +``` +gam create datatransfer ( )* +``` +Creates a data transfer request. Old owner is the source user whose data will be transferred. App is the name of the application data to transfer. New owner is the target user that will receive the data. Depending on the app, optional parameters can be specified which determine the scope of data to be transferred. + +## Example +This example transfers all Drive files for oldguy@acme.com to newguy@acme.com +``` +gam create datatransfer oldguy@acme.com gdrive newguy@acme.com privacy_level shared,private +``` +This example transfers only Drive files shared by terminated@acme.com to manager@acme.com +``` +gam create datatransfer terminated@acme.com gdrive manager@acme.com privacy_level shared +``` +This example transfers Calendar entries from oldguy to newguy and releases calendar resources booked by oldguy. +``` +gam create datatransfer oldguy@acme.com calendar newguy@acme.com release_resources true +``` +--- + +# Get Information About a Data Transfer +## Syntax +``` +gam info datatransfer +``` +Get information about an existing data transfer including the status. + +## Example +This example shows the status of a given data transfer. +``` + +gam info datatransfer AKrEtIYIysvNvudwY69gEtJNb85tK87Py2SJl8uwq78BxSMMRgn46rWtuKPIxmkWehZ_YJguKbSs +Old Owner: sarah@acme.com +New Owner: announce@acme.com +Request Time: 2015-09-29T20:45:28.085Z +Application: Drive +Status: completed +Parameters: + PRIVACY_LEVEL: PRIVATE,SHARED +``` +--- +# Print All Data Transfers +## Syntax +``` +gam print datatransfers [oldowner ] [newowner ] [status ] [todrive] +``` +Prints a CSV of all data transfers. With no parameters, all transfers will be printed. The oldowner, newowner and status parameters limit the output to results which match. The todrive parameter causes GAM to generate a Google Spreadsheet of the results rather than outputting the CSV file to the console. + +## Example +This example prints all transfers +``` +gam print datatransfers +``` +This example prints all transfers that have failed to a Google Spreadsheet. +``` +gam print datatransfers status failed todrive +``` +--- + +# Print Information About Apps That Support Data Transfer +## Syntax +``` +gam print transferapps +``` + +Prints information about all apps which support data transfer. + +--- \ No newline at end of file diff --git a/docs/Domain-People-Contacts-Profiles.md b/docs/Domain-People-Contacts-Profiles.md index 380c1fff..8ed7b183 100644 --- a/docs/Domain-People-Contacts-Profiles.md +++ b/docs/Domain-People-Contacts-Profiles.md @@ -31,7 +31,7 @@ gam user user@domain.com check serviceaccount ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= contact|contacts| diff --git a/docs/Domain-SharedContacts-GAL.md b/docs/Domain-SharedContacts-GAL.md index 7e7425a2..81109418 100644 --- a/docs/Domain-SharedContacts-GAL.md +++ b/docs/Domain-SharedContacts-GAL.md @@ -55,7 +55,7 @@ ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= [query ] [emailmatchpattern [emailmatchtype work|home|other|]] @@ -208,7 +208,7 @@ You specify contacts by ID or by selection qualifiers. ::= "(,)*" ::= | | | - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ::= [query ] [emailmatchpattern [emailmatchtype work|home|other|]] diff --git a/docs/DomainVerification.md b/docs/DomainVerification.md new file mode 100644 index 00000000..73b580dd --- /dev/null +++ b/docs/DomainVerification.md @@ -0,0 +1,128 @@ +- [Getting Verification Codes For A Domain](#getting-verification-codes-for-a-domain) +- [Performing Domain Verification](#performing-domain-verification) +- [Getting info about existing successful domain verifications](#getting-info-about-existing-successful-domain-verifications) + +GAM 3.04 and later allows admins to generate the details for domain verification as well as attempt the actual verify and print out existing verifications. + +In order to use a domain with G Suite, all primary, secondary and alias domains must be verified. Once an admin verifies a domain, they will be able to add it and it's subdomains as secondary and alias domains in G Suite. + +It's important to understand that the verification codes are unique to each user. If admin A generates the verification codes and admin B attempts to verify those codes, it will fail. + +# Getting Verification Codes For A Domain +## Syntax +``` +gam create verify +``` +Displays the DNS and Web server verification codes that are needed in order to verify the given domain name. + +## Example +This example shows the DNS and Web codes that would need to be created in order for the admin to verify the example.com domain. +``` +gam create verify example.com + +TXT Record Name: example.com +TXT Record Value: google-site-verification=ORsLMhIHCe2TFX3jeSgRpUk4A4WfywZ9znTS +sjfWDbE + +CNAME Record Name: 3umntkhyge7x.example.com +CNAME Record Value: gv-so2ram4atzoczj.dv.googlehosted.com + +Saving web server verification file to: google38973a5e4d01f5ee.html +Verification File URL: http://example.com/google38973a5e4d01f5ee.html + +Meta URL: http://example.com/ +Meta HTML Header Data: +``` + +--- + + +# Performing Domain Verification +## Syntax +``` +gam update verify +``` +Attempt domain verification of the given domain using the given method (cname, txt or site). In order for verification to succeed, the domain's DNS or Web Server must have been updated to contain the correct record. + +## Example +This example attempts DNS TXT record verification of the example.com domain (and is expected to fail). +``` +gam update verify example.com txt + +ERROR: The necessary verification token could not be found on your site. +Method: DNS_TXT +Token: google-site-verification=ORsLMhIHCe2TFX3jeSgRpUk4A4WfywZ9znTSsjfWDbE + +DNS Record: $Id: example.com 1921 2013-10-21 04:00:39Z dknight $ +DNS Record: v=spf1 -all +``` + +This example attempts DNS TXT record verification of the jay.powerposters.org domain and succeeds. +``` +gam update verify jay.powerposters.org txt + +SUCCESS! +Verified: jay.powerposters.org +ID: dns%3A%2F%2Fjay.powerposters.org +Type: INET_DOMAIN +All Owners: + admin@jay.powerposters.org + +You can now add jay.powerposters.org or it's subdomains as secondary or domain aliases of the jay.powerposters.org G Suite Account. +``` + +--- + + +# Getting info about existing successful domain verifications +## Syntax +``` +gam info verify +``` +Prints out a list of the DNS domains that the given administrator has already successfully performed domain verification against. + +## Example +This example prints out all the existing domain verifications for admin@jay.powerposters.org. +``` +gam info verify + +Site: secondary.ditoapps.com +Type: INET_DOMAIN +Owners: + admin@jay.powerposters.org + +Site: sdomain.jay.powerposters.org +Type: INET_DOMAIN +Owners: + admin@jay.powerposters.org + +Site: jay.powerposters.org +Type: INET_DOMAIN +Owners: + admin@jay.powerposters.org + +Site: jaylee.powerposters.org +Type: INET_DOMAIN +Owners: + admin@jay.powerposters.org + +Site: http://sites.google.com/a/jay.powerposters.org/my-site/ +Type: SITE +Owners: + jay@jay.powerposters.org + admin@jay.powerposters.org + +Site: http://sites.google.com/a/jay.powerposters.org/my-site2/ +Type: SITE +Owners: + jay@jay.powerposters.org + admin@jay.powerposters.org + +Site: vtest.powerposters.org +Type: INET_DOMAIN +Owners: + admin@jay.powerposters.org +``` + +--- diff --git a/docs/Domains-Verification.md b/docs/Domains-Verification.md index 4989b4d8..443a653e 100644 --- a/docs/Domains-Verification.md +++ b/docs/Domains-Verification.md @@ -1,4 +1,4 @@ -# Domains - Verification +!# Domains - Verification - [API documentation](#api-documentation) - [Definitions](#definitions) - [Introduction](#introduction) diff --git a/docs/Domains.md b/docs/Domains.md index a0e42d08..4b81151d 100644 --- a/docs/Domains.md +++ b/docs/Domains.md @@ -1,4 +1,4 @@ -# Domains +!# Domains - [API documentation](#api-documentation) - [Definitions](#definitions) - [Create a domain](#create-a-domain) diff --git a/docs/Downloads-Installs-GAM7.md b/docs/Downloads-Installs-GAM7.md deleted file mode 100644 index 7c75f9ae..00000000 --- a/docs/Downloads-Installs-GAM7.md +++ /dev/null @@ -1,56 +0,0 @@ -# Downloads-Installs-GAM7 -You can download and install the current GAM7 release from the [GitHub Releases](https://github.com/GAM-team/GAM/releases/latest) page. -Choose one of the following: - -* Executable Archive, Automatic, Linux/Mac OS/Google Cloud Shell/Raspberry Pi/ChromeOS - - Start a terminal session and execute one of the following commands: - - New install, default path `$HOME/bin` - - `bash <(curl -s -S -L https://git.io/gam-install)` - - New install, specify a path - - `bash <(curl -s -S -L https://git.io/gam-install) -d ` - - Update to latest version, do not create project or authorizations, default path `$HOME/bin` - - `bash <(curl -s -S -L https://git.io/gam-install) -l` - - Update to latest version, do not create project or authorizations, specify a path - - `bash <(curl -s -S -L https://git.io/gam-install) -l -d ` - -By default, a folder, `gam7`, is created in the default or specified path and the files are downloaded into that folder. -Add the `-s` option to the end of the above commands to suppress creating the `gam7` folder; the files are downloaded directly into the default or specified path. - -* Executable Archive, Manual, Linux/Google Cloud Shell - - `gam-7.wx.yz-linux-x86_64-glibc2.35.tar.xz` - - `gam-7.wx.yz-linux-x86_64-glibc2.31.tar.xz` - - `gam-7.wx.yz-linux-x86_64-legacy.tar.xz` - - Download the archive, extract the contents into some directory. - - Start a terminal session. - -* Executable Archive, Manual, Raspberry Pi/ChromeOS ARM devices - - `gam-7.wx.yz-linux-aarch-glibc2.31.tar.xz` - - `gam-7.wx.yz-linux-aarch-legacy.tar.xz` - - Download the archive, extract the contents into some directory. - - Start a terminal session. - -* Executable Archive, Manual, Mac OS versions Big Sur, Monterey, Ventura - M1/M2 - - `gam-7.wx.yz-macos-aarch.tar.xz` - - Download the archive, extract the contents into some directory. - - Start a terminal session. - -* Executable Archive, Manual, Mac OS, versions Big Sur, Monterey, Ventura - Intel - - `gam-7.wx.yz-macos-x86_64.tar.xz` - - Download the archive, extract the contents into some directory. - - Start a terminal session. - -* Executable Archive, Manual, Windows 64 bit - - `gam-7.wx.yz-windows-x86_64.zip` - - Download the archive, extract the contents into some directory. - - Start a Command Prompt/PowerShell session. - -* Executable Installer, Manual, Windows 64 bit - - `gam-7.wx.yz-windows-x86_64.msi` - - Download the installer and run it. - - Start a Command Prompt/PowerShell session. - -* Source, all platforms - - `Source code(zip)` - - `Source code(tar.gz)` - - Download the archive, extract the contents into some directory. - - Start a terminal/Command Prompt/PowerShell session. diff --git a/docs/Downloads-Installs.md b/docs/Downloads-Installs.md index 3c2a0a64..fab77379 100644 --- a/docs/Downloads-Installs.md +++ b/docs/Downloads-Installs.md @@ -1,62 +1,54 @@ -# Downloads-Installs -You can download and install the current GAM7 release from the [GitHub Releases](https://github.com/taers232c/GAMADV-XTD3/releases) page. Choose one of the following: +!# Downloads-Installs-GAM7 +You can download and install the current GAM7 release from the [GitHub Releases](https://github.com/GAM-team/GAM/releases/latest) page. +Choose one of the following: * Executable Archive, Automatic, Linux/Mac OS/Google Cloud Shell/Raspberry Pi/ChromeOS - Start a terminal session and execute one of the following commands: - New install, default path `$HOME/bin` - - `bash <(curl -s -S -L https://raw.githubusercontent.com/taers232c/GAMADV-XTD3/master/src/gam-install.sh)` + - `bash <(curl -s -S -L https://git.io/gam-install)` - New install, specify a path - - `bash <(curl -s -S -L https://raw.githubusercontent.com/taers232c/GAMADV-XTD3/master/src/gam-install.sh) -d ` + - `bash <(curl -s -S -L https://git.io/gam-install) -d ` - Update to latest version, do not create project or authorizations, default path `$HOME/bin` - - `bash <(curl -s -S -L https://raw.githubusercontent.com/taers232c/GAMADV-XTD3/master/src/gam-install.sh) -l` + - `bash <(curl -s -S -L https://git.io/gam-install) -l` - Update to latest version, do not create project or authorizations, specify a path - - `bash <(curl -s -S -L https://raw.githubusercontent.com/taers232c/GAMADV-XTD3/master/src/gam-install.sh) -l -d ` + - `bash <(curl -s -S -L https://git.io/gam-install) -l -d ` -By default, a folder, `gamadv-xtd3`, is created in the default or specified path and the files are downloaded into that folder. -Add the `-s` option to the end of the above commands to suppress creating the `gamadv-xtd3` folder; the files are downloaded directly into the default or specified path. +By default, a folder, `gam7`, is created in the default or specified path and the files are downloaded into that folder. +Add the `-s` option to the end of the above commands to suppress creating the `gam7` folder; the files are downloaded directly into the default or specified path. * Executable Archive, Manual, Linux/Google Cloud Shell - - `gamadv-xtd3-6.wx.yz-linux-x86_64-glibc2.35.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-x86_64-glibc2.31.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-x86_64-glibc2.27.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-x86_64-glibc2.23.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-x86_64-glibc2.19.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-x86_64-legacy.tar.xz` + - `gam-7.wx.yz-linux-x86_64-glibc2.35.tar.xz` + - `gam-7.wx.yz-linux-x86_64-glibc2.31.tar.xz` + - `gam-7.wx.yz-linux-x86_64-legacy.tar.xz` - Download the archive, extract the contents into some directory. - Start a terminal session. * Executable Archive, Manual, Raspberry Pi/ChromeOS ARM devices - - `gamadv-xtd3-6.wx.yz-linux-arm64-glibc2.31.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-arm64-glibc2.27.tar.xz` - - `gamadv-xtd3-6.wx.yz-linux-arm64-glibc2.23.tar.xz` + - `gam-7.wx.yz-linux-aarch-glibc2.31.tar.xz` + - `gam-7.wx.yz-linux-aarch-legacy.tar.xz` - Download the archive, extract the contents into some directory. - Start a terminal session. * Executable Archive, Manual, Mac OS versions Big Sur, Monterey, Ventura - M1/M2 - - `gamadv-xtd3-6.wx.yz-macos-arm64.tar.xz` + - `gam-7.wx.yz-macos-aarch.tar.xz` - Download the archive, extract the contents into some directory. - Start a terminal session. * Executable Archive, Manual, Mac OS, versions Big Sur, Monterey, Ventura - Intel - - `gamadv-xtd3-6.wx.yz-macos-x86_64.tar.xz` + - `gam-7.wx.yz-macos-x86_64.tar.xz` - Download the archive, extract the contents into some directory. - Start a terminal session. * Executable Archive, Manual, Windows 64 bit - - `gamadv-xtd3-6.wx.yz-windows-x86_64.zip` + - `gam-7.wx.yz-windows-x86_64.zip` - Download the archive, extract the contents into some directory. - Start a Command Prompt/PowerShell session. * Executable Installer, Manual, Windows 64 bit - - `gamadv-xtd3-6.wx.yz-windows-x86_64.msi` + - `gam-7.wx.yz-windows-x86_64.msi` - Download the installer and run it. - Start a Command Prompt/PowerShell session. -* Winget - - `winget install taers232c.GAMADV-XTD3 --location C:\GAMADV-XTD3` - - Specify an alternate location if desired - - Start a Command Prompt/PowerShell session. - * Source, all platforms - `Source code(zip)` - `Source code(tar.gz)` diff --git a/docs/Drive-File-Selection.md b/docs/Drive-File-Selection.md index 69ca53b4..17812b3d 100644 --- a/docs/Drive-File-Selection.md +++ b/docs/Drive-File-Selection.md @@ -319,7 +319,7 @@ You can select a list of file IDs by referencing files that contain file IDs. ``` ::= | | | ) | ) - See: https://github.com/taers232c/GAMADV-XTD3/wiki/Collections-of-Items + See: https://github.com/GAM-team/GAM/wiki/Collections-of-Items ``` * [Collections of Items](Collections-of-Items) diff --git a/docs/Drive-Items.md b/docs/Drive-Items.md index 03aaca41..bf48b103 100644 --- a/docs/Drive-Items.md +++ b/docs/Drive-Items.md @@ -1,4 +1,4 @@ -# Drive Items +!# Drive Items - [Basic Items](Basic-Items) - [List Items](List-Items) ``` diff --git a/docs/Drive-REST-API-v3.md b/docs/Drive-REST-API-v3.md index 4b87873a..470ab8f3 100644 --- a/docs/Drive-REST-API-v3.md +++ b/docs/Drive-REST-API-v3.md @@ -1,4 +1,4 @@ -All Google Drive API calls have been converted from v2 to v3, see: https://developers.google.com/drive/v3/web/migration +!All Google Drive API calls have been converted from v2 to v3, see: https://developers.google.com/drive/v3/web/migration Many of the changes are internal to Gam and have no visible effect. Google has modified/renamed many field names and these will affect scripts that parse the output from `gam print/show drivesettings/drivefileacls/fileinfo/filelist/filerevisions`. Additionally, Google has dropped some fields and their values are no longer available. On input, Gam accepts both the old and new field names. A variable, `drive_v3_native_names` (default value is True), has been added to `gam.cfg` to control the field names on output: when True, the v3 native field names are used; when False, the v3 native field names are mapped to the v2 field names. diff --git a/docs/Email-Audit-Monitor.md b/docs/Email-Audit-Monitor.md index 709d3da3..a55d29dd 100644 --- a/docs/Email-Audit-Monitor.md +++ b/docs/Email-Audit-Monitor.md @@ -1,4 +1,4 @@ -# Email Audit Monitor +!# Email Audit Monitor - [API documentation](#api-documentation) - [Notes](#notes) - [Definitions](#definitions) diff --git a/docs/ExamplesAccountAuditing.md b/docs/ExamplesAccountAuditing.md new file mode 100644 index 00000000..4cf415c3 --- /dev/null +++ b/docs/ExamplesAccountAuditing.md @@ -0,0 +1,317 @@ +- [About Google Apps Audits](#about-google-apps-audits) +- [Audit Monitors](#audit-monitors) + - [Create a Audit Monitor](#create-a-audit-monitor) + - [List Audit Monitors](#list-audit-monitors) + - [Delete an Audit Monitor](#delete-an-audit-monitor) +- [Managing the GPG Key](#managing-the-gpg-key) + - [Updating the GPG Key on Google's Servers](#updating-the-gpg-key-on-googles-servers) +- [User Account Activity](#user-account-activity) + - [Request an Account's Activity](#request-an-accounts-activity) + - [Retrieving Current Status of Activity Request(s)](#retrieving-current-status-of-activity-requests) + - [Downloading the Results of a Completed Activity Request](#downloading-the-results-of-a-completed-activity-request) + - [Deleting a Completed Activity Request](#deleting-a-completed-activity-request) +- [User Mailbox Exports](#user-mailbox-exports) + - [Request an Export of a User's Mailbox](#request-an-export-of-a-users-mailbox) + - [Retrieving Current Status of Export(s)](#retrieving-current-status-of-exports) + - [Downloading the Results of a Completed Export Request](#downloading-the-results-of-a-completed-export-request) + - [Deleting a Completed Export Request](#deleting-a-completed-export-request) +- [Using GPG with Audits](#using-gpg-with-audits) + - [Creating/Uploading a GPG Key](#creatinguploading-a-gpg-key) + - [Downloading GPG](#downloading-gpg) + - [Windows Users](#windows-users) + - [Linux Users](#linux-users) + - [Mac Users](#mac-users) + - [Creating/Uploading the Key](#creatinguploading-the-key) + - [Uploading the GPG Key](#uploading-the-gpg-key) + - [Decrypting Downloaded Files with GPG](#decrypting-downloaded-files-with-gpg) + +# About Google Apps Audits +```diff +- Most of the Email Audit API's functionality has been replaced/improved upon +- by Google's Vault and email routing functionality. GAM 3.8+ no longer supports +- the email audit commands listed below. If you need to use these audit commands, +- use GAM 3.72 or older. No support is provided for these commands going forward. +``` + +# Audit Monitors +## Create a Audit Monitor +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit monitor create [begin ] [end ] [incoming_headers] + [outgoing_headers] [nochats] [nodrafts] [chat_headers] [draft_headers] +``` +create an audit monitor for the source user. All Mail to and from the source user will be forwarded to the destination user. By default, the audit will begin immediately and last for 30 days. Optional parameters begin and end can set the start and end times. Both parameters must be in the future with end being later than begin, the format is "YYYY-MM-DD hh:mm". Optional parameters, incoming\_headers and outgoing\_headers configure the audit to not send the given message's full email body but just the message headers. By default, the audit will also forward the source user's Chats and saved message Drafts. The optional parameters nochats and nodrafts disable forwarding of these type of messages. The optional parameters chat\_headers and draft\_headers tell the audit to only send the headers of the given messages instead of the full message body. + +Only one audit is possible per a source and destination user combo. Creating a new audit with the same source and destination of an existing audit will overwrite the settings of the current of the existing audit. + +### Example +This example configures an audit of the source user, forwarding full copies of all incoming, outgoing, chat and draft messages to the destination user. The audit will start immediately and terminate in 30 days time +``` +gam audit monitor create jsmith fthomas +``` + +This example will start the audit on the given date and end it on the given date. Only message headers of each type will be sent to fthomas +``` +gam audit monitor create jsmith fthomas begin "2010-07-15 12:00" end "2011-07-15 12:00" + incoming_headers outgoing_headers chat_headers draft_headers +``` + +This example will not capture drafts or chats +``` +gam audit monitor create jsmith fthomas nochats nodrafts +``` + +--- + + +## List Audit Monitors +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit monitor list +``` +shows the current audit monitors for the user source user. + +This example will list the current monitors for the user jsmith +``` +gam audit monitor list jsmith + +jsmith has the following monitors: + + Destination: fthomas + Begin: 2010-07-04 12:00 + End: 2010-08-05 12:00 + Monitor Incoming: HEADER_ONLY + Monitor Outgoing: HEADER_ONLY + Monitor Chats: NONE + Monitor Drafts: NONE +``` + +--- + + +## Delete an Audit Monitor +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit monitor delete +``` +delete the audit monitor for the given source user / destination user combo. + +This example deletes the monitor that is sending all jsmith's mail to fthomas +``` +gam audit monitor delete jsmith fthomas +``` + +--- + + +# Managing the GPG Key +## Updating the GPG Key on Google's Servers +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit uploadkey +``` +updates the public GPG key that Google's servers use to encrypt Audit Activity and Export files. The key should be provided on Standard Input. See [Using GPG with Audits](ExamplesAccountAuditing#using-gpg-with-audits) for more details on GPG keys. + +This example tells GPG to print the key on standard output and gam reads the key on standard input +``` +gpg --export --armor | gam audit uploadkey +``` + +--- + + +# User Account Activity +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +## Request an Account's Activity +``` +gam audit activity request +``` +request the account activity of the given user. Requests can take several hours/days to be completed by Google's servers. GAM will print out a request ID which can be used to monitor the progress of the request (see Retrieving Request Status below). Note that before requesting an account's activity, a GPG key should be uploaded to Google Servers. See [Using GPG with Audits](ExamplesAccountAuditing#Using_GPG_with_Audits) for more details on GPG keys. Failure to upload a key will result in the activity request always getting a status of ERROR. + +This example creates a request for the user's activity +``` +gam audit activity request jsmith +``` + +--- + + +## Retrieving Current Status of Activity Request(s) +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit activity status [user] [request_id] +``` +get the current status of existing account activity requests. Optionally, a user and request\_id can be specified to limit the retrieval to a single request. + +This example retrieves the status of all current activity requests +``` +gam audit activity status +``` + +--- + + +## Downloading the Results of a Completed Activity Request +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit activity download +``` +download the results of an activity request that has a status of COMPLETED. The required parameters user and request\_id specify which request to download. The GPG encrypted activity file will be saved to a file named with the format activity-username-request\_id-1.txt.gpg and should be decrypted with GPG. + +This example downloads the encrypted activity log of the COMPLETED request +``` +gam audit activity download jsmith 234342 +``` + +--- + + +## Deleting a Completed Activity Request +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit activity delete +``` +delete the completed activity request for the given user. User and Request ID are required parameters. + +This example deletes the completed activity request for the user +``` +gam audit activity delete jsmith 234342 +``` + +--- + + +# User Mailbox Exports +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +## Request an Export of a User's Mailbox +``` +gam audit export request [begin ] [end ] [search ] [headersonly] [includedeleted] +``` +request an export of all mail in a user's mailbox. Optional parameters begin and end date specify the range of messages that should be included in the export and should be of the format "YYYY-MM-DD hh:mm". By default, export begins at account creation and ends at the time of the export request. Optional parameter search, specifies a search query defining what messages should be included in the export. The query parameters are the same as those used in the Gmail interface and described [here](http://mail.google.com/support/bin/answer.py?hl=en&answer=7190). Optional parameter headersonly specifies that only the message headers should be included in the export instead of the full message body. Optional parameter includedeleted specifies that deleted messages should also be included in the export. + +Note that before requesting an export of an account, a GPG key should be uploaded to Google's Server. See [Using GPG with Audits](ExamplesAccountAuditing#Using_GPG_with_Audits) for more details on GPG keys. Failure to upload a key will result in the export request always getting a status of ERROR. + +This example requests an export of all of a user's mail including deleted messages +``` +gam audit export request jsmith includedeleted +``` + +This example requests an export of all of a user's mail for a 30 day range including deleted +``` +gam audit export request jsmith begin "2010-06-01 00:00" end "2010-07-01 00:00" includedeleted +``` + +This example requests an export of all of a user's mail that has the word secret in the message subject +``` +gam audit export request jsmith search "subject:secret" +``` + +--- + + +## Retrieving Current Status of Export(s) +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit export status [user] [request_id] +``` +retrieve the status of current export requests. If the optional parameters user and request\_id are specified, only the status of the one request will be retrieved, otherwise all current requests' status will be retrieved. + +This example shows the status of all current export requests +``` +gam audit export status +``` + +--- + + +## Downloading the Results of a Completed Export Request +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit export download +``` +download the encrypted results of a completed export request. The required parameters user and request\_id specify which request's results should be downloaded. The encrypted files are saved with file names of export-username-request\_id-file\_number.mbox.gpg. If a file already exists on the hard drive, GAM will not re-download that file. GAM does not verify that the existing local file is complete, only that it exists. Thus if a download is interrupted, delete the partially downloaded file and start the process again, GAM will then skip over the files that have finished downloading. After they have been downloaded, they can be decrypted with GPG and then viewed with a mail client like Thunderbird. + +This example downloads the completed export request for jsmith +``` +gam audit export download jsmith 344920 +``` + +--- + + +## Deleting a Completed Export Request +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +``` +gam audit export delete +``` +delete the completed export request. The required parameters user and request\_id specify which request to delete. + +This example deletes the export request for the given user +``` +gam audit export delete jsmith 344920 +``` + + +# Using GPG with Audits +## Creating/Uploading a GPG Key +**This command is deprecated and will not work in GAM 3.8+**. [Details](#about-google-apps-audits) +### Syntax +Google's Servers use GPG to encrypt files that you request via the Audit API for account activity and mailbox export. Before you can successfully request a user account activity log or mailbox export, you need to create a GPG and upload it to Google's Servers for their use. +### Downloading GPG +#### Windows Users +A Windows version of GPG can be downloaded [here](ftp://ftp.gnupg.org/gcrypt/binary/gnupg-w32cli-1.4.10b.exe). I suggest installing it to an easy to remember location like C:\GPG. + +#### Linux Users +GPG comes with many Linux distributions by default. Try opening a Terminal and typing: +``` +gpg --version +``` +if you get an error, visit your Linux Distributions website and search for instructions on installing GPG. + +#### Mac Users +You can download a version of GPG for Macs [here](https://gpgtools.org/). Download the GPG Suite and run the package installer. The GUI suite will open. You can quit it and continue as below or use the GUI to generate your key. + +### Creating/Uploading the Key +Run the command: +``` +gpg --gen-key --expert +``` +you will be prompted for the kind of key you want, choose "RSA and RSA (default)". + +Next you'll be prompted for the keysize. This determines how strong the encryption is. If you're not paranoid about security, I suggest choosing a smaller key size as bigger keys will take longer to encrypt/decrypt your data thus greatly slowing down the process (especially for large exports), 1024 should be fine in most cases. + +Next you'll be prompted for how long the key should be valid. Specify 0 so that the key does not expire. + +Next you'll be prompted for your name, email address and a comment. Remember the name you enter, you'll need it for the next step. Google doesn't really use this information so feel free to make something up if you want. + +Finally, you'll be prompted for a passphrase, you'll need this passphrase in order to decrypt activity logs and exports so make sure you remember what it is! + +### Uploading the GPG Key +You can now upload your key to Google's Servers with the command: +``` +gpg --export --armor -a "Your Name" | \path\to\gam\gam audit uploadkey +``` +where "Your Name" is the name you entered for yourself in the last GPG command. This will output the GPG key and "pipe" it into GAM, telling GAM to upload the key to Google. + +## Decrypting Downloaded Files with GPG +Once you've submitted requests, the requests complete and you download requests, you can decrypt the data with GPG. The command to decrypt is: +``` +gpg --output --decrypt +``` +encrypted file is one of the files GAM downloaded from a completed activity or export request. In the case of exports, you may have multiple files to decrypt. Here's an example decrypt command: +``` +gpg --output jsmith-activity.txt --decrypt c:\gam\activity-jsmith-34231-1.txt.gpg +``` +this will create a file jsmith-activity.txt with the decrypted results. \ No newline at end of file diff --git a/docs/ExamplesCSV.md b/docs/ExamplesCSV.md new file mode 100644 index 00000000..e4768177 --- /dev/null +++ b/docs/ExamplesCSV.md @@ -0,0 +1,155 @@ + + +**Table of Contents** *generated with [DocToc](http://doctoc.herokuapp.com/)* + +- [Printing All Users](#printing-all-users) + - [Syntax](#syntax) + - [Example](#example) + - [users.csv contains:](#userscsv-contains) + - [Smith, wsmith@example.com, William,](#smith-wsmith@examplecom-william) + - [](#) +- [Printing All Groups](#printing-all-groups) + - [Syntax](#syntax-1) + - [Examples](#examples) + - [](#-1) +- [Print All Aliases](#print-all-aliases) + - [Syntax](#syntax-2) + - [Example](#example-1) + - [](#-2) +- [Print All Organizational Units](#print-all-organizational-units) + - [Syntax](#syntax-3) + - [Example](#example-2) + - [](#-3) +- [Print All Resource Calendars](#print-all-resource-calendars) + - [Syntax](#syntax-4) + - [Example](#example-3) + - [](#-4) +- [Print Reports](#print-reports) + - [Syntax](#syntax-5) + - [Example](#example-4) + + + +(TODO: Add table of contents.) + +_**Comments have been turned off for these help pages, please post your questions and comments to the [Mailing List](http://groups.google.com/group/google-apps-manager)**_ + +# Printing All Users + +### Syntax +``` +gam print users [firstname] [lastname] [username] [ou] [suspended] [changepassword] [agreed2terms] [admin] [aliases] [groups] +``` +prints a CSV file of all users in the Google Apps Organization. The CSV output can be redirected to a file using the operating system's pipe command (such as "> users.csv") see examples below. By default, the only column printed is the user's full email address. The optional arguments firstname, lastname, username, ou (organization unit), suspended, changepassword, agreed2terms, admin, nicknames and groups add the respective additonal column to the CSV output. Note that adding one or more of firstname, lastname, suspended, changepassword, agreed2terms or admin will require an additional call to Google's servers and will increase the length of time for the command to complete. Adding aliases will also require an additional call to Google's servers. Note also that adding groups will require 1 additional call to Google's servers per user which will significantly increase the length of time for the command to complete. + +### Example +This example will generate the csv file users.csv showing with columns for Email, Firstname and Lastname +``` +gam print users firstname lastname > users.csv +Getting all users in the organization (may take some time on a large Google Apps + account)... +Getting detailed info for users in example.com domain (may take some time on a large + domain)... + +users.csv contains: +-- +Lastname, Email, Firstname, +User, admin@example.com, Super, +Jones, pjones@example, Paul, +Smith, wsmith@example.com, William, +-- +``` + +--- + + +# Printing All Groups +### Syntax +``` +gam print groups [name] [description] [members] [managers] [owners] [settings] [domain ] [admincreated] [id] [aliases] [todrive] +``` +prints a CSV file of all groups in the Google Apps domain. The CSV output can be redirected to a file using the operating system's pipe command (such as "> groups.csv") see examples below. By default, the only column printed is the email address. The optional arguments name and description add the respective additional column to the CSV output. The optional arguments members, managers, owners and settings each perform additional API calls per group which may greatly increase the time it takes the command to complete. members, managers and owners will include a column for the respective role. settings will add multiple columns for the groups advanced settings. domain will limit the results to groups that have a primary address in the supplied domain. admincreated will include a True/False column in the results, False being user-created groups. aliases will add 2 columns to the output, Aliases and nonEditableAliases. The optional todrive parameter specifies that the results should be uploaded to Google Drive rather than being displayed on screen or piped to a CSV text file. + +### Examples +this example will output basic details for all groups and upload the results to Google Drive. +``` +gam print groups name description todrive +``` + +--- + + +# Print All Aliases +### Syntax +``` +gam print aliases [todrive] +``` +prints a CSV file of all user and group aliases in the Google Apps domain. The CSV output can be redirected to a file using the operating system's pipe command (such as "> nicknames.csv") see examples below. The optional todrive parameter specifies that the results should be uploaded to Google Drive rather than being displayed on screen or piped to a CSV text file. + +### Example +this example will output all aliases to Google Drive +``` +gam print nicknames todrive +``` + +--- + + +# Print All Organizational Units +### Syntax +``` +gam print orgs [name] [description] [parent] [inherit] +``` +prints a CSV file of all organizational units in the Google Apps account. The CSV output can be redirected to a file using the operating system's pipe command (such as "> orgs.csv") see examples below. By default, the only column output is "Path" (OUs full path). The optional arguments name, description, parent and inherit add the respective additonal column to the CSV output. Only 1 call to Google's servers is done no matter which arguments are specified so the optional arguments should not significantly increase the time it takes for the command to complete. + +### Example +this example will output all organizations to the file orgs.csv including all optional columns +``` +gam print orgs name description parent inherit > orgs.csv +``` + +--- + + +# Print All Resource Calendars +### Syntax +``` +gam print resources [id] [description] [email] +``` +prints a CSV file of all resource calendars in the Google Apps account. The CSV output can be redirected to a file using the operating system's pipe command (such as "> resources.csv") see examples below. By default, the only column output is "Name"The optional arguments id, description and email add the respective additonal column to the CSV output. Only 1 call to Google's servers is done no matter which arguments are specified so the optional arguments should not significantly increase the time it takes for the command to complete. + +### Example +this example will output all resource calendars to the file resources.csv including all optional columns +``` +gam print resources id description email > resources.csv +``` + +--- + + +# Print Reports +### Syntax +``` +gam report accounts|activity|disk_space|email_clients|summary [YYYY-MM-DD] +``` +Prints one of 5 Google Apps reports: + * The **accounts** report contains a list of all of the hosted accounts that exist in your domain on a particular day. The report includes both active accounts and suspended accounts. The status column will indicate whether each account is active or suspended. The field definitions for the accounts report can be found [here](http://code.google.com/googleapps/domain/reporting/google_apps_reporting_api.html#Accounts_Report). + * The **activity** report identifies the total number of accounts in your domain as well as the number of active and idle accounts over several different time periods. In this report, activity encompasses user interaction with his email, such as reading or sending email. The activity statistics includes web mail as well as POP activity. The field definitions for the activity report can be found [here](http://code.google.com/googleapps/domain/reporting/google_apps_reporting_api.html#Activity_Report). + * The **disk\_space** report shows the amount of disk space occupied by users' mailboxes. The report identifies the total number of accounts in your domain as well as the number of accounts that fall into several different size groupings. Mailboxes that occupy less than 1GB of disk space are grouped in increments of 100MB, and mailboxes that occupy between 1GB and 10GB of disk space are grouped in increments of 500MB. The field definitions for the disk\_space report can be found [here](http://code.google.com/googleapps/domain/reporting/google_apps_reporting_api.html#Disk_Space_Report). + * The **email\_clients** report explains how users in your domain access their hosted accounts on a day-by-day basis. For each day, the report lists the total number of accounts in your domain as well as the number and percentage of users who accessed their accounts using WebMail. This report does not include suspended accounts in the account total. The field definitions for the email\_clients report can be found [here](http://code.google.com/googleapps/domain/reporting/google_apps_reporting_api.html#Email_Clients_Report). + * The **summary** report contains the total number of accounts, total mailbox usage in bytes and total mailbox quota in megabytes for your domain. Each row in the report contains data for one day. This report does not include information for suspended accounts. The field definitions for the summary report can be found [here](http://code.google.com/googleapps/domain/reporting/google_apps_reporting_api.html#Summary_Report). + +optionally, a date can be specified in YYY-MM-DD format. The report for the given day will be pulled. If not specified, the report for the most recent day that has passed 12pm Pacific time will be pulled (e.g. today or yesterday if it's not yet noon Pacific time). + +**Note:** unlike the "gam print" commands, the report commands offer a snapshot of activity on a Google Apps domain for the given day, they are not realtime. For example, if you create a new user and then pull the accounts report, that user will not be included. It will take 24-48 hours before the user is included in the most recent accounts report. + +### Example +This command will pull the most recently available accounts report. +``` +gam report accounts +``` + +This example will pull the summary report from last month. +``` +gam report summary 2011-11-30 +``` \ No newline at end of file diff --git a/docs/ExamplesEmailSettings.md b/docs/ExamplesEmailSettings.md new file mode 100644 index 00000000..06fc5d77 --- /dev/null +++ b/docs/ExamplesEmailSettings.md @@ -0,0 +1,897 @@ +- [Signatures and Away Messages](#signatures-and-away-messages) + - [Setting a Signature](#setting-a-signature) + - [Retrieving a Signature](#retrieving-a-signature) + - [Enabling/Disabling and Setting a Vacation (Away) Message](#enablingdisabling-and-setting-a-vacation-away-message) + - [Retrieving Vacation Settings](#retrieving-vacation-settings) +- [Labels and Filters](#labels-and-filters) + - [Create a Label](#create-a-label) + - [Retrieving User's Labels](#retrieving-users-labels) + - [Delete a Label](#delete-a-label) + - [Create a Filter](#create-a-filter) + - [Retrieve a Filter](#retrieve-a-filter) + - [Delete a Filter](#delete-a-filter) + - [Print Filter Details](#print-filter-details) + - [Show Filter Details](#show-filter-details) +- [IMAP, POP](#imap-pop) + - [Setting IMAP Settings](#setting-imap-settings) + - [Retrieving IMAP Settings](#retrieving-imap-settings) + - [Setting POP Settings](#setting-pop-settings) + - [Retrieving POP Settings](#retrieving-pop-settings) +- [Send As](#send-as) + - [Add a Send As Address (Custom From)](#add-a-send-as-address-custom-from) + - [Update a Send As Address](#update-a-send-as-address) + - [Delete a Send As Address](#delete-a-send-as-address) + - [Retrieve a Send As Address](#retrieve-a-send-as-address) + - [Print Send As Addresses](#print-send-as-addresses) + - [Show Send As Addresses](#show-send-as-addresses) +- [Forwarding](#forwarding) + - [Add a Forwarding Address](#add-a-forwarding-address) + - [Delete a Forwarding Address](#delete-a-forwarding-address) + - [Retrieve a Forwarding Address](#retrieve-a-forwarding-address) + - [Print Forwarding Addresses](#print-forwarding-addresses) + - [Show Forwarding Addresses](#show-forwarding-addresses) + - [Setting a Forward](#setting-a-forward) + - [Print Forward Settings](#print-forward-settings) + - [Show Forward Settings](#show-forward-settings) +- [Delegates](#delegates) + - [Creating a Gmail delegate](#creating-a-gmail-delegate) + - [Deleting a Gmail delegate](#deleting-a-gmail-delegate) + - [Print Gmail delegates](#print-gmail-delegates) + - [Show Gmail delegates](#show-gmail-delegates) + - [Creating a Contact delegate](#creating-a-contact-delegate) + - [Deleting a Contact delegate](#deleting-a-contact-delegate) + - [Print Contact delegates](#print-contact-delegates) + - [Show Contact delegates](#show-contact-delegates) +- [Managing S/MIME Certificates](#managing-smime-certificates) + - [Adding S/MIME Certificates](#adding-smime-certificates) + - [Updating S/MIME Certificates](#updating-smime-certificates) + - [Deleting S/MIME Certificates](#deleting-smime-certificates) + - [Show/Print S/MIME Certificates](#show-print-smime-certificates) +- [Hiding/Unhiding users from the domain contacts](#hidingunhiding-users-from-the-domain-contacts) + - [Changing a users profile to hidden/unhidden](#changing-a-users-profile-to-hiddenunhidden) + - [Showing users profile hidden/unhidden status](#showing-users-profile-hiddenunhidden-status) +- [User Profile Photos](#user-profile-photos) + - [Updating Profile Photos](#updating-profile-photos) + - [Getting Profile Photos](#getting-profile-photos) + - [Deleting Profile Photos](#deleting-profile-photos) +- [Managing User Email](#managing-user-email) + - [Modifying User Emails](#modifying-user-emails) + - [Deleting or Trashing User Emails](#deleting-trashing-or-untrashing-user-emails) + - [Sending Email as a User](#sending-email-as-a-user) + - [Dropping Emails into a User Mailbox](#dropping-emails-into-a-user-mailbox) + - [Drafting Emails for a User](#drafting-emails-for-a-user) +- [Print/Show User Gmail Profile](#print-show-user-gmail-profile) + - [Print User Gmail Profile](#print-user-gmail-profile) + - [Show User Gmail Profile](#show-user-gmail-profile) +- [Managing User Display Language](#managing-user-display-language) + - [Set User Language](#set-user-language) + - [Get User Language](#get-user-language) + +# Signatures and Away Messages +## Setting a Signature +### Syntax +``` +gam user |group |ou |all users [signature ] [file ] [replyto ] (replace )* +``` +sets a email signature for the given users' primary email address. Use quotes around the signature text if it contains spaces (which it almost certainly will). New lines can be specified with \n. HTML can also be used. An empty string like "" will disable the signature. Use the optional `file` argument to specify a filename that contains the signature text. This is easier for long, complex signatures. Use the optional `replyto` argument to specify a reply to address for use with this signature. The optional argument `replace` can be used to insert values into the signature text. Every instance of {`Tag`} in the signature will be replaced by `String`. Instances of the form {RT}...{`Tag`}...{/RT} will be eliminated if that `Tag` was not specified or if `Tag` was specified but the accompanying `String` is empty. {RT} and {/RT} are eliminated from the signature. +### Example +This example sets all user's signatures to be: +``` +Acme Inc +1321 Main Ave +http://www.acme.com +``` + +``` +gam all users signature + "Acme Inc
1321 Main Ave
http://www.acme.com +``` + +This example reads the signature from a file: +``` +gam user bob@example.com signature file bobs-sig.txt +``` + +This example reads the signature from an HTML file: +``` +gam user sue@example.com signature file sues-html-sig.html html +``` +---- + +## Retrieving a Signature +### Syntax +``` +gam + user | group | ou | all users show signature [format] +``` +Shows the email signature for the given users. By default, the raw HTML of the signature is shown, the optional argument `format` causes the HTML to be interpreted. + +### Example +This example shows all user's signature + +``` +gam all users show signature +``` +---- + +## Enabling/Disabling and Setting a Vacation (Away) Message +### Syntax +``` +gam + user | group | ou | all users + vacation on|off subject [message ] | [file ] [html] + startdate enddate + [contactsonly] [domainonly] + (replace )* +``` +enable or disable a vacation/away message for the given users. `subject ` will set the away message subject. `message ` will set the away message text. Use quotes around `` and `` if they contain spaces (which they probably will). If `file` is specified instead of message, the message will be read from the given text file. In ``, \n will be replaced with a new line. The optional argument `html` says to interpret the message text as HTML. Except for the simplest messages, you should specify `html` even if your message doesn't contain HTML as Google does unexpected line wrapping when `html` is not specified. The optional `startdate` and `enddate` arguments set a start and end date for the vacation message to be enabled. The optional argument `contactsonly` will only send away messages to persons in the user's Contacts. The optional argument `domainonly` will prevent vacation messages from going to users outside the Google Apps domain. The optional argument `replace` can be used to insert values into the away message text. Every instance of {`Tag`} in the message will be replaced by `String`. Instances of the form {RT}...{`Tag`}...{/RT} will be eliminated if that `Tag` was not specified or if `Tag` was specified but the accompanying `String` is empty. {RT} and {/RT} are eliminated from the message. + +### Example +This example sets the away message for the user +``` +gam user epresley vacation on subject "Elvis has left the building" + message "I will be on Mars for the next 100 years. I'll get back to you when I return.\n\nElvis" +``` + +This example reads the message from a text file: +``` +gam user bob@example.com vacation on subject "I am away" file bobs-away-message.txt +``` +---- + +## Retrieving Vacation Settings +### Syntax +``` +gam + user | group |ou | all users show vacation [format] +``` +Show the given user's vacation message and settings. By default, the plain text or raw HTML of the vacation message is shown, the optional argument `format` causes the HTML to be interpreted. + +## Example +This example shows the vacation settings for jsmith +``` +gam user jsmith show vacation +``` + +# Labels and Filters +## Create a Label +### Syntax +``` +gam user |group |ou |all users label