How To: Understand and Use FileSync

Version Affected: All versions

 

Overview

This article explains what the FileSync service is, the terminology it uses, and how it decides what to synchronize, so you understand its behavior before relying on it. FileSync is an add-on to SecureAuth IdP that keeps configuration information synchronized between the members of a cluster.

Understand How FileSync Works

Terminology:

• Cluster: two or more SecureAuth IdP servers running the FileSync service.
• Node: a specific SecureAuth IdP server in a FileSync cluster.
• Primary-Replica: one appliance is the Primary node, and all changes for the cluster are made there.
• Multi-Master (FileSync 3.4.5 and older only; deprecated after 3.4.5): every appliance is a peer, and a change made on any node propagates to the rest of the cluster.

FileSync is a pull service: changes propagate to other servers only after a change is made on the Primary node (Primary-Replica) or on any node (Multi-Master) — not continuously.

FileSync 3.4.5 and older cannot create realms or folders on its own. For example, if realm SecureAuth6 exists on the Primary appliance, you must also create SecureAuth6 on the Replica appliance using the Realm Management Tool before FileSync can pull its settings there. FileSync 4.0.11 and newer do not have this limitation.

What FileSync copies: the SecureAuth0 folder contains a file named Paths.list, which controls what FileSync actually copies — by default, each realm's web.config, its language resource files, and the MFA.SecureAuth.Resource.dll file. You can sync additional folders by adding a new entry, for example <path name="Images\" /> to also sync the Images folder. New files that don't already exist on the replica must be placed in the Template realm first (the realm specified when FileSync was installed on the Primary server) — otherwise FileSync will not start syncing them. For example, to sync a new file company-logo.jpg when SecureAuth1 is the Template realm, first copy it to SecureAuth1\Images\; FileSync then replicates it to the same path in every other realm.

Using FileSync correctly:

• FileSync relies on Windows File and Print Sharing being enabled between nodes, over ports allowed through the firewall. If sharing is disabled, or a firewall is blocking those ports, changes stop propagating between nodes entirely. Confirm the Server service (services.msc) is set to Automatic and running, File and Print Sharing is enabled under Network and Sharing Center > Advanced sharing settings, and the firewall allows traffic between all nodes.
• In a Primary-Replica configuration, only make changes on the Primary server. If a file's timestamp is newer on the Replica than on the Primary, FileSync 3.4.5 and older will not sync that file; FileSync 4.0.11 and newer will overwrite it on the Replica regardless.
• Create the realm on the Primary server using the Realm Management Tool. On FileSync 3.4.5 and older, also create a matching realm number on the Replica server the same way — FileSync 4.0.11 and newer does not need this step.
• On FileSync 3.4.5 and older, allow the default 10-minute sync interval (configurable) after creating a realm. On FileSync 4.0.11 and newer, the sync interval is 1 minute, since changes are pushed out as they're detected rather than pulled by a periodic comparison.
• On FileSync 3.4.5 and older, always use the Realm Management Tool to create realms intended for FileSync — creating realms through the Admin Console can fail to carry over the template realm's permissions.
• On FileSync 4.0.11 and newer, do not use renamed or vanity URLs for a realm — for example, renaming SecureAuth23 to appname to serve https://your.idp.com/appname. This breaks FileSync's replication. FileSync 4.1.5.6 and newer supports vanity URLs, but only when the vanity URL is created as a new application alongside the original SecureAuthXXX realm, which must still exist.
• Before running SABackupTool, turn off the FileSync service on every server first — otherwise the backup attempt fails.

Installing FileSync: FileSync should be installed by a SecureAuth support engineer during a scheduled session.

Special Considerations

FileSync 4.0.11 is not aware of Windows Server 2016. Use FileSync 4.0.13 or newer to support Server 2016.


 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.