Google App Dir Sync

Google Apps Directory Sync
Administration Guide
Release 1.3.27, March 2009
Google Message Filtering Google Message Security Google Message Discovery Postini Email Security, Service Provider Edition Postini Email Security, Enterprise Edition
Google, Inc. 1600 Amphitheatre Parkway Mountain View, CA 94043 www.google.com Part number: DSS_1.3.27_11 26 March 2009
Copyright 2009 Google, Inc. All rights reserved. Google, the Google logo, Google Message Filtering, Google Message Security, Google Message Discovery, Postini, the Postini logo, Postini Perimeter Manager, Postini Threat Identification Network (PTIN), Postini Industry Heuristics, and PREEMPT are trademarks, registered trademarks, or service marks of Google, Inc. All other trademarks are the property of their respective owners. Use of any Google solution is governed by the license agreement included in your original contract. Any intellectual property rights relating to the Google services are and shall remain the exclusive property of Google, Inc. and/or its subsidiaries (Google). You may not attempt to decipher, decompile, or develop source code for any Google product or service offering, or knowingly allow others to do so. Google documentation may not be sold, resold, licensed or sublicensed and may not be transferred without the prior written consent of Google. Your right to copy this manual is limited by copyright law. Making copies, adaptations, or compilation works, without prior written authorization of Google. is prohibited by law and constitutes a punishable violation of the law. No part of this manual may be reproduced in whole or in part without the express written consent of Google. Copyright by Google, Inc. Google, Inc. provides this publication as is without warranty of any either express or implied, including but not limited to the implied warranties of merchantability or fitness for a particular purpose. Google, Inc. may revise this publication from time to time without notice. Some jurisdictions do not allow disclaimer of express or implied warranties in certain transactions; therefore, this statement may not apply to you. This software uses the JGoodies Forms, JGoodies Validation, and JGoodies Looks. Copyright (c) 2002-2008 JGoodies Karsten Lentzsch. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: o Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. o Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. o Neither the name of JGoodies Karsten Lentzsch nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. This software uses Apache Derby. Apache Derby Copyright 2004-2007 The Apache Software Foundation This product includes software developed by The Apache Software Foundation (http://www.apache.org/).
Portions of Derby were originally developed by International Business Machines Corporation and are licensed to the Apache Software Foundation under the Software Grant and Corporate Contribution License Agreement, informally known as the Derby CLA. The following copyright notice(s) were affixed to portions of the code with which this file is now or was at one time distributed and are placed here unaltered. (C) Copyright 1997,2004 International Business Machines Corporation. All rights reserved. (C) Copyright IBM Corp. 2003. The portion of the functionTests under 'nist' was originally developed by the National Institute of Standards and Technology (NIST), an agency of the United States Department of Commerce, and adapted by International Business Machines Corporation in accordance with the NIST Software Acknowledgment and Redistribution document at http://www.itl.nist.gov/div897/ctg/sql_form.htm
Contents
About This Guide 7 What This Guide Contains 7 Related Documentation 7 How to Send Comments About This Guide
Chapter 2: Introduction 9 About Google Apps Directory Sync 9 Features and Benefits 9 Comparison with Directory Sync Hosted Edition 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 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
10
21
30
Contents
Message Security Service Orgs 33 Exclusion Filters for Service Settings 34 Sample Message Security Exclusion Rules LDAP Settings 38 LDAP Connection 39 LDAP Users 41 LDAP User Attributes 42 LDAP User Sync 44 LDAP User Exclusion Rules 48 Sample LDAP User Exclusion Rules 51 LDAP Mailing List Overview 52 LDAP Mailing List Sync 54 LDAP Mailing List Exclusion Rules 56 Sample LDAP User Exclusion Rules 58 Notifications 59 Delete Limits 61 Log Files 63 Simulate Sync 64 Simulate Sync 64 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 About Troubleshooting 71 Common Issues 71 System Tests 73 Escalating Problems 74 71
36
About This Guide
What This Guide Contains

The Google Apps Directory Sync Administration Guide provides information about: Google Apps Directory Sync features. Basic steps for installing the directory sync utility on your mail server. Configuration for the directory sync utility. Synchronizing users. Troubleshooting the directory sync utility.
This guide is intended for mail server administrators who are already familiar with mail server configuration and the message security service. This guide is a supplement to the Message Security Administration Guide. For details about using the features and components of the message security service, see the Message Security Administration Guide.
Related Documentation
For additional information about the message security service and related products, refer to the following documents.
Document Description
Message Security Administration Guide
Administration Guide for the message security service. This includes information on users and organizations, message filtering, and other features. The Directory Sync chapter in this guide covers only Directory Sync Hosted Edition.
Document
Description
Directory Sync Configuration Guide
Instructions for setting up your network environment and directory server for Directory Sync Hosted Edition. Directory Sync Hosted Edition is a different feature, that runs on the message security service and requires special configuration on your network to use.
How to Send Comments About This Guide

Google values your feedback. If you have comments about this guide, please send an email message to:
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.
Chapter 2
Introduction
Chapter 2
About Google Apps Directory Sync

Google Apps Directory Sync is a utility that adds, deletes, and moves your users in the message security service to match the user directory on your LDAP server. When you synchronize, any changes on your LDAP server are reflected in the message security service. 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.
Features and Benefits

Google Apps Directory Sync offers the following features and benefits: Updates registered users in the message security service to match your LDAP user list. A local on-site utility that runs in your server environment. No machine outside your perimeter will access your LDAP server. Can be configured to track user primary address changes, keeping quarantines and settings intact even with user address changes. Runs on any Windows (XP or Vista), Linux or Solaris server. All needed components included in installation. Allows sophisticated rules to handle mailing lists, aliases, and exceptions. Allows complex mapping for your org hierarchy. Extensive tests and simulations to ensure correct synchronization.
Introduction
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. This table compares the two methods:
Google Apps Directory Sync Directory Sync Hosted Edition
Runs on a server in your network.

Location
Runs within the message security service. Configure in the Administration Console. Pulls changes from your DSML server. Requires complex installation of third party DSML server on your network. Your firewall must allow incoming HTTPS connections to your DSML server. Connects to your DSML server by HTTPS port 443, which then connects to your LDAP server. Requires administration access on the message security service, and read and execute permissions on your LDAP server. Uses basic authentication or anonymous access. Allows advanced LDAP queries, simple organization mapping, and some exception handling.
Configuration Direction of Data Flow Installation Needed
Configure on your server with the Configuration Manager utility provided. Pushes changes to the message security service. Installation includes all needed components. Your firewall must allow outgoing HTTPS connections to the message security service. Connects directly to your LDAP server using port 389, or a port you specify.
Firewall Settings
Connection
Authorization
Requires administration access on the message security service, and read and execute permissions on your LDAP server. Uses basic authentication. Allows advanced LDAP queries, sophisticated organization mapping, and exception handling.
Complexity
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.
10
Architecture
Google Apps Directory Sync runs on your server and updates the message security service to match your LDAP server. The directory sync utility never updates or changes your LDAP server. 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.
12
Utility Overview
The directory sync utility includes several components, designed to work together. These components are: Configuration Manager - Use this graphical UI to configure how the directory sync utility will connect to the message security service and to your LDAP server. You can also create rules for user lists, search queries, organization mapping, aliases, distribution lists and exceptions. For more information, see Configuration on page 27. XML Configuration File - Save configuration information from Configuration Manager in an XML file. Use this file during synchronization. Synchronization Command Line - Use the command-line utility sync-cmd to perform actual synchronization. This utility uses settings in your XML configuration file to connect to the message security service and your LDAP server, and updates your users and aliases in the message security service. For more information, see Synchronization on page 67. Scheduling - Once you have used sync-cmd successfully, use your operating systems 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
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 youll need before you begin, LDAP browser information, some sample LDAP queries, and a discussion of special considerations for large deployments. For information on system requirements, see System Requirements on page 24.
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. 2. Install the directory sync utility. 3. Step through Configuration Manager to configure synchronization. 4. In Configuration Manager, simulate a synchronization. 5. Revise your configuration in Configuration Manager based on the simulation. This could take several revisions for complex environments. 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. 8. Using your servers scheduling tools, set up automatic scheduled synchronization.
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: Message Security Org Structure Message Security Administrator LDAP Structure Information LDAP Base DN LDAP Administrator LDAP Queries Org Mapping Mail Server
Each item on the checklist is detailed below. Message Security Org Structure: Before you configure synchronization, set up your org hierarchy in the message security service. You should create organizations for all users you want to add. For more information about your org hierarchy, see About the Organization Hierarchy and About Organization Management in the Email Security Administration Guide.
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:
Message Security Administrator: Note the administrator username and password (or Xauth string, if you are using Cross-Authentication) for an administrator on the message security service. The administrator needs read authority for All Standard Privileges, and write authority for all Help Desk and User Settings.
16
LDAP Structure Information: Gather information about your LDAP directory server. You will need to know what OUs contain users you want to sync and which LDAP attributes contain important information. To collect this information, use an LDAP browser. For more information, see Useful LDAP Tools on page 18. 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 doesnt 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 Administrator: Collect the username and password of an administrator on your LDAP directory server. Enter the user to use when connecting to the server. This user should have read and execute permissions for the whole LDAP subtree you want to synchronize. You can restrict the permissions of the administrator to match only the OUs you want to synchronize. 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 wont 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, youre 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.
Softerra LDAP Administrator

To download Softerra LDAP Administrator, go to:
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.
18
Syntax
The following syntax is used in LDAP filters:
Name of Operator
Character
Use
Equals Any Parentheses And Or Not
= * () & | !
Creates a filter which requires a field to have a given value. Wildcard to represent that a field can equal anything except NULL. Separates filters to allow other logical operators to function. Joins filters together. All conditions in the series must be true. Joins filters together. At least one condition in the series must be true. Excludes all objects that match the filter.
For examples of how these operators are used, see the common LDAP queries below.
Common LDAP Queries

The examples below show the most common LDAP queries. These queries are the most common queries used, and are designed to work with most directory server environments.
All objects (this may cause load problems):
objectclass=*.
All user objects that are designated as a person

(&(objectclass=user)(objectcategory=person))
Distribution Lists only

(objectcategory=group)
Public Folders only

(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=*)))
All users, but exclude disabled users:

(&(&(objectclass=user)(objectcategory=person))(!(userAccountContro l=514)))
Active Directory LDAP: All users

(objectClass=person)
Active Directory LDAP: All email users (alternate)

(&(objectclass=user)(objectcategory=person))
OpenLDAP: All users

(objectClass=inetOrgPerson)
Lotus Domino LDAP: All users

(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=*))
20
Planning for Large or Complex Deployments

If your deployment is large enough or complex enough to require multiple configuration files, you may need extra planning and preparation. Synchronizing for a very large or complex organization may require special consideration. This may be the case for two reasons: A complex deployment may include many different sub-groups which need to be synchronized using separate rules or message security service organizations. A large deployment may be system-intensive and may require special work to be sure it runs quickly.
A common way to handle a large deployment is to create multiple configuration files for different parts of your company. This allows greater customization and may speed up your synchronization. When you set up multiple configuration files for a large deployment, consider the following: If you are scheduling synchronization, schedule each configuration file separately. Every configuration file must synchronize to a different organization in the message security service. If two configuration files affect the same organization on the message security service, the directory sync utility may overwrite or delete users. 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.
One particular way to enhance performance is to separate mailing lists to a separate search. If a large synchronization is going slowly, consider creating a separate organization for mailing lists, and running a separate synchronization for that organization. However, remember that you must include some kind of LDAP user search in every configuration file; if youre only synchronizing mailing lists, add a placeholder LDAP search rule that will not return any results, such as (objectclass = thisisnotavalidclass). 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. If you are using multiple configuration files, consider assigning a different administrator to each. Then, set the permissions for
Preparation
21
22
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: A server on which to install Google Apps Directory Sync, running Microsoft Windows (tested on XP and Vista), Linux or Solaris. 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. An LDAP server with user information which is accessible to the directory sync utility. All versions of the LDAP protocol are supported. Read and execute administrative access over the appropriate OU structure of the LDAP server. Network access to the message security service through HTTPS, directly or through a proxy server. An administrator account on the message security service. A mail server able to accept and relay notifications from the directory sync utility.
Install Google Apps Directory Sync

To install the directory sync utility: 1. In a web browser, go to http://www.postini.com/dir_sync. 2. Choose the operating system of the server where you plan to run the directory sync utility.
24
3. Download and run the installer.
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.
Upgrade Google Apps Directory Sync

In Release 1.3.13 or later, Google Apps Directory Sync automatically checks to see if there are any updates available. If updates are available, you will be prompted to upgrade when you start Configuration Manager.
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. Configuration files are backward-compatible. Future versions of the directory sync utility cans run configuration files created in earlier versions. The installer wizard automatically detects and uninstalls previous versions of the software in the same directory. To reinstall the utility. 1. In a web browser, go to http://www.postini.com/dir_sync. 2. Choose the operating system of the server where you plan to run the directory sync utility. 3. Download and run the installer. 4. Select a directory on your server to install the directory sync utility. 5. Complete the installer wizard.
Uninstall Google Apps Directory Sync

The directory sync utility also includes an uninstaller. To remove the directory sync utility: 1. Open a command line interface and go to the directory that contains the directory sync utility 2. Run the following command:
uninstall
3. In the uninstaller, click Next to uninstall the directory sync utility. 4. Once uninstallation has completed close the uninstaller. 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.
26
Chapter 5
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.
In Configuration Manager, you can: Set up and test a connection to the message security service. Configure which users and orgs in the message security service to synchronize. Set up and test a connection to your LDAP server. Configure LDAP search criteria for synchronization. Set up notifications and logging. Run a simulated synchronization to verify your settings.
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 havent 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.
28
Message Security Service Settings

The Message Security Settings section governs how the directory sync utility connects to the message security service, and how the directory sync utility generates your message security service user list for comparison.
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.
Specify the following:

Authentication Setting Description
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. The administrator needs read authority for All Standard Privileges, and write authority for all Help Desk and User Settings. Example: admin@mixateria.com
Password or Xauth Hash String
The password (if using passwords) or XAuth hash string (if using XAuth) for the Admin Email. Example: swordFISH23 Passwords are stored in an encrypted format.
Authentication
The authentication method used. If you have set up XAuth (cross-authentication) with the Administration Console, and you wish to use XAuth to connect, select XAuth. Otherwise, leave this setting as Password. Example: Password
30
Authentication Setting
Description
SSL Proxy Host Name (if needed)
If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, enter the proxy host name here. If you can connect directly to the internet from this machine, leave this field blank. Authenticated proxy is not supported. Example: firewall01.mixateriacorp.com
SSL Proxy Host Port (if needed)
If your server is running behind a firewall that requires an SSL Proxy to connect to an outside server, enter the proxy host port here. Otherwise, leave this field blank. Common ports for SSL proxy are 80, 8080, 3128 and 1080. Authenticated proxy is not supported. Example: 8080
HTTP Proxy Host Name (if needed)
If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host here. Directory Sync always connects to the message security service on SSL. The only time the directory sync utility sends traffic by unencrypted HTTP is to validate a certificate with the issuing authority. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. Authenticated proxy is not supported. Example: firewall02-http.mixateriacorp.com
HTTP Proxy Host Port (if needed)
If you use a different proxy server for HTML connections than SSL connections, enter the HTTP proxy host port number here. If you do not use a proxy server, or you use the same proxy server for HTML and SSL connections, leave this field blank. Authenticated proxy is not supported. Example: 80
Configuration
31
Authentication Setting
Description
Immediately send a welcome message to new users
Typically, the message security service sends welcome notifications to new users within 24 hours, but not immediately. This is to prevent a flood of welcome that may overload your mail server. If you want to send all the notifications immediately, check the box labelled Immediately send a welcome message to new users.
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.
32
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. Choose which orgs to synchronize: 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. Hierarchy: All organizations under an organization you specify here are included in the synchronization. Enter the org name (not IID) here. The org name is case sensitive. Match the same case as the org name in the message security service. Specific orgs: Only the specified organizations are included in the synchronization. Enter each org name (not IID) and click Add to add it to the list. To remove an organization from synchronization, select that organization on the list and click Remove. Org names are case sensitive. Match the same case as the corresponding org name in the message security service.
Configuration
33
Exclusion Filters for Service Settings

If you have any users on your message security service user list who should not be deleted or moved by the synchronization, add an exclusion filter to protect those users. Other exclusion filters you might want to include are: Default users Administrators who are not in your LDAP system in the OUs you specify Mailing list administrators 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. Delete: Click the X icon to delete the exclusion filter.
34
Add Exclusion Filter
Click Add Exclusion Filter at the bottom of the page to exclude a user or organization from synchronization.

Exclusion Rule Setting Description
Type
Sets what type of exclusion filter to create, Primary Address or Postini Org. Primary Address: Check the users primary address and exclude any users that match. Postini Org: check the organization name on the message security service and exclude all users in organizations that match.
Configuration
35
Exclusion Rule Setting
Description
Match Type
The type of rule to match for the filter. Exact Match: The address or organization name must match the rule exactly. User Example: For a user, user1@mixateria.com would exclude that single user. Org Example: For an org, Mixateria Florida Sales would exclude all users in that single org. Substring Match: The address or organization name must contain the text of the rule as a substring. User Example: For a user, pdefault would exclude pdefaultsales55@mixateria.com and pdefault@sales.mixateria.com. Org Example: For an org, Sales would exclude all users in Mixateria Florida Sales and Sales Teams. Regular Expression: The address or organization must match the regular expression in the rule. User Example: For a user, the regular expression team[3-9]@mixateria.com would exclude team3@mixateria.com through team9@mixateria.com. Org Example: For an org, the regular expression Local Group - [A-Z][A-Z] would exclude all users in the Local Group - NJ and Local Group AZ organizations.
Exclusion Rule
The text of the match or regular expression to compare. See above for examples for these rules. Users that meet the requirements for an exclusion filter will not be deleted or moved. If they are listed on the LDAP server, the directory sync utility will attempt to add the user and fail
Sample Message Security Exclusion Rules

Listed below are samples of common exclusion rules. Note that the exact text of these rules will vary based on your needs.
36
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: Type: Primary Address Match Type: Substring Match Exclusion Rule: pdefault@
Second rule: Type: Primary Address Match Type: Substring Match Exclusion Rule: postinidefault@
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 wont be moved or deleted. Add a separate rule for each special administrator: First rule: Type: Primary Address Match Type: Exact Match Exclusion Rule: spam.administrator@mixateria.com
Second rule: Type: Primary Address Match Type: Exact Match Rule: virus.administrator@mixateria.com
Mailing List Org
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. Type: Postini Org Match Type: Exact Match Exclusion Rule: Mixteria Mailing List Users
Configuration
37
Alternate Offices
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. Type: Postini Org Match Type: Regular Expression Exclusion Rule: [Dubai|London]
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.
38
LDAP Connection
Specify your LDAP connection and authentication in this page.
LDAP Connection Setting
Description
Connection Type
Choose whether to use an encrypted connection. If your LDAP server supports an SSL connection and you wish to use it, choose LDAP + SSL. Otherwise, choose Standard LDAP. Example: Standard
Host Name
Enter the domain name or IP address of your LDAP directory server. Example: ad.mixateria.com, or 10.22.1.1.
Port
Specify the host port. The default is 389. Example: 389
Base DN
Enter the base DN for the subtree to synchronize. Do not include spaces between commas. If you dont know the base DN, consult your LDAP administrator or check an LDAP browser. Example:
ou=test,ou=sales,ou=melbourne,dc=ad,dc=mixateri a,dc=com
Configuration
39
LDAP Connection Setting
Description
Authentication Type
The authentication method for your LDAP server If your LDAP server allows anonymous connections and you want to connect anonymously, select Anonymous. Otherwise, select Simple. 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. If needed, include the domain for the user as well. Example: admin1
Password
Enter the password for the authorized user. Example: swordfish Passwords are stored in an encrypted format.
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.
40
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.
Configuration
41
LDAP User Attributes

Specify what attributes Google Apps Directory Sync will use when generating the LDAP user list.
LDAP User Attribute Setting
Description
Server Type
The type of LDAP server that you are using with the directory sync utility. If you are using a Lotus Domino, Microsoft Active Directory, or Open LDAP directory server, select that server type. Otherwise, select Other. Example: Microsoft Active Directory
Email Address Attribute
The LDAP attribute that contains a users primary email address. Example: The default is mail.
42
LDAP User Attribute Setting
Description
Non-Address Primary Key Attribute (Optional)
An LDAP attribute with a unique key other than an email address. This field is optional. If a users email address on your LDAP server changes (for instance, because of a name change), Google Apps Directory Sync will rename the user in the message security service without losing any quarantined mail or user settings. Example: sAMAccountName
Note: Use an attribute that contains a valid string. An
attribute that contains raw binary data will not work as a Non-Address Primary Key Attribute. Do not use the objectGUID attribute for this field. Mail List Attribute An LDAP attribute that specifies the address of a mailing list. The directory sync utility will use this attribute to look up the email address for any mailing lists detected with Mail List rules. For most servers, this value will be the same as the Email Address attribute. Example: mail Alias Address Attributes (if needed) One or more attributes used to hold alias addresses. These addresses will be placed as aliases to the primary address listed in the Email Address Attribute field. Example: proxyAddresses Domino Alias Address Attribute (if needed) Only for Lotus Domino servers. One or more attributes used to hold internal Domino alias attributes, which are stored as usernames without domain information. These addresses will be formatted as email addresses and placed as aliases to the primary address listed in the Email Address Attribute field. If you are using a Lotus Domino server but your alias address attribute stores full SMTP email addresses, list the attribute in Alias Address Attributes, not Domino Alias Address Attributes. Example: uid Domino Replacement Character Only for Lotus Domino servers. If an address contains a space, Google Apps Directory Sync will substitute this character instead. Example: The most common values are dot (.) and underscore (_).
Configuration
43
Use Defaults
Click this button to use the default values for your server type, as follows: Lotus Domino: Email Address Attribute mail, Domino Alias Address Attribute uid. MS Active Directory: Email Address Attribute mail, Alias Address Attribute
proxyAddresses.
OpenLDAP: Email Address Attribute mail. Other: Email Address Attribute mail.
LDAP User Sync

This shows a list of rules used when generating the LDAP user list.
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.
44
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. Delete: Click the X icon to delete 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.
Add Search Rule

To add a new search rule, click Add Search Rule.
Configuration
45

LDAP User Sync Setting
Description
Org Name
Select Org Name or Org name defined by this LDAP attribute and enter an appropriate value. Configure where to put users in your message security service org hierarchy. The directory sync utility adds all users that match this rule into the specified org in the message security service. Example: mixateria-com users
WARNING: Synchronization does not create new orgs in the message security service. If you need to add new organizations in the message security service, add them before you use the directory sync utility.
Org name defined by this LDAP attribute
Select Org Name or Org name defined by this LDAP attribute and enter an appropriate value. 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. Collect this information from the message security service and your LDAP server. For more information, see Checklist: Before You Begin on page 16. Example: extensionAttribute5 For instance, if the value for Org name defined by this attribute is extensionAttribute5, the directory sync utility will look up each users extensionAttribute5 attribute. If that attribute is set to mixateria-com sales then the directory sync utility will attempt to add the user to mixateria-com sales in the message security service. If the value of the Org Mapping Attribute is blank, the directory sync utility will not add the user, and will attempt to delete the user from the message security system if it is there.Configure where to put users in your message security service org hierarchy.
WARNING: Synchronization does not create new orgs in the message security service, nor does it populate fields in your LDAP server. If you need to add new organizations in the message security service, or new fields on your LDAP server, add them before you use the directory sync utility.
46
Description
Use Default Filter (optional)
Only usable if you are using Org name defined by this LDAP attribute. The use default filter check box sets the scope to Subtree and the rule to objectclass=*.
WARNING: This setting is not recommended for large deployments because it may cause extreme load.
Scope
This determines where in the LDAP directory this rule applies. This could be an entire subtree, one level, or a single object. Subtree: All objects matched by the search, and anything under those objects. (recursive) One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. Object: Only objects directly matched by the search. No recursion of any kind.
Choosing which option to use: Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level provides a limited search that will avoid causing extreme load for very large organizations. Object is rarely used except with very complex LDAP searches. It allows a search only on the specified object. Example: Subtree
Configuration
47
Description
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. Example 1: To match all objects (this may cause load problems):
objectclass=*.
Example 2: To match all human users: For OpenLDAP:

(objectClass=inetOrgPerson)
For Active Directory:

(objectClass=person)
for Lotus Domino:

(objectClass=dominoPerson)
LDAP User Exclusion Rules

If you have any users on your LDAP directory server that match your search rules but should not be added, add an exclusion rule here. This might include: Internal users who do not have outside email addresses Printers, conference rooms, and other non-user resources Users who should not receive mail filtering
48
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. Delete: Click the X icon to delete the exclusion filter.
Configuration
49
Click the Add Exclusion Filter at the bottom of the page to exclude a user or organization in your LDAP server from synchronization.

Match Type
The type of rule to use for the filter. Exact Match: The address must match the rule exactly. Example: maria@mixateria.com would exclude only the user maria@mixateria.com. Substring Match: The address or organization name must contain the text of the rule as a substring. Example: test would exclude testadmin@mixateria.com and salestest1@mixateria.com. Regular Expression: The address or organization must match the regular expression specified. Example: internal.*@mixateria.com would exclude internalhelpdesk@mixateria.com and internal@mixateria.com.
50
Exclusion Rule Setting
Description
Exclude Type
What kind of LDAP data to exclude. Primary Address: Directory Sync will exclude primary addresses that match this rule. Alias Address: Directory Sync will exclude aliases that match this rule.
If you want to exclude both primary addresses and alias addresses, create two exclusion rules. Rule The match string or regular expression for the exclusion rule. Behavior of this field depends on the Match Type you choose. Addresses that contain this string (or match this regular expression) will not be added to the message security service, and will be deleted if found. Examples: Exact Match: maria@mixateria.com Substring Match: listinternal Regular Expression: internal.*@mixateria.com
Sample LDAP User Exclusion Rules

Sample Substring Match: Printers
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. Match Type: Substring Match Exclude Type: Primary Address Rule: printer
Sample Exact Match: Opt-Out Users
Two users have opted out of mail filtering and should not be synchronized. Add a separate rule for each special user.
Configuration
51
First rule: Match Type: Exact Match Exclude Type: Primary Address Rule: atif@mixateria.com
Second rule: Match Type: Exact Match Exclude Type: Primary Address Rule: svetlana@mixateria.com
Sample Regular Expression Match: Test Users
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: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression Rule: internal-test[0-9]*@mixateria.com
LDAP Mailing List Overview

The LDAP Settings section configures how Google Apps Directory Sync generates a list of mailing lists from your LDAP directory server. You may need to collect information from your LDAP directory server before you can enter details in this section.
52
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.
Configuration
53
LDAP Mailing List Sync

Mailing lists are a special kind of email address that direct mail to many addresses at once. Most administrators prefer to create mailing lists as aliases to a separate user in the message security service, to avoid administrative notifications and quarantine summaries going out to all the members of a mailing list.
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. Delete: Click the X icon to delete the exclusion filter.
54
Add Mail List

Click the Add Mail List at the bottom of the page to synchronize one or more addresses as mailing lists.

Mailing List Setting Description
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. Example: Mixateria Special Administrators
Configuration
55
Mailing List Setting
Description
Scope
Where to apply the mail list rule. This could be a whole subtree, a single level, or a single object. Subtree: All objects matched by the search, and anything under those objects. (recursive) One-level: All objects matched by the search, and anything one level underneath them. Does not look further than one level. Object: Only objects directly matched by the search. No recursion of any kind.
Choosing which option to use: Subtree gives the broadest search, but for very large organizations this can be load-intensive and cause system problems. One-level provides a limited search that will avoid causing load for very large organizations. Object is rarely used except with very complex LDAP searches. It allows a search only on the specified 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)
LDAP Mailing List Exclusion Rules

You can exclude particular addresses from being treated as mailing lists. 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: Internal mailing lists that do not have outside email addresses Printers, conference rooms, and other non-user resources Mailing lists that should be treated as individual users, with separate archives and quarantines.
56
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. Delete: Click the X icon to delete the exclusion filter.
Configuration
57
Click Add Exclusion Filter at the bottom of the page to prevent an address from being treated as a mailing list.

Match Type
The type of rule to use for the filter. Exact Match: The address or organization name must match the rule exactly. Substring Match: The address or organization name must contain the text of the rule as a substring. Regular Expression: The address or organization must match the regular expression specified.
Rule
The text of the match or regular expression to compare. Addresses that meet the requirements for an exclusion filter (or users in orgs that meet the requirements) will not be added as mailing lists.
Sample LDAP User Exclusion Rules

58
Sample Substring Match: Internal Mailing Lists
Several mailing lists are devoted to internal use only. Those lists all have internal in the address. Match Type: Substring Match Rule: internal
Sample Exact Match: Secure Mailing Lists
Three small-distribution mailing lists are top security and should not be archived with other mailing lists. Add a separate rule for each special mailing list. First rule: Match Type: Exact Match Rule: finance-early-statements@mixateria.com
Second rule: Match Type: Exact Match Rule: internal-security@mixateria.com
Third rule: Match Type: Exact Match Rule: legal-confidential@mixateria.com
Sample Regular Expression Match: Test Users
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: internaltestX, where X is a number, and all test users are in the same domain. Match Type: Regular Expression 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.
Configuration
59
Consider adding a notification to send mail to your own address, and possibly the addresses of any concerned parties in your company.
Note: Notifications do not support TLS.

Notifications Setting Description
Send notifications from address
Enter the From: address for the notification mail. Recipients will see this address as the notification sender. For instance, you might use your own email address. Example: dirsync@mixateria.com
Send notifications to the following addresses
Notifications will be sent to all addresses on this list. Enter any valid email address on any domain. Enter each recipient email address individually, then click the Add button. Depending on your mail server settings, the directory sync utility may be unable to send mail to external email addresses. Run a test notification to confirm that mail is sent properly. Example: dirsync-admins@mixateria.com
60
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: 172.0.0.1 to run the mail server on the same machine. Example: mail.mixateria.com
Username (if needed) Password (if needed)
If the SMTP server you specify requires SMTP authentication, enter the user name to use here. Example: admin5 If the SMTP server you specify requires SMTP authentication, enter the Password to use here. Example: swordfish Passwords are stored in an encrypted format.
Do not include in notifications (Optional)
You can limit the information sent in notifications by checking any of the three checkboxes. All checkboxes are optional. Extra details: Google Apps Directory Sync notifications will not include extra details and potentially extraneous information. Warnings: Google Apps Directory Sync notifications will not include warning messages. Errors: Google Apps Directory Sync notifications will not include error messages.
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.
Configuration
61
The directory sync utility checks to be sure that synchronization will not delete too many users. If the synchronization would delete more users than the delete limits allow, the entire synchronization fails and no users are added, moved or deleted. This will be noted in the notifications email.
Note: Delete limits apply during synchronization, but not during simulation.
Simulation results will not include delete limits. To set a delete limit, specify one of the following:
Delete Limits Setting Description
Delete no more than % of users (Optional)
Specify a maximum percentage of users that can be deleted. This is a percentage of the users registered on the message security service, not a percentage of users on your LDAP server. If no delete limit is specified, the default is 5%. If you set the delete limit to 100%, delete limits will not apply. You can suppress delete limits from the command line. Example: 5%
Delete no more than users (Optional)
Specify a maximum number of users that can be deleted. Example: 25
62
Log Files
You can specify the file name and level of detail of logging for Google Apps Directory Sync.

Logging Setting Description
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. The level of detail is cumulative: each level includes all the details of previous levels. ERROR includes all ERROR and FATAL messages, and so on. FATAL only logs fatal operations. ERROR only logs errors and fatal operations. WARN only logs warnings, errors and fatal operations. INFO logs summary information. DEBUG logs more extensive details. TRACE logs all possible details.
Configuration
63
Logging Setting
Description
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.
64
Once youve completed all required fields, you will be able to use the Simulate Sync button to simulate a synchronization.
Once youre ready, click Simulate Sync. You will see the Simulate Sync page. During simulation, Configuration Manager will: Connect to the message security service and generate a registered user list. Connect to your LDAP server and generate an LDAP user list. Generate a list of differences. Log all events. If connection was successful, show a Proposed Change Report which shows what changes would have been made to your message security service 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.
Configuration
65
Review the Simulation Results to confirm that the simulation occurred correctly without any unexpected results.
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 doesnt 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.
66
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.
Command Line Synchronization

Before you can run synchronization, create a Configuration XML file using the Configuration Manager user interface. For more information, see For more information about Configuration Manager, see Configuration on page 27. The command line to use for all platforms is
sync-cmd
Run without any arguments, this command gives an error and directs you to run sync-cmd -h for help. To synchronize, use the following command line to read a configuration file, connect to both servers, generate a list of changes, and apply those changes:
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
in the directory where the directory sync utility is installed.

Option -r,--report-out -a,--apply -V -c,--config [filename] Values
Write reports to the specified output file, in addition to writing them to the log. Apply detected changes. Display detailed application version information. Specify the configuration to load. Synchronization will not occur without a valid XML file for this argument. Ignores any configured delete limits. For support troubleshooting only (slows sync)
WARNING: This option is intended only to resolve specific troubleshooting issues. Improper use can cause performance degradation. Do not use this option unless directed by support.
-d, --deletelimits -f, --flush
-g, --groups
Do not analyze groups.

Note: Do not use this option. It is intended for other versions of the directory sync utility, and will have no effect.
-h,--help -l,--loglevel [level]
View this information and exit. Override the default and/or configured log level with the specified value. Valid values (in increasing order of verbosity) are FATAL, ERROR, WARN, INFO, DEBUG, and TRACE. In most cases, the recommended log level is INFO.
-s, --sharedcontacts
Do not analyze shared contacts.

Note: Do not use this option. It is intended for other versions of the directory sync utility, and will have no effect.
68
Option -u, --users
Values
Do not analyze users.

Note: If you use this option, Google Apps
Directory Sync will not add, move or delete users.

-v
Display short application version information.
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.
Microsoft Windows: Scheduled Tasks

In Microsoft Windows, schedule synchronization using Scheduled Tasks.
Note: These steps apply to most common Microsoft Windows configurations.
Scheduled Tasks is a third-party product and is not supported directly by the Google (or Postini) team. In the event of a Scheduled Tasks issue, contact your Windows administrator.
To schedule a task
1. In Control Panel, open Scheduled Tasks. 2. Double-click Add Scheduled Task.
Synchronization
69
3. Complete the Scheduled Task wizard using the following information. (Steps may vary depending on your version of Microsoft Windows.) Choose the program sync-cmd.exe, located where the directory sync utility is installed. The frequency of the task depends on your synchronization needs. For most environments, twice per week is appropriate. Use Advanced Properties to specify an exact command line. The appropriate command line is:
[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. 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.
Linux and Solaris: cron

In Linux and Solaris environments, schedule synchronization using crontab.
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.
To add a cron job
1. Run crontab -e to update the crontab file. 2. Add a line in the crontab file for the following command:
sync-cmd -a -c [filename]
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. 3. Save the crontab file and exit your text editor.
70
Chapter 7
Troubleshooting
Chapter 7
About Troubleshooting
This chapter covers information about how to troubleshoot problems that may occur with Google Apps Directory Sync. Troubleshooting information includes information about common issues, system tests and researching issues. 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.
A mailing list rule or exclusion rule doesnt seem to be doing anything.
Check the scope of the rule. You may need to set the scope to SUBTREE.
A mailing list rule generates errors.
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.
The base DN information doesnt seem to be correct.
Check to be sure your base DN doesnt include any spaces.
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.
I cannot simulate a synchronization because the notifications server not specified.
To run a simulated synchronization, you will need a server capable of sending mail. If you are running directory sync 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.
How securely are passwords stored?
Google Apps Directory Sync stores passwords using a two-way encryption scheme. This protects your sensitive information from casual snooping or reverse engineering. This is a change from previous versions. Before 1.3.11, passwords were stored unencrypted in plain text in configuration files. To convert a configuration file to the new format with encrypted passwords: 1. Open the file in Configuration Manager. 2. Save the file again. You can also upgrade the file with the following command-line executable:
upgrade-config -c [filename]
where [filename] is the name of the XML configuration file to upgrade.

Note: Configuration files for version 1.3.11 or later are not compatible with earlier
versions.
How can I exclude a specific LDAP organization?
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.
72
There is no workaround for this. This stored information is only available to DSS and is not available via batch or the GUI.
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. 2. Under Message Security Service Authentication, click Test Connection to confirm you can connect to the message security service. 3. Under LDAP Connections, 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. 6. Under Simulate Sync, click Simulate Sync to confirm that synchronization is running properly. 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
74

Google App Dir Sync

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Google App Dir Sync

Diunggah oleh

Hak Cipta:

Format Tersedia

Google Apps Directory Sync

Release 1.3.27, March 2009

Release 1.3.27, March 2009

Release 1.3.27, March 2009

About This Guide

What This Guide Contains

Message Security Administration Guide

Directory Sync Configuration Guide

How to Send Comments About This Guide

Release 1.3.27, March 2009

About Google Apps Directory Sync

Features and Benefits

Comparison with Directory Sync Hosted Edition

Runs on a server in your network.

Configuration Direction of Data Flow Installation Needed

Release 1.3.27, March 2009

Release 1.3.27, March 2009

Release 1.3.27, March 2009

Checklist: Before You Begin

Release 1.3.27, March 2009

Useful LDAP Tools

Softerra LDAP Administrator

Release 1.3.27, March 2009

Equals Any Parentheses And Or Not

Common LDAP Queries

All user objects that are designated as a person

Distribution Lists only

Public Folders only

All users, but exclude disabled users:

Active Directory LDAP: All users

Active Directory LDAP: All email users (alternate)

OpenLDAP: All users

Lotus Domino LDAP: All users

Release 1.3.27, March 2009

Planning for Large or Complex Deployments

Release 1.3.27, March 2009

Install Google Apps Directory Sync

Release 1.3.27, March 2009

3. Download and run the installer.

Upgrade Google Apps Directory Sync

Uninstall Google Apps Directory Sync

Release 1.3.27, March 2009

Release 1.3.27, March 2009

Message Security Service Settings

Message Security Service Authentication

Specify the following:

Password or Xauth Hash String

Release 1.3.27, March 2009

SSL Proxy Host Name (if needed)

SSL Proxy Host Port (if needed)

HTTP Proxy Host Name (if needed)

HTTP Proxy Host Port (if needed)

Immediately send a welcome message to new users

Release 1.3.27, March 2009

Message Security Service Orgs

Exclusion Filters for Service Settings

Release 1.3.27, March 2009

Add Exclusion Filter

Specify the following:

Exclusion Rule Setting

Sample Message Security Exclusion Rules

Release 1.3.27, March 2009

Mailing List Org