Академический Документы
Профессиональный Документы
Культура Документы
Administration Guide
28 January 2009
3
4 Release 1.3.25, January 2009
Contents
Chapter 2: Introduction 9
About Google Apps Directory Sync 9
Features and Benefits 9
Comparison with Directory Sync Hosted Edition 10
Architecture 11
Utility Overview 13
Chapter 3: Preparation 15
About Preparation 15
Overview 15
Checklist: Before You Begin 16
Useful LDAP Tools 18
Softerra LDAP Administrator 18
JXplorer 18
LDAP Queries 18
Syntax 19
Common LDAP Queries 19
Planning for Large or Complex Deployments 21
Chapter 4: Installation 23
About Installation 23
System Requirements 24
Install Google Apps Directory Sync 24
Upgrade Google Apps Directory Sync 25
Uninstall Google Apps Directory Sync 26
Chapter 5: Configuration 27
About Configuration 27
Configuration Files 28
Message Security Service Settings 29
Message Security Service Authentication 30
Contents 5
Message Security Service Orgs 32
Exclusion Filters for Service Settings 33
Sample Message Security Exclusion Rules 35
LDAP Settings 37
LDAP Connection 38
LDAP Users 40
LDAP User Attributes 41
LDAP User Sync 43
LDAP User Exclusion Rules 47
Sample LDAP User Exclusion Rules 50
LDAP Mailing List Overview 51
LDAP Mailing List Sync 53
LDAP Mailing List Exclusion Rules 55
Sample LDAP User Exclusion Rules 57
Notifications 58
Delete Limits 60
Log Files 62
Simulate Sync 63
Simulate Sync 63
Chapter 6: Synchronization 67
About Synchronization 67
Command Line Synchronization 67
Synchronization options 68
Scheduling Synchronization 69
Microsoft Windows: Scheduled Tasks 69
Linux and Solaris: cron 70
Chapter 7: Troubleshooting 71
About Troubleshooting 71
Common Issues 71
System Tests 73
Escalating Problems 74
• Basic steps for installing the directory sync utility on your mail server.
• Synchronizing users.
This guide is intended for mail server administrators who are already familiar with
mail server configuration and the message security service.
Related Documentation
For additional information about the message security service and related
products, refer to the following documents.
Document Description
7
Document Description
postini-doc_comments@google.com
Please specify in your email message the section to which your comment applies.
If you want to receive a response to your comments, ensure that you include your
name and contact information.
Introduction Chapter 2
The directory sync utility runs on a server machine in your network environment.
You can use any machine that is able to connect to your LDAP server and the
message security service.
• A local on-site utility that runs in your server environment. No machine outside
your perimeter will access your LDAP server.
Introduction 9
Comparison with Directory Sync Hosted Edition
Google Apps Directory Sync is a separate utility run on your server, and is
different from the Directory Sync Hosted Edition feature found in the
Administration Console.
Because of the functional advantages and ease of use, Google Apps Directory
Sync is recommended over Directory Sync Hosted Edition for most
administrators.
Both Google Apps Directory Sync and Directory Sync Hosted Edition synchronize
your LDAP server with your user list in the message security service, but they
work in very different ways.
Pushes changes to the message Pulls changes from your DSML server.
Direction of Data Flow security service.
Your firewall must allow outgoing Your firewall must allow incoming
HTTPS connections to the message HTTPS connections to your DSML
Firewall Settings security service. server.
WARNING: Google Apps Directory Sync and Directory Sync Hosted Edition are
two distinct ways to synchronize. They are not designed to work together. Using
both at the same time could cause unexpected or contradictory results.
This guide describes Google Apps Directory Sync. For more information about
Directory Sync Hosted Edition, see About Directory Sync in the Message Security
Administration Guide and the Configuration Guide for Postini Directory Sync.
The following steps describe how the data flow of directory sync works.
1. The directory sync utility connects to your LDAP server (via port 389 or
another port you specify) and generates a list of users on your directory. You
can set up rules to specify how this user list is generated.
2. The directory sync utility connects to the message security service (via port
8080 if you are using a proxy server, or otherwise port 443) and generates a
list of registered users in the message security service. You can set up rules
to specify how this user list is generated.
Introduction 11
3. The directory sync utility compares the two lists, and generates a list of
changes.
4. The directory sync utility then updates the message security service to match
your LDAP server settings.
• Scheduling - Once you have used sync-cmd successfully, use your operating
system’s scheduling functionality to schedule future synchronization.
Depending on the server you use, this might be a cron job, a Windows
Scheduled Service utility, or any other scheduling tool. For more information,
see “Synchronization” on page 67.
Introduction 13
14 Release 1.3.25, January 2009
Chapter 3
Preparation Chapter 3
About Preparation
Successful deployment of Google Apps Directory Sync requires planning.
Many steps in the configuration and synchronization process assume you already
have key information about your LDAP directory server, mail server, and message
security service organization structure.
This chapter includes a checklist of things you’ll need before you begin, LDAP
browser information, some sample LDAP queries, and a discussion of special
considerations for large deployments.
Overview
A typical setup for Google Apps Directory Sync involves the following steps:
1. Collect required information about your LDAP server and the message
security service.
6. When the simulation is successful, save your final copy of the configuration
file and exit Configuration Manager.
7. In the command line, run a manual synchronization with the configuration file
you created to update the message security service.
Preparation 15
Checklist: Before You Begin
Before you configure synchronization, gather the information you need from the
message security service, as well as your own LDAP server and mail server.
Use this checklist to be sure you have the information you need:
• LDAP Base DN
• LDAP Administrator
• LDAP Queries
• Org Mapping
• Mail Server
Note: The directory sync utility does not create these organizations, so you will
need to add them beforehand.
Collect the structure and exact org names from the Administration Console:
LDAP Base DN: The directory sync utility will use this Base DN as the top level
for all LDAP queries. You can use an LDAP browser to collect this information. If
your LDAP directory server includes OUs that you do not want to sync, consider a
base DN that doesn’t include these OUs. A typical Base DN might be
ou=test,ou=sales,ou=melbourne,dc=ad,dc=mixateria,dc=com for a domain
called ad.mixteria.com.
Note: Each configuration file can only use one base DN. If you need to use
multiple base DNs, run separate synchronizations with separate XML
configuration files.
LDAP Queries: Decide which users to synchronization from your LDAP directory
server, and create one or more LDAP queries that will find those users. For more
information, see “LDAP Queries” on page 18.
Org Mapping: Plan which users will go into which organizations in the message
security service. You want to be sure that your org hierarchy includes special
organizations for users who should not be synchronized, so those users won’t be
deleted. Decide which users go in which organizations. If you want to specify
different organizations for many different users, you can populate a user attribute
on your LDAP directory server that shows the exact name of the message
security service organization for that user. This requires changing your LDAP
settings.
Mail Server: The SMTP mail server to use for notifications. The directory sync
utility does not include an outbound mail server, and will connect to the mail server
you specify. You will need the domain name or IP address of a mail server that will
relay messages from the directory sync server. If the SMTP server you plan to use
requires SMTP authentication, you will need to find or create a username and
password for SMTP authentication as well.
Once you have collected this information and decided on how you want to
synchronize users in different organizations, you’re ready to begin with
Configuration Manager.
If you begin using Configuration Manager and find you need more information,
save your configuration file. You can return to Configuration Manager and load
your XML file after you collect the needed information.
Preparation 17
Useful LDAP Tools
By default, most LDAP directory servers do not include a way to view or modify
your LDAP structure directly. To collect information about your LDAP structure,
download and install an LDAP browser. Two such browsers are listed below.
Note that these are third-party browsers, and this document does not include
instructions or support on the use of an LDAP browser.
http://www.ldapbrowser.com
JXplorer
To download the JXplorer Java Ldap Browser, go to:
http://www.jxplorer.org
LDAP Queries
The directory sync utility uses the LDAP query language to gather information
from your directory server. The LDAP query language is a flexible standard that
supports complex and powerful logical queries.
To build your LDAP queries, you will need to know your LDAP structure. The best
way to collect directory server information is an LDAP browser. For more
information, see “Useful LDAP Tools” on page 18.
Google Apps Directory Sync strictly adheres to RFC 2254, which defines
international standards on LDAP filters.
Most of the search rules in the directory sync utility use LDAP queries for
information. The only exception to this are Exception Rules, which use substring
or regular expressions based on the text of email addresses, not LDAP fields.
Note: The support team cannot write LDAP queries for your environment or debug
your LDAP queries. While this document lists the most common queries, every
directory server is different, and many store information in different fields or
formats. To develop these queries, consult standard LDAP documentation and
review your LDAP structure with an LDAP browser.
Name of
Operator Character Use
For examples of how these operators are used, see the common LDAP queries
below.
objectclass=*.
(&(objectclass=user)(objectcategory=person))
(objectcategory=group)
(objectcategory=publicfolder)
Preparation 19
All user objects except for ones with primary email addresses that begin with
test
(&(&(objectclass=user)(objectcategory=person))(!(mail=test*)))
All user objects except for ones with primary email addresses that end with test
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test)))
All user objects except for ones with primary email addresses that contain the
word “test”
(&(&(objectclass=user)(objectcategory=person))(!(mail=*test*)))
All user objects (users and aliases) that are designated as a “person” and all
group objects (distribution lists)
(|(&(objectclass=user)(objectcategory=person))(objectcategory=grou
p))
All user objects that are designated as a “person”, all group objects and all
contacts, except those with any value defined for extensionAttribute9:
(&(|(|(&(objectclass=user)(objectcategory=person))(objectcategory=
group))(objectclass=contact))(!(extensionAttribute9=*)))
(&(&(objectclass=user)(objectcategory=person))(!(userAccountContro
l=514)))
(objectClass=person)
(&(objectclass=user)(objectcategory=person))
(objectClass=inetOrgPerson)
(objectClass=dominoPerson)
Lotus Domino LDAP: All objects with a mail address defined that are designated
as a “person “or “group”:
(&(|(objectclass=dominoPerson)(objectclass=dominoGroup)(objectclas
s=dominoServerMailInDatabase))(mail=*))
When you set up multiple configuration files for a large deployment, consider the
following:
• You must include some kind of LDAP user search in every configuration file.
• The directory sync utility can move users from other organizations to
complete synchronization.
If your organization has multiple LDAP servers, or multiple base DNs, set up
separate XML configuration files and run separate synchronizations. Create a
separate organization in the message security service Administration Console for
each separate LDAP server or base DN.
Preparation 21
22 Release 1.3.25, January 2009
Chapter 4
Installation Chapter 4
About Installation
To run Google Apps Directory Sync, install the directory sync utility on your server.
The directory sync utility is designed to run on Windows, Linux or Solaris
machines.
The installer is an executable program that installs all needed components on the
server, including managing libraries, classpath variables, and other components.
The installer also uninstalls any existing version of the directory sync utility in the
same directory.
The sections below contain instructions on how to install, upgrade or uninstall the
directory sync utility on your server.
Installation 23
System Requirements
Using Google Apps Directory Sync requires the following:
• Sufficient disk space on the server. You should have at least 5G of disk space
for log files and data. If you are running with DEBUG or INFO level of logging,
you may need more free space than this for additional log data.
• Sufficient memory on the server. The minimum amount of RAM needed to run
the tool is 256MB free. Suggested is 1G free if you have less than 10,000
users, 2G free if you have more than 10,000 users. For very large
organizations (over 250,000) further tuning may be needed.
• A mail server able to accept and relay notifications from the directory sync
utility.
2. Choose the operating system of the server where you plan to run the directory
sync utility.
4. When you have completed all the steps of the installer, the directory sync
utility has been installed.
The installer contains all needed components and can be run offline without any
outside connection.
Installation 25
You can also update manually. The latest version of the directory sync utility is
always accessible on the Google Apps Directory Sync website. To upgrade to the
latest version, go to this site, and download and run the directory sync utility.
The installer wizard automatically detects and uninstalls previous versions of the
software in the same directory.
2. Choose the operating system of the server where you plan to run the directory
sync utility.
1. Open a command line interface and go to the directory that contains the
directory sync utility
All directory sync utility files and all libraries not used by other programs will be
removed. Log files and XML configuration files will not be deleted.
Configuration Chapter 5
About Configuration
Configuration Manager is a step-by-step graphical user interface that walks you
through creating and testing an XML configuration file for Google Apps Directory
Sync.
Note: Before you use Configuration Manager, collect information about your LDAP
directory server and your message security service organizations. For more
information, see “Checklist: Before You Begin” on page 16.‘
Once you have set up your configuration in Configuration Manager, you can run
your actual synchronization from the command line. See “Synchronization” on
page 67.
Configuration Manager does not change the data in your LDAP directory server or
the message security service. It is strictly used to configure and simulate
synchronization.
Google Apps Directory Sync settings are stored as XML configuration files.
Configuration Manager can also load and edit existing configuration files for the
directory sync utility.
Configuration Manager walks you through each step of configuring Google Apps
Directory Sync. Once you have finished each page, click Next to go to the next
step. You can also go back to previous steps with the Previous button, or jump
directly to any step using the left side navigation menu.
Configuration 27
The directory sync utility includes several ways to customize search rules and
filters. When collecting information from your LDAP server, you can define LDAP
queries to extract information. The directory sync utility supports RFC 2254, the
international standard on LDAP Filters. For the details, see RFC 2254:
http://www.ietf.org/rfc/rfc2254.txt
The directory sync utility also includes some non-LDAP filters. In these, you can
use regular expressions to filter for patterns of text. Regular expressions use
standard Java regular expression syntax, which is similar to most standard regular
expression syntax standards.
Configuration Files
In Configuration Manager, you can save or load configuration files to manage
multiple configuration files and store settings for later. All configuration files are
XML files.
To save configuration settings under a new name, select File->Save As from the
top menu and specify the directory and filename you wish to use. If you overwrite
an existing file, Configuration Manager will save the existing file as a copy with the
timestamp in the file name.
To save configuration settings under the existing name, select File->Save from
the top menu. If you haven’t saved yet, this option will be greyed out. If you
overwrite an existing file, Configuration Manager will save the previous file as a
copy with the timestamp of when the file was overwritten.
To open a configuration file, select File->Open from the top menu and choose the
configuration file. The user interface will then show the settings for that
configuration file. To open a recent configuration file, select File->Open Recent
and choose the configuration file.
To start a new configuration file, select File->New from the top menu.
Configuration Manager will load a new file with no configuration rules specified.
Before you enter information in the Message Security Service Settings pages,
collect the information from the message security service. You may need to create
new organizations or administrators in the message security service.
Configuration 29
Message Security Service Authentication
Enter your message security service login and connection information in this
section.
Admin Email The email address used to log into the Administration
Console. This address should be a valid user on the
Administration Console with administrative privileges
over the user organizations you want to synchronize.
Example: admin@mixateria.com
Example: swordFISH23
Example: Password
SSL Proxy Host If your server is running behind a firewall that requires
Name an SSL Proxy to connect to an outside server, enter
the proxy host name here.
(if needed)
If you can connect directly to the internet from this
machine, leave this field blank.
Example: httpproxy.mixateriacorp.com
SSL Proxy Host Port If your server is running behind a firewall that requires
an SSL Proxy to connect to an outside server, enter
(if needed) the proxy host port here. Otherwise, leave this field
blank. The usual port for SSL proxy is 8080.
Example: 8080
Test Connection
Once you have configured Server settings, click Test Connection. Configuration
Manager will connect to the message security service and attempt to log in.
If the test fails, verify your admin email and password, and confirm that you are
able to connect to the Internet from the machine.
Configuration 31
Message Security Service Orgs
On this page, specify which orgs in the message security service to synchronize.
The directory sync utility will use these orgs to generate user lists as a basis for
comparison with your LDAP user list.
Any existing user in the specified orgs will be deleted if they are not in the user list
generated from your LDAP server. Any users not in these orgs will be added (or
moved from another org) if they are in the user list generated from your LDAP
server. After synchronization, your users in the message security service will be
the same as your users on your LDAP server. You make exceptions to this
behavior by using exclusion filters.
• All users in all orgs under your Postini account: All organizations visible
to the administrator account (specified in the Server section) are included in
synchronization.
• Default users
• Administrators who are not in your LDAP system in the OUs you specify
• Users in the message security service who are listed on a different LDAP
server
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
This page shows the list of exclusion filters. In a new configuration, this will
contain two filters for default users. To add new exclusion filters, click the Add
Exclusion Filter button at the bottom of the screen.
On the list of Exclusion Filters, you can change existing filters as follows:
• Reorganize: Click the up arrow or down arrow icon to change the order of
exclusion filters.
• Edit: Click the notepad icon to edit the settings of an exclusion filter.
Configuration 33
Add Exclusion Filter
Click Add Exclusion Filter at the bottom of the page to exclude a user or
organization from synchronization.
Configuration 35
Default Users
If your search includes your pdefault users, the directory sync utility will try to
delete these users unless they are in your LDAP server. Therefore, every new
configuration file includes the following two exclusion filters when created.
First rule:
Second rule:
Special Administrations
If you have administrative accounts on the message security service that are not
part of your LDAP query, you may want to exclude them from synchronization so
they won’t be moved or deleted.
First rule:
Second rule:
• Rule: virus.administrator@mixateria.com
If you have a separate organization devoted to mailing lists, and you want to
exclude it from synchronization, create an org rule. Note the exact organization
name from the Administration Console.
The company has two other offices with separate LDAP servers. The three offices
have intermingled org structures, but all orgs in the other two offices are labeled
as “Dubai” or “London” in the org name in the Administration Console.
LDAP Settings
The LDAP Settings section configures how the directory sync utility connects to
your LDAP directory server and generates your LDAP user list for comparison.
You may need to collect information from your LDAP directory server before you
can enter details in this section.
Configuration 37
LDAP Connection
Specify your LDAP connection and authentication in this page.
LDAP Connection
Setting Description
Example: Standard
Example: 389
Example:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=mixateri
a,dc=com
Example: Simple
Authorized User Enter the user to use when connecting to the server.
This user should have read and execute permissions
for the whole subtree.
Example: admin1
Example: swordfish
Test Connection
Once you have configured LDAP Authentication settings, click Test Connection.
Configuration Manager will connect to your LDAP server and attempt to log in, to
verify the settings you entered.
Configuration 39
LDAP Users
The LDAP Settings section configures how Google Apps Directory Sync
generates your LDAP user list for comparison. You may need to collect
information from your LDAP directory server before you can enter details in this
section.
Note: You must add at least one LDAP User Sync rule to run Google Apps
Directory Sync. This determines which users are synchronized and added in the
message security service.
Server Type The type of LDAP server that you are using with the
directory sync utility.
Configuration 41
LDAP User Attribute
Setting Description
Example: sAMAccountName
Example: mail
Example: proxyAddresses
Domino Alias Only for Lotus Domino servers. One or more attributes
Address Attribute used to hold internal Domino alias attributes, which are
stored as usernames without domain information.
(if needed) These addresses will be formatted as email addresses
and placed as aliases to the primary address listed in
the Email Address Attribute field.
Example: uid
Click this button to use the default values for your server type, as follows:
By default, all users that match these search rules will be added to the message
security service user list (or moved if they are in a different organization) and all
users that do not match these search rules will be removed. You can change this
behavior with exclusion filters.
This page shows the list of search rules. In a new configuration, this will be an
empty list. To add a search rule, click the Add Search Rule button at the bottom
of the screen.
Note: You cannot create an LDAP rule to exclude a specific OU in your LDAP
directory. Instead, limit the authority of the LDAP Administrator you use, removing
access to any OUs you do not want to synchronize.
Configuration 43
On the list of Search Rules, you can change existing rules:
• Reorganize: Click the up arrow or down arrow icon to change the order of
search rules.
• Edit: Click the notepad icon to edit the settings of a search rule.
Search rules are processed in the order listed. If you would like one search rule to
take priority over another, move that search rule up using the up arrow icon on this
page. If two rules contradict each other, the first rule takes precedence.
Org Name Select Org Name or Org name defined by this LDAP
attribute and enter an appropriate value.
Org name defined Select Org Name or Org name defined by this LDAP
by this LDAP attribute and enter an appropriate value.
attribute
For each user, the directory sync utility reads the value
an LDAP attribute you specify, and adds the user to the
message security service organization specified in this
LDAP attribute.
Example: extensionAttribute5
Configuration 45
LDAP User Sync
Setting Description
Use Default Filter Only usable if you are using “Org name defined by
this LDAP attribute.”
(optional)
The “use default filter” check box sets the scope to
“Subtree” and the rule to objectclass=*.
Example: Subtree
Rule This is the search rule used. This rule uses standard
LDAP filtering language, and allows sophisticated logic
and complex rules for searching. For more information
about LDAP search filters, see “LDAP Queries” on
page 18.
objectclass=*.
• For OpenLDAP:
(objectClass=inetOrgPerson)
Configuration 47
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
Note: To exclude individual users, add a separate rule for each user.
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click the Add Exclusion Filter button at the
bottom of the screen.
On the list of Exclusion Filters, you can change existing filters as follows:
• Reorganize: Click the up arrow or down arrow icon to change the order of
exclusion filters.
• Edit: Click the notepad icon to edit the settings of an exclusion filter.
Click the Add Exclusion Filter at the bottom of the page to exclude a user or
organization in your LDAP server from synchronization.
Configuration 49
Exclusion Rule Setting Description
Examples:
In this example, printers are listed as LDAP users and would match the LDAP
query given. However, the printers all have the word “printer” in the name. The
rule looks for that substring.
• Rule: printer
Two users have opted out of mail filtering and should not be synchronized.
• Rule: atif@mixateria.com
Second rule:
• Rule: svetlana@mixateria.com
About five hundred test users are listed in LDAP, but they are only used for
internal load testing. All the test users follow the same name pattern: internal-
testX, where X is a number, and all test users are in the same domain.
• Rule: internal-test[0-9]*@mixateria.com
Configuration 51
Mailing lists are often handled separately, because if a mailing list is added as a
user, all recipients of the mailing list will receive notifications. This can cause
confusion. To avoid this problem, Google Apps Directory Sync can import mailing
lists as aliases to a user you specify.
This section is optional. Fill out the information in this section if you wish to import
mailing lists as aliases to a central user in the message security service.
This page shows the list of LDAP mail list rules. In a new configuration, this will be
an empty list. To add mail lists, click the Add Mail List button at the bottom of the
screen.
On the list of Mail List rules, you can change existing filters as follows:
• Reorganize: Click the up arrow or down arrow icon to change the order of
exclusion filters.
• Edit: Click the notepad icon to edit the settings of an exclusion filter.
Configuration 53
Add Mail List
Click the Add Mail List at the bottom of the page to synchronize one or more
addresses as mailing lists.
Mail list owner The email address of the user who will manage the
mailing list. If this user is not a user in the message
security service, the directory sync utility will add this
user in the specified Mail list owner org.
Example: admin@mixateria.com
Mail list owner org If the mailing list owner does not exist on your LDAP
server, the directory sync utility will add it to this
organization. If the mailing list owner already exists this
field is not used.
Scope Where to apply the mail list rule. This could be a whole
subtree, a single level, or a single object.
Example: Subtree
Rule This is the search rule used. This rule uses standard
LDAP filtering language, and allows sophisticated logic
and complex rules for searching. For more information
about LDAP search filter language, consult your LDAP
documentation.
Example: (objectclass=dominoGroup)
If you have any entries in your directory server that match a mail list rule, but
should not be treated as a mailing list, list them here. This might include:
• Mailing lists that should be treated as individual users, with separate archives
and quarantines.
Configuration 55
Exclusion rules are based on string values and regular expressions, not LDAP
settings.
This page shows the list of exclusion filters. In a new configuration, this will be an
empty list. To add exclusion filters, click the Add Exclusion Filter button at the
bottom of the screen.
On the list of exclusion filters, you can change existing filters as follows:
• Reorganize: Click the up arrow or down arrow icon to change the order of
exclusion filters.
• Edit: Click the notepad icon to edit the settings of an exclusion filter.
Click Add Exclusion Filter at the bottom of the page to prevent an address from
being treated as a mailing list.
Configuration 57
Sample Substring Match: Internal Mailing Lists
Several mailing lists are devoted to internal use only. Those lists all have “internal”
in the address.
• Rule: internal
Three small-distribution mailing lists are top security and should not be archived
with other mailing lists.
First rule:
• Rule: finance-early-statements@mixateria.com
Second rule:
• Rule: internal-security@mixateria.com
Third rule:
• Rule: legal-confidential@mixateria.com
About five hundred test users are listed in LDAP, but they are only used for
internal load testing. All the test users follow the same name pattern: internal-
testX, where X is a number, and all test users are in the same domain.
• Rule: internal-test[0-9]*@mixateria.com
Notifications
You can set Configuration Manager so that every time synchronization occurs,
Google Apps Directory Sync will send out a notification to a list of users.
Send notifications Enter the “From:” address for the notification mail.
from address Recipients will see this address as the notification
sender. For instance, you might use your own email
address.
Example: dirsync@mixateria.com
Example: dirsync-admins@mixateria.com
Configuration 59
Notifications Setting Description
SMTP Relay Host The SMTP mail server to use for notifications. The
directory sync utility uses this mail server as a relay
host.
Example: mail.mixateria.com
Test Notification
Click this button to test notifications. Configuration Manager will connect to the
SMTP server you specified and send a test notification to the addresses you list.
Delete Limits
As a safeguard, you can limit how many users Google Apps Directory Sync can
delete during synchronization. This is recommended as a way to prevent
accidental mass deletion.
Note: Delete limits apply during synchronization, but not during simulation.
Simulation results will not include delete limits.
Example: 5%
Configuration 61
Log Files
You can specify the file name and level of detail of logging for Google Apps
Directory Sync.
File name Enter the directory and file name to use for the log file
or click Browse to browse your file system.
Example: sync.log
Log Detail The level of detail of the log. Options are FATAL,
ERROR, WARN, INFO, DEBUG, and TRACE.
Maximum Log Size The maximum size of the log file, in gigabytes. When
this file reaches half capacity, it is saved as a backup
file (which overwrites any existing backup file) and a
new file is created. At any time, the total size of these
two files (the log file and the backup log file) will not
exceed the total maximum size.
Example: 4
Simulate Sync
After you enter configuration information, use this section to verify and test your
Google Apps Directory Sync settings.
Note: Configuration Manager does not check for valid LDAP syntax. To find invalid
LDAP queries, use Simulate Sync. Invalid LDAP queries will cause errors.
Simulate Sync
When you first go to this page, you will see Validation Results. This page will show
a checklist of all the Configuration Manager sections. If you are missing required
information, you will see error messages showing what needs to be added.
Important: This checklist confirms only the minimum needed for synchronization.
You may need to configure additional filters or rules to be sure the results are what
you expect.
Configuration 63
Once you’ve completed all required fields, you will be able to use the Simulate
Sync button to simulate a synchronization.
Once you’re ready, click Simulate Sync. You will see the Simulate Sync page.
• Connect to the message security service and generate a registered user list.
Note: Simulate Sync will never update or change your LDAP server or your users
in the message security service. The simulation is strictly for configuration and
testing. To run an actual synchronization, use the command line. See
“Synchronization” on page 67 for more.
If any errors occur, check the error text. Most error text is human readable, but
some error text may contain Java stack trace errors. If you need help
troubleshooting these errors, see “Troubleshooting” on page 71.
If the synchronization was successful, check the Proposed Change Report and
review it for unexpected results.
Note: The Proposed Change Report doesn’t check your delete limits.
If you see any errors or unexpected results, you can go back and change your
configuration to try again. To change your configuration, click on any of the
headings on the left navigation bar.
You can switch between the Validation Results and Simulation Results pages
using the buttons at the bottom of the page. You can also run another simulation
from either page by clicking the Simulate Sync button at the bottom.
Once you are finished, save your configuration file and run synchronization. See
“Synchronization” on page 67.
Configuration 65
66 Release 1.3.25, January 2009
Chapter 6
Synchronization Chapter 6
About Synchronization
Run the synchronization command to push your LDAP directory server user
information to the message security service.
The directory sync utility uses the command sync-cmd to run synchronization.
This simple command line interface gives you the flexibility to incorporate
synchronization into any scheduling or batch script you wish to use.
Before you can synchronize the message security service with your LDAP
directory server, you must create rules that detail how to connect to both servers,
and what filters and rules to use. These rules are stored in an XML file. To create
this XML file, run Configuration Manager. For more information about
Configuration Manager, see “Configuration” on page 27.
Most administrators run their first synchronization manually to test the process,
import an initial set of users, and confirm the changes. After initial synchronization
with the command line, you can set up automatic scheduling for future
synchronization.
sync-cmd
Run without any arguments, this command gives an error and directs you to run
sync-cmd -h for help.
sync-cmd -a -c [filename]
Synchronization 67
Replace [filename] with the name of the XML file you created in the
Configuration Manager.
Synchronization options
The table below describes the possible arguments to the sync-cmd command. You
can also see this information by running the following:
sync-cmd -h
Option Values
Scheduling Synchronization
Once you have successfully run a manual synchronization, you can set up
automatic synchronization. Use existing third-party scheduling software to
automate synchronization.
In most cases, scheduling twice a week is recommended. The exact timing will
vary based on the number of users you have and how often you need to update
them. A large company with many users changing frequently may need to run the
directory sync utility daily, while a small company with few changes may not need
to run the utility more than once a week.
The exact method to schedule this task depends on the operating system in which
the directory sync utility is installed. In Microsoft Windows, use Scheduled Tasks.
In Linux or Solaris, use cron. Steps for how to do this are listed below. You can
also use any other scheduling software that can launch commands from the
command line interface.
To schedule a task
Synchronization 69
3. Complete the Scheduled Task wizard using the following information. (Steps
may vary depending on your version of Microsoft Windows.)
Replace [path] with the path where the directory sync utility was
installed. Replace [filename] with the name of the XML file you created
in the Configuration Manager.
4. Test the scheduled task by running manually once. In the Scheduled Tasks
window, right-click the task you created and select Run from the right-click
menu. Check the log file for errors.
Note: These steps apply to most common Linux and Solaris configurations. Linux
and Solaris are third-party products and are not supported directly by the Google
(or Postini) team. In the event of an issue with cron, contact your administrator.
The syntax of this line will depend on your operating system and version of
cron. For instance, to schedule the task to run at 3:30 AM twice per week, on
Monday and Thursday, add the following entry:
30 3 * * 1,4 [path]/sync-cmd -a -c [filename]
Replace [path] with the path where the directory sync utility was
installed.Replace [filename] with the name of the XML file you created in the
Configuration Manager.
Troubleshooting Chapter 7
About Troubleshooting
This chapter covers information about how to troubleshoot problems that may
occur with Google Apps Directory Sync.
For information about LDAP queries, see “LDAP Queries” on page 18.
Common Issues
The following describes common issues and questions related to Google Apps
Directory Sync.
Check the scope of the rule. You may need to set the scope to SUBTREE.
Check the Mailing List Attribute in LDAP Configuration. This is the field that
contains the email address of a mailing list. In most cases, this will be mail.
The proxy environment requires a password challenge for external web access.
The directory sync utility can use a proxy server but cannot respond to password
challenges. To run synchronization, you will need to change your network setup to
allow the directory sync utility to connect without a password challenge, or without
a proxy server.
Troubleshooting 71
How do I find out information about my LDAP server fields?
You will need to download an LDAP browser. An LDAP browser allows you to
browse through an LDAP directory server and identify all fields and values. Most
directory servers do not include a complete LDAP browser.
For information about LDAP browsers, see “Useful LDAP Tools” on page 18.
This is a change from previous versions. Before 1.3.11, passwords were stored
unencrypted in plain text in configuration files.
You can also upgrade the file with the following command-line executable:
upgrade-config -c [filename]
Note: Configuration files for version 1.3.11 or later are not compatible with earlier
versions.
You cannot create an LDAP rule to exclude users in a specific LDAP organization.
Instead, limit the authority of the LDAP Administrator you use, removing access to
any OUs you do not want to synchronize.
Is there a way to change the Non-Address Primary Key Attribute for users
manually once the directory sync utility has synced users in the message
security service?
The purpose of this field is to store something stable and unique from LDAP
directory and then use that to compare users later.
If you use the optional field for Non-Address Primary Key Attribute, and then you
change this attribute to something other than the original Non-Address Primary
Key Attribute, the directory sync utility will delete users and add them again.
After a user is deleted, then added again, non-fatal errors occur during
synchronization.
You can safely ignore non-fatal error messages that directory sync tried to add an
alias that already exists.
The directory sync utility preserves alias information after deleting a user, and
keeps that information for a period of time. If the user is added again, the user still
has all the same aliases, which can cause a warning message when the directory
sync utility tries to add them again.
Some users on the LDAP server have aliases in another domain that is not listed
in the message security service. Is there a way to exclude aliases from
synchronization?
No. The directory sync utility will attempt to add these aliases and fail. If this
happens, you can safely ignore the warning messages.
How can I set up the directory sync utility to use a Global Catalog?
Set Configuration Manager to connect to port 3268 instead of 389. You will also
need to set up your LDAP scope and queries appropriately for the Global Catalog.
For more information on appropriate LDAP queries for a Global Catalog, see your
LDAP server documentation or contact your LDAP administrator.
System Tests
If you encounter problems, use the tests in Configuration Manager to find the
problem:
1. In Configuration Manager, open the XML file you are using for configuration.
3. Under LDAP Connectons, click Test Connection to confirm you can connect
to your LDAP server.
4. Under Notifications, click Test Notification to confirm you can send a test
notification.
5. Under Simulate Sync, confirm you have filled out all required fields.
If you encounter any problems, note which tests failed and confirm that the
configuration information is correct for those sections of Configuration Manager.
Troubleshooting 73
Escalating Problems
If you are unable to run directory sync, and cannot resolve the problem using
system tests, collect the following information for troubleshooting:
• The most current sync log file, located in the folder where the directory sync
utility is installed.
• The version number of the directory sync utility you are running. You can find
this in the Configuration Manager UI by going to Help->About, or you can run
the command sync-cmd -V.
• The current config file you are using. This is an XML file (default name
sync.xml) located in the same folder where the directory sync utility is
installed.
• The brand and version of the LDAP directory server you're using.
• The operating system on the machine where the directory sync utility is
running.
Once you have collected this information, escalate this using your normal support
channels. For more information about support for the directory sync utility, see the
Google Apps Directory Sync site:
http://www.postini.com/dir_sync