Work with configuration files

In Configuration Manager, you can save or load configuration files to store Google Cloud Directory Sync (GCDS) synchronization settings for later. All configuration files are in XML format.

Store your configuration files securely. Exposed configuration files are a security risk.

Start or save a configuration file

  • To start a new configuration file, select File > New from the top menu. Configuration Manager loads a new file with no configuration rules specified.
  • To save a configuration file  with a new name, select File > Save As and specify the directory and file name.
  • To save a configuration file with an existing name, select File > Save.

If you overwrite an existing file, Configuration Manager saves the existing file as a copy with a timestamp in the file name that indicates when the file was overwritten.

Copy a configuration file

The secrets (password and OAuth token) in the configuration file are encrypted using an encryption key that's stored using the java.util.preferences Java class. This makes it harder for an attacker to obtain access to your LDAP system or your Google domain by using the XML file.

Using the XML file with different machines or users

If you open an XML file that was saved on a different machine, or even as a different user on the same machine, GCDS won't be able to access the secrets in the XML file. You must re-enter them in Configuration manager.


To run GCDS when signing in as multiple users on Windows:

  1. Open Configuration Manager.
  2. Hold down the Shift key and right-click.
  3. Select Run as different user (note that it may be Run as depending on your version of Windows).
  4. Enter the administrator username and password.
  5. Update the passwords and reauthorize OAuth as needed.
  6. Save the XML file.
  7. Run a simulation to ensure that your settings are correct.
  8. Manually run the synchronization and review the logs to ensure that the XML file was saved correctly.

Note: If you are running the sync-cmd task as the Windows SYSTEM user, NetworkService, or another system account, you may not be able to use Run as different user to run the Configuration Manager as that user. Try using PsExec from Microsoft to run Configuration Manager as a system user.


There are 2 ways to move the XML file between Linux machines:

  1. Remove the encrypted information (from the authCredentialsEncrypted and oAuth2RefreshToken fields) and reauthorize GCDS with the the upgrade-config tool. (Note: Currently, there's no way to update smtpAuthPasswordEncrypted).
  2. Move the prefs file from the original machine to the new destination machine. The prefs files is stored by default in the following location: $HOME/.java/.userPrefs/com/google/usersyncapp/util/prefs.xml.

Other configuration file issues

  • If you have a very large deployment, consider using multiple configuration files. This allows you to split the deployment into smaller synchronizations, reduce performance load, and vary the rate of synchronizations.
  • You can run the same configuration file and synchronize groups, users, and organizational units individually. For details, see Schedule synchronization using the command line.
Was this helpful?
How can we improve it?