Setting up DirSync

Requirements

Software requirements

Windows operating system, minimum Windows XP / Server 2003
(Windows 7 or higher or Windows Server 2008 R2 or higher are recommended)
Supports both 32-bit and 64-bit operating systems
Microsoft .Net Framework 4.0

Hardware requirements

Memory requirements depend on the size of the directory that is to be queried. It is recommended to reserve at least one Gigabyte for the service.

As to hard disk requirements, they depend on the size of the log and archive files to be retained. It is recommended to reserve a minimum of 500 MB of free hard disk space.

It is not required to set up a dedicated system for this service. It can be run on machines already available in the infrastructure, provided they meet the other requirements described in this document.

Network requirements

The following network requirements exist:

Network access to the internet via https on port 443.
Network access to the domain controllers’ Active Directory service, typically the Microsoft default port 389 (TCP/UDP), or port 3268 (TCP), if the Global Catalog is to be queried.
A minimum bandwidth to the internet of 256 kBit/sec (depending on the size of the directory to be queried).
If sending logs/error reports by mail is required: the possibility to send mail via SMTP.

Architecture

The software has been programmed in C#, using the .NET Framework version 4. Only native Microsoft libraries have been used. The software neither uses nor depends on third party libraries.

All operative actions such as querying the directory and sending the information to Retarus are completed by a Windows service to be installed locally at the customer. The settings are stored locally in a configuration file.

License and liability

The program and its documentation are supplied free of charge as a courtesy of Retarus GmbH with no obligations or liabilities whatsoever. Customers run this software at their own risk and are not entitled to officially request or receive support for this tool. They can request the source code of the software to verify its procedures and operations, and they may compile the source code for their own usage. However, customers are not entitled to alter or distribute the software or any of its sources or to use it or any parts or sources of it for other purposes without the prior and explicit permission by Retarus.

Any information, documentation, or sources that the customers or their agents have possession of are the intellectual property of Retarus and are subject to the privacy regulations and non-disclosure agreements between the customer and Retarus.

Installing the service

Installing via the setup wizard

Retarus DirSync Service may be installed by using the provided setup routine.

Administrative user privileges are required to install the tool as a service. Any command line prompts must be opened in administrative mode:

Execute the RetarusDirSyncSetup.exe installation wizard and follow the shown steps. The service is installed in the default location %ProgramData%\Retarus\DirSync.
If you would like to use another location, please follow the steps described in the manual installation below.
On the last screen, activate the Start services management console option (or open the Windows Services management console manually after the setup wizard has been completed) and start the RetarusDirSync service.

Known Issue
On some systems, an error message with “error code 1076” is displayed when starting the service for the first time. In this case, please try a second time, and the service will start.

Configuration of the Retarus DirSync Service is done afterwards directly via editing the config file as described in the following chapters.

Deinstallation

The service may be deinstalled by using the Windows built-in deinstallation functionality. In this case, the configuration and log files are not deleted automatically

Installing manually

As an alternative to the provided setup routine, Retarus DirSync Service may be installed manually. In this case, you may also choose a different location for the installation.

Administrative user privileges are required to install the tool as a service. Any command line prompts must be opened in administrative mode.

There are only a few steps to be completed to install the Retarus DirSync:

Copy both the executable file (RetarusDirSync.exe) and the pre-configured xml file (do not change the file name RetarusDirSyncConfig.xml), which you were provided with, into a folder of your choice.
Open a command prompt and change the current directory to the folder you selected.
To install the executable file as a Windows service, run the following command at this command line prompt:
%windir%\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe RetarusDirSync.exe
%windir% represents the drive of your Windows operating system. To uninstall the service, run this command with the command-line parameter /u. Any installation log files will be stored in the program folder.
Open the Windows Services management console (services.msc) and start the RetarusDirSync service. Alternatively, you may also enter net start RetarusDirSync on the command prompt.
By default, the service creates any subfolders required for log and archive files in %ProgramData%\Retarus\DirSync. This location can be changed via the configuration settings.
Configuration of the Retarus DirSync Service is done afterwards directly via editing the config file (see subsequent sections).

Known limitations

During service setup, an error may occur (typically) on Windows 2008 R2 systems. To protect the computer from potentially malicious software trying to get installed, the operating system might block the downloaded executable from being executed. Microsoft’s InstallUtil.exe may, therefore, not be able to load the RetarusDirSync.exe. An error message similar to the following example will occur in this case when running InstallUtil:

NONE

c:\Windows\Microsoft.NET\Framework\v4.0.30319\InstallUtil.exe RetarusDirSync.exe

Microsoft (R) .NET Framework Installation utility Version 4.0.30319.1
Copyright (c) Microsoft Corporation. All rights reserved.

Exception occurred while initializing the installation:
System.IO.FileLoadException: Could not load file or assembly
'file:///C:\Retarus\RetarusDirSync.exe' or one of its dependencies.
Operation is not supported. (Exception from HRESULT: 0x80131515).

In this case, right-click RetarusDirSync.exe and select the PROPERTIES option from the context menu. On the tab GENERAL, click the UNBLOCK button to permit the file to be executed. After unblocking the file, repeat the InstallUtil.exe command line in order to complete the installation procedure.