IBM Support

What is file synchronization and how does it work?

Question & Answer


What is file synchronization service? How does Synchronization actually work? Does the Synchronization Service synchronize changes to the master repository made by manually editing a configuration file, for example, using Notepad? Are installed applications covered in synchronization?


  1. What is the file synchronization service?

    The Deployment Manager will maintain a centralized repository of configuration data. Each node also has their own local configuration files. The file synchronization service is the administrative service responsible for keeping the configuration documents that are distributed across the IBM® WebSphere® Application Server cell up to date. This service runs in the deployment manager and node agents, and ensures that the configuration changes made to the cell repository will be propagated to the appropriate node repositories.

    During a configuration synchronization operation, a node agent checks with the deployment manager to see if any configuration documents that apply to the node have been updated. New or updated documents are copied to the node repository, and deleted documents are removed from the node repository.

  2. How does synchronization actually work? Does the synchronization service synchronize changes to the master repository made by manually editing a configuration file, for example, using Notepad?

    Both the node agent and deployment manager keep a calculated digest for each file in the configuration they manage (master cell repository managed by deployment manager, local node repository managed by node agent). These digest values are stored in memory.

    Also stored in memory are "epochs" for the folders in the repository and for the repository overall. These epochs are used to determine whether any files in the directory have changed.

    If a change to a configuration file is made through the administration programs (Administration console, wsadmin, or other), then the overall repository epoch and the epoch for the folder in which that file resides is modified. During configuration synchronization operations, if the repository epoch has changed since the previous synchronization operation, then individual folder epochs will be compared. If the epochs for corresponding node and cell directories do not match, then the digests for all files in the directory are recalculated, including that changed file. If a change to a configuration file is made by editing the file and bypassing the administration programs, then the digest is not recalculated because the epochs for the directories continue to match.

    The algorithm for synchronization by default only compares these epochs between node agent and deployment manager. The files are not read on every synchronization operation. So, by DEFAULT, manual edits to the configuration files in the cell repository are not picked up during "normal synchronization" operations. This was a compromise reached to allow best performance under normal conditions since editing the files manually is not a recommended best practice.

    But manual edits of configuration files in the master cell repository can be picked up if the repository is "reset" so that it goes back out and re-reads all the files and recalculates all of the digests. There is a JMX operation on the ConfigRepository MBean that resets the repository epoch so that the next sync operation will result in recalculating the file digests and picking up any manual changes to the master cell repository configuration files.

    You can reset either the master cell repository epoch or the node repository epoch. If you reset the master cell repository, then any manual changes made in the master configuration repository will be picked up and replicated to the nodes where the file is applicable. If you reset the node repository, then any manual changes to the local node files will be wiped out (overwritten) by whatever is in the master cell repository, regardless of whether the cell repository was changed or not. Any manual changes in the master repository will be picked up and brought down to the node. The main difference between cell reset and node reset is that cell reset is likely to impact the entire cell, not just one node.

    Here are instructions for performing a reset of the master cell repository:

    In a wsadmin session connected to the deployment manager, enter the following (blue text):

    wsadmin>set config [$AdminControl queryNames *:*,type=ConfigRepository,process=dmgr]
    wsadmin>$AdminControl invoke $config refreshRepositoryEpoch

    You will see a number returned by the refreshRepositoryEpoch operation (for instance: 1047961605195). This resets the entire cell repository digest set. So, on the next sync operation, all files in the master cell repository will have their digests recalculated and any manual changes will be replicated to the applicable nodes.

    There are a couple of ways to perform node "repository reset".
    • In a wsadmin session connected to the deployment manager (or node agent), enter the following (blue text):

      wsadmin>set config [$AdminControl queryNames *:*,type=ConfigRepository,process=nodeagent]
      wsadmin>$AdminControl invoke $config refreshRepositoryEpoch

      This resets the node digest set. Any file on the local node that does not match what is in the repository will be overwritten.

    • In the Network Deployment Administration console, you can click on "System Administration" and then "Nodes" to see a list of the nodes in the cell. You will notice "Synchronize" and "Full Resynchronize" buttons on the page. The "Synchronize" button is "normal synchronization" (no re-reading of the files). The "Full Resynchronize" button is the "reset and recalculate" function. Select the node or nodes to be updated with manual changes and click on the Full Resynchronize button.

  3. Are installed applications covered in synchronization?

    Yes, installed applications are treated like the other configuration files in the repository and are synchronized. For installed applications, there is an EAR file in the repository and also some configuration files associated with the deployment of the application. Normal synchronization operations will synchronize the application files that have been updated with the Administration programs.

    If you manually change the EAR file, this is not recommended, and reset the master cell repository (to recalculate the digests), the changed EAR file will be replicated out to the nodes where it is configured to be served and it will be expanded in the appropriate location on that node for the application server to find it
  4. Are files added to the configuration repository synchronized to nodes?

Since the file synchronization service will ensure that the node repository matches the deployment manager repository, any files placed in the deployment manager configuration repository by the administrator will be synchronized to nodes in the cell. Files placed in a node level directory will only be synchronized to that node. Files placed above a node level directory will be synchronized to all nodes. If the files are added to or updated in an existing directory you will need to take additional action to have the system recognize the files. The actions are the same as discussed in question 2 above for manual edits.

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU053","label":"Cloud & Data Platform"},"Component":"Administrative Console (all non-scripting)","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"8.5.5;8.5;8.0;7.0;6.1;6.0","Edition":"Network Deployment","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSNVBF","label":"Runtimes for Java Technology"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Java SDK","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}}]

Document Information

Modified date:
30 August 2019