Troubleshoot common GCDS issues
Here’s how to troubleshoot problems you might have while configuring Google Cloud Directory Sync (GCDS). You can also check G Suite Known Issues for additional info.
Setup and configurationTroubleshoot a configuration using Configuration Manager
If you're having trouble getting a synchronization to run properly, confirm that the configuration information is correct in Configuration Manager and note which tests fail:
- In Configuration Manager, open the XML file you're using to configure the synchronization.
- On the LDAP Connections page, click Test Connections to confirm you can connect to your LDAP server.
- On the Notifications page, click Test Notification to confirm you can send a test notification.
- On the Sync page, click Simulate Sync to confirm you have completed all the required fields and to confirm that the synchronization runs.
To troubleshoot a configuration using log files, submit generated logs to the Log Analyzer.
Most issues can be identified within a few moments of submission.
GCDS needs to validate Secure Sockets Layer (SSL) certificates when connecting to Google APIs (over HTTPS) and LDAP over SSL by connecting through HTTP to certificate revocation list (CRL) providers. Sometimes, these validations fail, usually due to a proxy or firewall blocking the HTTP request.
Make sure the GCDS server can access the following URLs over HTTP (port 80):
Additional URLs might be needed if you're using your own certificates for LDAP over SSL.
If you can't enable CRL access, you can disable CRL checks, although this reduces the security of SSL and is not recommended. To do so, edit the
config-manager.vmoptions files in the installation directory of GCDS and add these lines:
To run a simulated synchronization, you need a server capable of sending mail. If you're running GCDS on a mail server machine, you can use the IP address 127.0.0.1 for your mail server. Otherwise, contact your mail administrator for the correct mail information.
In rare cases, Google Cloud support may ask you to enable full HTTP logging in addition to enabling trace-level logging in GCDS. Full HTTP logging is used to see the exact API request made by GCDS and the response provided by the Google APIs.
Important: Full HTTP logs can contain highly sensitive information. Remove any sensitive information (such as current refresh_token or access_token fields) before sending the logs to support.
To enable full HTTP logging:
- Make sure GCDS isn't running with either sync-cmd or Configuration Manager.
- Navigate to the GCDS installation folder.
- Edit the file
- Add the following lines to the end of the file:
java.util.logging.FileHandler.pattern = %h/gcdshttp%u.%g.log
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.count = 100
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
handlers = java.util.logging.FileHandler
com.google.api.client.http.level = CONFIG
- Save the file.
- Run another GCDS sync (with logging set to Trace).
Log files named gcdshttp*.log are created in homedir (Linux) or profile folder (Windows). Archive these files together, because they can be quite big.
- Delete the lines added in step 4 to prevent large log files being created in the future.
Then, provide the following files to support:
- The XML file used.
- The trace-level logs from the latest sync.
gcdshttp*.logfiles generated by the sync.
Using these logs, support can see the information provided by the Directory API to GCDS and how GCDS responds.
Note: If you want to use a debugging proxy, such as Fiddler™, with GCDS, you need to export the Fiddler certificate, add it to GCDS, and disable CRL checks. You can then set Fiddler as the proxy server in GCDS (usually 127.0.0.1 on port 8888) and the connection is logged by Fiddler. For details on how to import the Fiddler root certificate into GCDS's Java® truststore, see Certificate-related errors.
See Work with configuration files for instructions on how to open an XML file that was saved on a different machine, or as a different user on the same machine.
You might see
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target errors in your GCDS log file. This error indicates that GCDS can't verify the certificate presented by the server because it isn't signed by a Certificate Authority (CA) that GCDS trusts. GCDS uses Java trusted root CA certificates. If your server's certificate is trusted by the operating system, you need to explicitly import it into GCDS.
To import a server certificate, you must export it from the domain controller and then import it into GCDS:
To export the certificate:
- Sign in to the domain controller.
- Open a command prompt.
certutil -store My DomainController dccert.certo export the domain controller's certificate.
- Copy the
dccert.cerfile to the server where GCDS is installed.
To import the certificate:
- Sign in to the server where GCDS is installed.
- Open a command prompt.
- Change the directory to the GCDS Java Runtime Environment (JRE) installation folder by entering one of the following commands:
- For Windows:
cd "c:\Program Files\Google Cloud Directory Sync\jre"
Note: If you installed GCDS 32-bit on a 64-bit system, the command is:
cd "c:\Program Files (x86)\Google Cloud Directory Sync\jre". For Linux, use:
- For Windows:
- Enter one of the following commands:
bin\keytool -keystore lib\security\cacerts -storepass changeit -import -file c:\dccert.cer -alias mydc
bin/keytool -keystore lib/security/cacerts -storepass changeit -import -file ~/dccert.cer -alias mydc
- (Optional) To trust the certificate, enter yes.
- Close Configuration Manager.
- Open Configuration Manager and on the LDAP Connections page, click Test Connections to confirm you can connect to your LDAP server.
If you're still seeing certificate-related errors, you might need to import your organization's CA certificate rather than your domain controller certificate. To do this, repeat the steps above but export and import the CA certificate instead.
Note: You can use the steps above to import certificates of other types of LDAP servers, or HTTP proxies that use self-signed certificates.
In your XML configuration file, enable the useDynamicMaxCacheLifetime option. This option configures GCDS to cache data for a maximum of 8 days, and clear the cache more frequently in small-to-medium data sets to reduce the chance of cached data growing stale or conflicting with new data. The useDynamicMaxCacheLifetime option is automatic in configurations created with GCDS 3.2.1 and above.
Note: These errors usually occur when modifications are done directly in your Google domain. When using GCDS to sync, you should avoid making changes to your Google domain directly. Instead, make changes to users, groups, and other entities in your LDAP directory. Then, use GCDS to sync these changes to your Google domain.
If you're seeing memory-related errors, you need to increase the heap size for Java Virtual Machine. Increase the heap size by editing the
config-manager.vmoptions files in the installation directory of GCDS. The relevant entries look like this:
-Xmx1000m(the maximum amount of memory for the heap size)
-Xms64m(the minimum amount of memory for the heap size)
Edit both the
config-manager.vmoptions files so that the change applies to both sync-cmd and Configuration Manager versions.
-Xmx number to increase the amount of memory. The "m" following the number indicates that the memory is measured in megabytes (MB). The correct amount of memory depends on how much the GCDS server has, and how much it needs for a synchronization. You might need to revise the number several times to set the correct size. For more information on the amount of free RAM required to run GCDS, read System requirements for GCDS.
This might be a configuration issue, such as an exclusion rule misconfiguration. This kind of misconfiguration can be hidden by GCDS caching.
GCDS keeps a cache of data for your Google service (such as G Suite or Cloud Identity) for a maximum of 8 days. GCDS might clear the cache more frequently, depending on the cached data size. However, if the cache isn't cleared, you might not see your updates for up to 8 days.
You can manually clear the cache:
- Run a sync from Configuration Manger and select to clear the cache when performing a sync.
- Use the command line
flag -fto force a flush of the cache.
- Modify the XML config file to set the maxCacheLifetime value to 0.
Important: Forcing a flush of cache can dramatically increase synchronization time.
For example, you sync your LDAP data and create a new group for your Google service (such as G Suite or Cloud Identity). You then create an exclusion rule to exclude that group from subsequent syncs. That exclusion rule is misconfigured and will fail. However, the subsequent sync calls on cached data and the group remains in your Google service. When you sync again with clear cache, the misconfiguration causes the group to be removed from your Google service.
Users and groupsWhy are some users not synced as groups members?
To synchronize group members separately from the results of any user search rules, GCDS enables the
INDEPENDENT_GROUP_SYNC option by default. If you're using member-reference attributes for group synchronizations, GCDS tries to resolve the email address of every user in the LDAP directory, regardless of any user search rules.
If you disable the
INDEPENDENT_GROUP_SYNC option, GCDS only uses the results of the user search rules to resolve group members. If some of your users aren't included in your user sync, they won't be synced as group members. This is particularly important if you're syncing shared contacts and you have group members that are contacts—they won't be synchronized as group members.
It's highly recommended to leave
INDEPENDENT_GROUP_SYNC enabled. Disabling it is only provided for backwards compatibility and troubleshooting.
This happens when the LDAP attribute configured as the Group Name Attribute doesn't contain a full email address. To resolve this issue, check your Group Search rules and make sure that GCDS uses a full email address for the group names. Use one of the following methods:
- Set the Group Name Attribute to a different LDAP attribute that specifies a full email address for each group, such as mail.
- Enable Replace domain names in LDAP email addresses in the Google Domain Settings, so that your Group Name Attribute matches the Google-side group names.
- Add the domain name to the group name by specifying a Group Name Suffix in your Group Search Rule.
Make sure you have selected MS Active Directory in the server type field of the LDAP Configuration section.
This option (shown as
SUPPRESS_DOMAIN in the XML file) is used if the email addresses in the LDAP directory are in a different domain than your Google domain. When you enable it, GCDS strips the domain part off all of the email addresses it reads.
Any processing is done without the domain name. If you use exclusion rules based on email addresses, you need to consider only the local part of the email address for the exclusion rule.
For example, if you have Replace domain names in LDAP email addresses disabled, and you're creating an Exact Match exclusion rule, you'd enter email@example.com as the user's email address to match. If you've enabled Replace domain names in LDAP email addresses, you'd need to use just johndoe. Trying to match firstname.lastname@example.org won't work, because @company.com is stripped prior to the comparison.
When provisioning groups using GCDS, you can't nest dynamic groups underneath static groups (or static groups underneath dynamic groups). GCDS requires static groups to be queried separately from dynamic groups, however all nested groups have to be a part of the same query.
Find a way to implement dynamic groups as static groups, possibly by automating a task that periodically queries every dynamic group to populate static groups in the directory. GCDS can then use the static groups (as created from the dynamic groups) for provisioning and not provision the dynamic group.
Contacts and calendarsWhy do I see duplicate contacts in my domain directory after syncing with GCDS?
This usually happens if you're syncing shared contacts and the search rules are built incorrectly.
There are 2 types of relevant objects that you can sync with GCDS:
- User profiles—Users in your Google domain with additional data such as a phone number or address. You can only sync a profile for a user that exists in your domain.
- Shared contacts—Contacts of external parties that users in your domain need to contact.
To resolve this issue, correct your shared contact search rules to exclude users in your own domain. On the next sync, GCDS attempts to delete the redundant contacts. You might need to adjust the shared contact deletion limit for that first sync.
In some circumstances, users don't see their main work location in Google Calendar when scheduling or arranging meetings.
If you see this issue, make sure that the location type and area attributes are set to "desk."
RulesWhy is a search rule not finding anything?
Check the scope of the rule. You might need to set the scope to SUBTREE.
You may be using a font that is too large for the screen. The dialog box does not work with large or extra large fonts. Change your font size or edit your XML file directly.