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.
Configuration issuesTroubleshoot 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 are 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.
Log file errorsCertificate-related errors
If you see
sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target errors in your GCDS log file, it indicates that GCDS can't verify the certificate that's presented by the server because it isn't signed by a Certificate Authority (CA) that GCDS trusts. GCDS uses Java® trusted root CA certificates, so even 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.
- Enter certutil -store My DomainController dccert.cer and press Enter to export the domain controller's certificate.
- Copy the dccert.cer file 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: cd ~/GoogleCloudDirSync/jre
- For Windows: cd "c:\Program Files\Google Cloud Directory Sync\jre"
- Enter one of the following commands:
For Windows: bin\keytool -keystore lib\security\cacerts -storepass changeit -import -file c:\dccert.cer -alias mydc
For Linux: 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 may 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 enabled by default 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.
Deployment issuesWhat if I'm seeing memory-related errors?
If you are seeing memory-related errors, you'll need to increase the heap size for Java® Virtual Machine. You increase the heap size by editing the sync-cmd.vmoptions and 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)
You must edit both the
config-manager.vmoptions files so that the change applies apply 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 available, and how much memory GCDS needs for a synchronization. You may need to revise the number several times to set the correct size. See System requirements for GCDS for more information on the amount of free RAM required to run GCDS.
To synchronize group members separately from the results of any user search rules, GCDS enables the INDEPENDENT_GROUP_SYNC option by default. If you are 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 purposes.
GCDS needs to validate Secure Sockets Layer (SSL) certificates when connecting to Google APIs (over HTTPS) and LDAP over SSL by connecting via 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 may be needed if you are 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 sync-cmd.vmoptions and config-manager.vmoptions files in the installation directory of GCDS and add these lines:
This usually happens if you are syncing shared contacts and the search rules are built incorrectly.
There are two 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 may need to adjust the shared contact deletion limit for that first sync.
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.
Check the scope of the rule. You may need to set the scope to SUBTREE.
Make sure you have selected MS Active Directory in the server type field of the LDAP Configuration section.
To run a simulated synchronization, you will need a server capable of sending mail. If you are 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. You should 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 is not running with either sync-cmd or Configuration Manager.
- Navigate to the GCDS installation folder.
- Edit the file jre/lib/logging.properties.
- 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 will be created in homedir (Linux) or profile folder (Windows). Archive these files together, as they may be quite big.
- Delete the lines added in step 3 to prevent large log files being created in the future.
Then, provide the following files:
- The XML file used.
- The trace-level logs from the latest sync.
- The gcdshttp*.log files 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.
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.
See here 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.
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 are 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 the @company.com part will be 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 in order 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.
This may 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 may clear the cache more frequently, depending on the cached data size. However, if the cache isn't cleared, you may 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 -f to 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.