gam-team/gam

command line management for Google Workspace

GAM is a command line tool for Google Workspace admins to manage domain and user settings quickly and easily.

Quick Start

Linux / MacOS

Open a terminal and run:

bash <(curl -s -S -L https://gam-shortn.appspot.com/gam-install)

this will download GAM, install it and start setup.

Windows

Download the MSI Installer from the GitHub Releases page. Install the MSI and you'll be prompted to setup GAM.

Documentation

The GAM documentation is hosted in the GitHub Wiki

Mailing List / Discussion group

The GAM mailing list / discussion group is hosted on Google Groups. You can join the list and interact via email, or just post from the web itself.

Chat Room

There is a public chat room hosted in Google Chat. Instructions to join.

Author

GAM is maintained by Jay Lee. Please direct "how do I?" questions to Google Groups.

gam's Issues

GAM.wiki - cannot clone to desktop

Tried to clone the GAM.wiki to GitHub Desktop but it says that the repository is invalid. The URL being used is github-windows://openRepo/https://github.com/jay0lee/GAM.wiki

Any ideas how to get this cloned to the desktop?dir

Updating group alias error.

Prereq:
[email protected] - actually as an alias to group [email protected]

Expected result:
[email protected] as an alias to [email protected]

Below cmds don't work.
gam update alias [email protected] group [email protected]
gam update alias [email protected] target [email protected]

Cmds result:
Error 400: Type not supported: userKey - badRequest

Gam print users

Hello.

In the new version, the function gam print users, show group address

Update internal organization information

From the documentation it only appears that we can add external organizational information. Is it possible to edit the internal description and title of a user via GAM?

Here is relevant section of gam info user

Organizations:
 customType:
 description: Staff
 title: Technology Coordinator

I'd love set title for everyone in the district without updating each by hand.

3.4.1 Issue with "gam get schema <schemaname>"

Just created a custom schema, but can't get info on it, GAM spits out example's.

gam org name get photo, results in an error since 3.4

Getting profile images is still working in 3.21, but not in 3.4 and 3.41.
Running this with 3.4 and 3.41 results in an error.

..\gam org Organization get photo

Getting all users in the Google Apps organization (may take some time on a large
domain)...
Got 930 users...929 users are directly in the OU.
Saving photo to [email protected] (1/929)
no photo for [email protected]
Saving photo to [email protected] (2/929)
Traceback (most recent call last):
File "gam.py", line 7612, in
File "gam.py", line 1548, in getPhoto
File "base64.pyo", line 112, in urlsafe_b64decode
File "base64.pyo", line 71, in b64decode
File "base64.pyo", line 36, in _translate
TypeError: character mapping must return integer, None or unicode

info user doesn't print all groups

Hi,

it seems a "gam info user {user} " command only returns the first 200 groups although Google supports up to 2000 groups per owner.
Also, is there an option to show indirect ownership of a group?
(currently using Gam 3.21)

print users firstname lastname is not working

the command print users firstname
pulls back first, full, and last name
any combinations of the name options pulls backs all three columns

Looks like gam report * is a different format.

Hey long time user of GAM. Big fan of the work. It looks like the output has changed pretty drastically since 3.02. (The last version I have been using.)

For this example I was using gam report logins. (I get similar results with gam report admin )

The format used to be:

time,user,event,ip,login_type,login_failure_type
2015-02-14T22:39:23.000Z,<email address>,login_success,<ipaddress>,google_password,

But is now:

name,actor.email,actor.profileId,id.applicationName,id.customerId,id.time,id.uniqueQualifier,ipAddress,parameters.0.name,parameters.0.value,parameters.1.name,parameters.1.value,type
login_success,<email address<>,<Google Unique ID>,login,<Customer ID>,2015-02-14T22:39:23.000Z,1448685302752473115,108.53.164.115,login_type,google_password,,,login

The first format lines up properly.

time = 2015,02-14T....etc | user = <email address> | event = login_success | ip = <ip address> | login_type = login_success | login_failure_type = google_password

the second format doesn't seem to line up.

name = login_success | actor.email = <email address> | actor.profileID = <google unique id> | id.application <login> | customerID = <customerid> | id.time = the time | uniqueQualifier = <another code> | ipAddress = <ip> | parameters.0.name = login_type, | parameters.0.value = google_password | parameters.1.name = , | parameters.1.value = , | type = login

I am just a bit confused by the output and the columns there. Thanks for checking it out / or for the explanation 👍

KeyError: u'client_email'

Using

Dito GAM 3.42 - http://git.io/gam
Jay Lee [email protected]
Python 2.7.8 64-bit final
google-api-python-client 1.3.1
Linux-3.16.0-25-generic-x86_64-with-Ubuntu-14.10-utopic x86_64

I run (with the user@domain replaced here in this ticket)

./gam.py user [email protected] show filelist

and I get

Traceback (most recent call last):
File "./gam.py", line 7599, in
showDriveFiles(users)
File "./gam.py", line 1873, in showDriveFiles
drive = buildGAPIServiceObject(u'drive', user)
File "./gam.py", line 589, in buildGAPIServiceObject
SERVICE_ACCOUNT_EMAIL = json_data[u'client_email']
KeyError: u'client_email'

If I try

./gam.py all users show filelist query "fullText contains 'TEST'"

I get the same thing.

Can't delete ACLs involving "anyoneWithLink"

If you "show drivefileacl" on a file that has "anyoneWithLink", you can see it listed as the id, where it would normally be a numeric ID.

The "delete drivefileacl" command won't function with that as an ID though. [GAM Version 3.42]
It shows that it looked up some sort of user ID, and that ID couldn't be found.

client_secrets.json not found

Hi,

I have just downloaded the GAM 3.41 and started using it from command prompt. Right after issuing the command "gam info domain" and then selecting the scope I was presented with this message:

"WARNING: Please configure OAuth 2.0

To make GAM run you will need to populate the client_secrets.json file
found at:

C:\Users\Desktop\Student Mail\Tools\gam-3.41-windows-x64\gam-64\client
_secrets.json

with information from the APIs Console https://cloud.google.com/console.

See https://code.google.com/p/google-apps-manager/wiki/CreatingClientSecretsFile

for instructions."

Now the issue is that I can't find "client_secrets.json" file at the target location. Also, the url for instructions is also old and does not point to the right location.

Proxy CONNECT uses IP address rather than domain name

My organization uses a proxy for outbound HTTP and HTTPS access to internet resources from a server farm. Access through the proxy is only authorized to specific domain names (e.g. .google.com, .googleapis.com, .apple.com, .microsoft.com, etc.). This works fine for clients that issue

"CONNECT <host.domain.name>:<port>"

requests in order to tunnel HTTPS connections through the proxy. With exception of GAM, all of our clients issue "CONNECT" this way. In GAM's case

httplib2/socks.py

builds

"CONNECT <ipaddress>:<port>"

requests instead. This makes it challenging to limit destinations using our proxy server implementation, as we would have to allow access to all of Google's address space in order for GAM to work. It would therefore be desirable for GAM to CONNECT via domain name if possible.

GAM sync seems to be working like update

We've tried this on multiple machines - it seems that at some point
gam update group [email protected] sync user file name.txt
changed behavior. It used to work as documented, but after a recent update, it now will overwrite the status of existing members and make existing managers into users - much like the update command.

This has broken our global mailing lists. Any help would be appreciated. Thanks!

Feature request: update timezone calendar

Hi,

Could GAM implement the https://developers.google.com/google-apps/calendar/v3/reference/calendars/update api to be able to update calendar timezone's (and other calendar attributes)?

This is an example I had to do for some calendars:
PUT https://www.googleapis.com/calendar/v3/calendars/calendar%40domain.be?key={YOUR_API_KEY}
{
"summary": "[email protected]",
"timeZone": "Europe/Brussels"
}

Thnx in advance!

2SV status?

Is there a way to query a user's 2SV status?

In the Google Admin Web UI:

create a group with GAM as a collaborative mailbox

Hi,

I don't find the command line to change the group type, I need to create a lot of group for a public folder migration and i love your tools but i can't manage to create that kind of group.

Thanks for your help and keep up the good work!

Very usefull :)

Bug in doCalendarDelACL()

doCalendarDelACL() has a bug with setting "entity" to the wrong argument (line 1327, GAM 3.42). It is using argv[4] but should use argv[5]. The effect of this is to use the keyword "user" rather than the actual entity. This results in attempting to delete the ACL for "user@domain" and effectively causing the delete function to not work (with the possible side effect of deleting the ACL for user@domain if such a user exists and has an ACL).

The fix is to change line 1327 to
entity = sys.argv[5].lower()

Gam Bulk Update Groups - System error

I've upgraded to (GAM 3.42) I've tested access successfully with:

$ gam update group it@our_domain.com maxMessageBytes 25M
updated group [email protected]

But when I try to do a bulk operation (via a pipe), I get this output:

$ gam print groups | gam update group ~Email maxMessageBytes 25M
Retrieving All Groups for Google Apps account (may take some time on a large account)...
Error 400: A system error has occurred - invalid

Got 159 groups: 305main@our_domain.com - zuora-notifications-group@sour_domain.com
close failed in file object destructor:
sys.excepthook is missing
lost sys.stderr
$

doUpdateUser

line 4272:
sys.stderr.write(u'updating user %s...\n' % user)

I am not sure if this is by choice, but I expected this to go to stdout , not stderr

Thank you

"delegate to" command fails consistently

Using either Gam 3.42 or older versions on either MAC or Windows with a couple of different accounts we consistently receive an error when attempting the "delegate to" command.

Verified accounts are active and not requiring password change and that E-mail is not alias and primary address.

All other gam commands work fine including "show delegate" on the same mailboxes.

When a "delegate to" command is run the error received is

Temp Error. Backing off 16 seconds......attempt 5/10
Temp Error. Backing off 32 seconds......attempt 6/10
.
.
.
Temp Error. Backing off 60 seconds......attempt 10/10
-giving up

These commands had worked in the past and recently became a problem about 3 or 4 weeks ago. At first error was intermittent and now command seems to fail every time in all scenarios.

Wondering if there was any ideas on why this no longer seems to be working?

Bug in doCalendarAddACL

doCalendarAddACL() has a bug in the "except KeyError:" at line 1311 (GAM 3.42). This appears to be for picking up an exception when there's no 6th argv. However, sys.arg is a sequence, not a dictionary so the exception should be IndexError. The effect of the bug is that when attempting to use "domain" for add, update or delete, GAM fails with an error. Note that this is a separate bug to Issue 32.

The fix is to change line 1311 to
except IndexError:

Include Consent to Wiki Doc

FYI, I got the error "invalid_client: no application name" while try in to complete the setup process (after running gam info domain. After a quick Google search, I found that the Consent part of the API console needs to be completed as well. I'd suggest adding this as a step to your client_secrets.json Wiki doc.

http://stackoverflow.com/questions/18677244/error-invalid-client-no-application-name

GAM Delete Mobile

I'm getting a temp error InternalError message when trying to use the "gam delete mobile" command. Any suggestions?

Update wiki

Hi.

For a while I hade trouble with GAM wanting me to add a client_secrets.json. I generated the file and placed it in the GAM-folder. But still the same message.

What finally did the trick was to generate a new client with the "Installed app" instead of the "Web..." i had used before.

This could be clarified in the wiki under generate client_secrets.json. As well as update the warning message in gam.exe so that it checks that the json file contains the word "installed".

Regards Tomas W

Set organization settings

Hi there,

I've been trying to update organization information such as title or name but it doesn't seem to be working with the following syntax :

sudo gam.py update [email protected] organization title "Test Inc."

I always get this error Error: invalid argument to "gam update..."

I don't understand what I'm doing wrong as I'm following what's wrotte on the documentation.

If there's anyone out there having or had this problem I'll be glad to hear from you.

Regards,

Refactor GAM to be "import"able

I'd like to use some of the GAM logic in separate scripts. GAM already does a lot of the hard work to set up API objects and the like.

I'd like to refactor the code to start making it reusable in new scripts.

My first step would be to pull out the object initialization into a new file, such as gamlib.py, which would be used by gam.py. Everything that ends up in gamlib.py would be something that is built to be reused - all OO, no globals, etc.

Would you like to discuss this and tell me what requirements you'd have for it to be something you're willing to merge in?

GAM report users todrive fails

After processing about 90k the following error occurs: Error: [Errno 8] _ssl.c:510: EOF occurred in violation of protocol

orgUnitPath is now orgUnitKey, causes gam.py info org <org> to fail

I did some debugging, it would appear that Google changed the orgUnitPath parameter to be orgUnitKey, though I don't see it documented (yet?).
https://developers.google.com/admin-sdk/directory/v1/reference/orgunits/get

In my testing, orgUnitKey still accepts the "name" of the orgUnit.

So in GAM 3.43 you can fix it by changing line 5209 as follows.

From: result = callGAPI(service=cd.orgunits(), function=u'get', customerId=customerId, orgUnitPath=name)
To: result = callGAPI(service=cd.orgunits(), function=u'get', customerId=customerId, orgUnitKey=name)

I'm not sure if they renamed any other parameters, this just happens to be one that a scheduled job runs, so I stumbled upon it.

Last pop3/imap time

Could you please enhance the "gam info user" command with the last pop3/imap access time?
The "gam user show pop" and the "gam user show imap" commands could also report these timestamps.

Recursive ownership change?

GAM has been super useful for me as I try to manage our Drive instance when many of our users don't follow appropriate protocols. Is there any way that GAM can recursively change owners on all child folders? It's quite easy to change ownership for one folder, but I can't find any GAM function that list all child elements in a folder with their owners (which I could then plug back into GAM via bulk operation). I've tried looking through the code but I don't have much python or Google Apps/Drive API experience and haven't been able to figure out how to call the appropriate Google Drive API functions to extend GAM to support such a function.

Any advice would be much appreciated!

errorCode="1801"

./gam.py info domain
...
Domain Edition: standard
...
User Migration Enabled: false
ERROR:

Missing import string

Hi Jay,

I think there is a missing the import of the string module and gam is crashing on this line:

safe_filename_chars = "-_.() %s%s" % (string.ascii_letters, string.digits)

Feature Request: change default value of 'view member email addresses'

Greetings:
Our company's users look at the membership addresses of group(s) to confirm before sending emails to them, much like expanding the 'plus sign' when addressing groups using Outlook. I cannot find the command that will change the setting.
Thanks, Jim

permissions/access permissions/view member email addresses
Default setting = owners of the group
Required setting = all organization members

3.4 cannot find oauth2service.json on 'gam user [email protected] show calendars'

I got this error after using the 'gam user [email protected] show calendars' command:

Traceback (most recent call last):
File "./gam.py", line 7496, in
showCalendars(users)
File "./gam.py", line 1565, in showCalendars
cal = buildGAPIServiceObject(u'calendar', user)
File "./gam.py", line 580, in buildGAPIServiceObject
json_string = open(oauth2servicefilejson).read()
IOError: [Errno 2] No such file or directory: u'/Users/roald/Project/gam2/oauth2service.json'

Every other command I tried works flawlessly. A strange bug or am I doing something very wrong here? This is on OSX Mavericks using gam 3.4 (I didn't see anything related to this in the changelog for 3.41 so I didn't think upgrading would solve this instantly).

GAM Bulk update groups

Hello jay0lee,

I am trying to use GAM to update groups on Google Apps however within powershell I get error: [Errno:10061] No connection...

I was getting this in command line but used the set http_proxy and set https_proxy commands and this worked but these commands do not allow me to connect with powershell

any help appreciated

Jase

Updating 'domain' ACL for resource cals doesn't work

When attempting to update resource cal domain level ACL, the command doesn't work:
Example command:

gam calendar example.com_436d6e[e-mail] update freebusy domain

What is shown following:

Dito GAM 3.42 - http://git.io/gam
Jay Lee [email protected]
Python 2.7.6 64-bit final
google-api-python-client 1.3.1
Darwin-14.0.0-x86_64-i386-64bit x86_64
Path: /Users/USERFOLDER/FOLDER/

Usage: gam [OPTIONS]...

Dito GAM. Retrieve or set Google Apps domain,
user, group and alias settings. Exhaustive list of commands
can be found at: https://github.com/jay0lee/GAM/wiki

Examples:
gam info domain
gam create user jsmith firstname John lastname Smith password secretpass
gam update user jsmith suspended on
gam.exe update group announcements add member jsmith
...

Replacing 'update' with 'reader' gives the following error, showing the the command is understood:
Error: Role must be freebusy, read, editor or owner. Not reader

Date problem

Starting the "gam report users todrive" command this error appears:

Error: Start date can not be later than 2014-10-03.

The current date and time is: 2014-10-04 08:44, CET. The "gam info domain" command has no problem with the time.

Make GAM an importable module

Hi,

I was wondering if you'd be willing to make a quick, small addition. I thought it might be fun to create a wrapper python script to call some GAM functions, but when I went to import GAM into my file, it runs gam independently (and fails my script since no arguments are being passed to GAM from the command line). Would it be possible to just add:

if name == 'main':

before your main section:

Main

reload(sys)
sys.setdefaultencoding(u'UTF-8')

This will keep the main section from being run if someone is importing GAM into another python file, but still run it normally when called on its own. It's easy to do independently, but figured I'd provide the feedback for your next release.

Thanks!

Show labels: UnicodeEncodeError

I get this error when I try to
gam all users show labels
or
gam user username show labels

The error:

Traceback (most recent call last): File "/home/henrik/src/GAM-3.43a/gam.py", line 7593, in <module> showLabels(users) File "/home/henrik/src/GAM-3.43a/gam.py", line 2924, in showLabels print label[u'name'] UnicodeEncodeError: 'ascii' codec can't encode character u'\xe5' in position 7: ordinal not in range(128)

UnicodeEncodeError / show calendars

CMD: gam user show calendars

Traceback (most recent call last):
File "gam.py", line 7591, in
File "gam.py", line 1574, in showCalendars
File "encodings\cp852.pyo", line 12, in encode
UnicodeEncodeError: 'charmap' codec can't encode character u'\xf5' in position 2
1: character maps to

UnicodeDecodeError

GAM 3.32 Windows x64
gam report users todrive

This report could not finish on a large database (almost 500.000 users). Always finished with this error message you can see on the attached screenshot.

3.4 (and 3.41) are crashing on downloads

C:\Scripts\gam>c:\scripts\gam\gam user [email protected] get drivefile id 1QtR
7HaCa3-IKO6YvnHIgTxb72OnceuGkkY_4RC1fG-Q format micosoft targetfolder c:\BCP_Pla
ns\google
Traceback (most recent call last):
File "gam.py", line 7614, in
File "gam.py", line 2223, in downloadDriveFile
NameError: global name 'string' is not defined

It looks like line 2223 or 2305/2306 introduced the error. I have string.py in my Python 2.7 implementation so I tried gam.py but got the same result. Going back to 3.32 allowed the download to work.

Enabling and Setting a Vacation (Away) Message Vacation

using gam 3.41, submitted the following (edited) command:
gam user [email protected] vacation on subject "Out of Office" message "Please note that user is currently out of the office. In her absence, please contact our Customer Service Department at [phone] for immediate assistance.\n\n" startdate 2015-03-30 enddate 2015-04-04

Text for message was set, vacation was turned on, but neither start nor end dates were set.

can not authenticate into domains

Hi,

using this commands:

gam info domain
press enter
insert 22 to continue

we get this error

Traceback (most recent call last):
File "gam.py", line 7416, in
File "gam.py", line 5533, in doGetDomainInfo
File "gam.py", line 516, in buildGAPIObject
File "gam.py", line 7267, in doRequestOAuth
File "oauth2client\util.pyo", line 129, in positional_wrapper
File "oauth2client\tools.pyo", line 183, in run_flow
File "oauth2client\util.pyo", line 129, in positional_wrapper
File "googleapiclient\http.pyo", line 723, in execute
googleapiclient.errors.HttpError: <HttpError 403 when requesting https://www.goo
gleapis.com/urlshortener/v1/url?alt=json returned "Daily Limit for Unauthenticat
ed Use Exceeded. Continued use requires signup.">

this happens in every device into our company.
This not happens if you have already an .oauth file to get authenticated into a domain.
.json file and all things that we must do on AppEngine console has been made

is it a known issue?
please let me know
regards
Stefano Saccone from Noovle SRL

1409 Invalid Encryption Public Key

With this command: gam audit export request john.doe
In Windows Command Prompt
Error: 1409 Invalid Encryption Public Key

Enable Google Apps api and followed the instructions. Is there a common reason?

Proxy CONNECT uses IP address rather than domain name (issue #45 continued)

Please refer to issue #45 for background.

... Actually, it looks like the version of httplib2 included in GAM and how GAM calls it that affects this:

The following code is present in the version of httplib2/__init__.py included in GAM 3.42:

    def __init__(self, proxy_type, proxy_host, proxy_port,
                 proxy_rdns=None, proxy_user=None, proxy_pass=None):

Whereas the following code is present in the current master branch of httplib2/__init__.py:

    def __init__(self, proxy_type, proxy_host, proxy_port,
                 proxy_rdns=True, proxy_user=None, proxy_pass=None):

along with the comment:

          proxy_rdns: If True (default), DNS queries will not be performed
          locally, and instead, handed to the proxy to resolve.  This is useful
          if the network does not allow resolution of non-local names.  In
          httplib2 0.9 and earlier, this defaulted to False.

Patching the version distributed with GAM, changing "proxy_rdns=None" to "proxy_rdns=True" addresses the issue.

I'd say, either updating the version of httplib2 or overriding the default when ProxyInfo is initialized would address the issue. In either case this would point back at GAM as the place to fix this.

ValueError: No JSON object could be decoded when running "show filelist"

running the latest version GAM-3.43a
under Debian Stable using Python 2.7.3

Command is:

gam user show filelist

gam returns:

raceback (most recent call last):
File "/home/john/scripts/gam/current/gam.py", line 7605, in
showDriveFiles(users)
File "/home/john/scripts/gam/current/gam.py", line 1879, in showDriveFiles
drive = buildGAPIServiceObject(u'drive', user)
File "/home/john/scripts/gam/current/gam.py", line 580, in buildGAPIServiceObject
json_data = json.loads(json_string)
File "/usr/lib/python2.7/json/init.py", line 326, in loads
return _default_decoder.decode(s)
File "/usr/lib/python2.7/json/decoder.py", line 365, in decode
obj, end = self.raw_decode(s, idx=_w(s, 0).end())
File "/usr/lib/python2.7/json/decoder.py", line 383, in raw_decode
raise ValueError("No JSON object could be decoded")
ValueError: No JSON object could be decoded

Please let me know if you need more information.

gam user [username] get drivefile hangs

I'm trying to download a users files and email. I've been successful downloading the user mailbox, but the command to download the file hangs.

Nothing is placed into the target folder using:
gam user [username] get drivefile query "'me' in owners" format microsoft ~/Documents/[username]

If I run : gam user [username] show filelist

I receive: Error 403: Forbidden - forbidden

I've run through the setup twice and upgraded to 3.42. Any suggestions?

retrieving vacation settings does not seem to work

Using GAM 3.43 when issuing the following command:
gam user [email protected] show vacation

I receive the following:
Traceback (most recent call last):
File "gam.py", line 7623, in
File "gam.py", line 3331, in getVacation
File "encodings\cp437.pyo", line 12, in encode
UnicodeEncodeError: 'charmap' codec can't encode character u'\u201d' in position
292: character maps to