updinst

The updinst program synchronizes files and registry settings between servers in a multiple-instance environment, or a replication environment. The program is run during auto discovery when the Maintenance > Options > PSUPDATE FILE REPLICATION setting is enabled. This is the default setting.

This program also collects and synchronizes proxy log files onto the instance server.

This program is used in conjunction with the File Replication Service (idfilerep).

To determine which files and registry settings updinst replicates, there are whitelists and blacklists that specify what data to include and what data to omit in the context of file/registry replication You can write an updinst.cfg file to provide additional configuration.

A sample of updinst.cfg is located in the samples directory. This configuration file must be placed in the \ <instance> \ psconfig \ directory before it can be used by the File Replication Service. Use this configuration file to control which files and registry settings are replicated to other instances (whitelist) and which are not replicated (blacklist). The whitelist settings override blacklist settings.

Warning

All file and configuration modifications should be done on the same server (the primary). When attempting to run updinst from a node other than the primary, an error will occur, and the operation will be aborted. In extreme circumstances there is an option to force external data store replication (-extdb -forcerun) from a secondary node; however that should be done only when that database was corrupted on the primary (and its backups that are created every time the external data store is updated, were also corrupted) but the database, or a backup, survived on a secondary node. If updinst is run from more than one server, or if file or registry changes are made on secondary nodes, it is possible for it to overwrite newer files or settings that exist on secondary nodes. If a server with missing files runs updinst, that will remove those same files on all other instances.

Caution

Do not attempt to replace Database Service (iddb) files using updinst or the File Replication Service. Updating the Database Service and related files (such as iddbmssql.dll) must be done manually on all instances. This only applies to the Database Service service. All other services can be updated using the File Replication Service. To update the Database Service files manually, shut down all services on the instance, back up all services, and then replace the Database Service files.

If a problem occurs during file replication then a notification email is sent to the administrator, and the FILE REPLICATION FAILURE event is triggered.

Usage

updinst.exe [-list] | [-showconfig] |
  [-synchfile] [-syncreg]  [-globalcp] [-serverid <serverid>...] [-dry-run] |
  [-extdb[-forcerun]] | [-getlogs] [-proxyfile <proxylist.csv>] [-removelogs]

Table 1. updinst arguments

Argument	Description
-dry-run	Only show what would be done without making changes.
-getlogs	Retrieve and synchronize all logs from all proxies configured onto the instance server. Logs will be under their respective \Logs\proxy_<proxy_IP> directory.
-globalcp	Synchronize the global connector pack in addition to the current instance. Used in conjunction with the -syncfile argument.
-list	List file replication services involved and exit. Display the status of each service, node ID, address, and port. If the service is unreachable, check the connection of the Database Service for each server.
-proxyfile <proxylist.csv>	Retrieve and synchronize all logs from proxies listed in the \<instance>\psconfig\proxylist.csv file. Logs will be under their respective \Logs\proxy_>proxy_IP< directory. Where proxylist.csv contains a list of proxy IP addresses and their ports. This is only used in conjunction with -getlogs.
-serverid <serverid> …	Synchronize to specified servers; can be used with multiple server IDs. The server ID can be found using the -list argument. If no server is specified, all servers are updated.
-showconfig	Show built-in configuration and exit.
-syncfile	Synchronize files to other servers.
-syncreg	Synchronize registry settings to other servers.
-extdb	Synchronize the extdb tables.
-forcerun	Forces the current node to synchronize the extdb tables.
-removelogs	Remove all previously fetched logs from all proxies. Can be used in conjunction with -getlogs to remove logs that no longer exist on the remote server.
-filedir <filedir>	Specific file path from which files are synchronized to other servers. This is the relative path under the instance’s main file folder.
-registrydir <registrydir>	Specific registry path from which settings are synchronized to other servers. This is the relative path under the instance’s main registry folder.

Examples

To show the default configuration file:
```
updinst -showconfig
```
To show a list of all file replication services that are running:
```
updinst -list
```
To synchronize all files and registry settings on all servers:
```
updinst -syncfile -syncreg
```
To synchronize a specific file directory on all servers:
```
updinst -syncfile -filedir <filedir>
```

To synchronize multiple file directories on all servers:

updinst -syncfile -filedir <filedir1> -filedir <filedir2> ...

To synchronize a specific registry setting on all servers:
```
updinst -syncreg -registrydir <registrydir>
```

To run a dry-run on a specific server:

updinst -serverid <server id (guid)> -syncfile -syncreg

To update global Connector Pack files:
```
updinst.exe -globalcp -syncfile
```
To collect and synchronize logs from all proxies:
```
updinst.exe -getlogs
```
To collect and synchronize logs from all proxies listed in the proxylist file:
```
updinst.exe -getlogs -proxyfile <proxylist.csv>
```

Where the proxylist.csv contains:

::proxy, port::
10.0.39.111, 3344
10.0.39.121, 3344

To synchronize the extdb tables:
```
updinst.exe -extdb
```
To remove all previously fetched logs:
```
updinst.exe -removelogs
```
To remove logs that no longer exist on the remote server:
```
updinst.exe -removelogs -getlogs
```

Update updinst config file

In the updinst config file, all file paths are rooted at the backslash immediately after the instance_name directory.

Each item in the lists contained in the file is a regular expression (regex).

While the sample .cfg file contains some entries from the default values built into the updinst binary (for regex illustration purposes), it's recommended that the cfg file actually used contain only new/custom values, which do not show up in the four lists when checking the configuration with no updinst.cfg file in the psconfig directory (it saves on comparisons, and the instance contains many files and directories to compare with each declared regex string).

If the file to add an exception for is script\somefile.py , the most precise regex expression for it is:

^\\\\script\\\\somefile.py$

The starting ^ represents the beginning of the string, so it would not match, for example:

\samples\script\somefile.py

Similarly, the trailing $ represents the end of the string, so it won't match, for example, an extension like .pyg

To exclude a whole directory, you can leave the $ off and the expression will match everything in that directory: files and other directories with their files. This default option for example matches all auto-discovered target list files:

psconfig\\\\discovered

Each backslash is escaped with a backslash, so \ becomes \\, and since it is inside a KVG string, \\ becomes \\\\ (\s would simply escape the s).

Below is an example that adds blacklisted registry entries and file entries (meaning that they will not be sent from the primary to secondary application nodes).

# KVGROUP-V2.0  
"updinst" "cfg" = {  
# Registry path blacklist.  Registry paths that match the regular  
# expressions here are not considered for replication, unless they  
# appear in regWhitelist.  All paths are relative to the instance  
# registry root.  Registry keys (and value names) are separated by  
# double-escaped backslashes (\\\\). 
 "regBlacklist" = { "^IDAPISOAP\\\\endpoints";  
                     "SENDER_EMAIL";  
                     "ServerAddress" };
  # File path blacklist. Filesystem paths that match the regular
  # expressions here are not considered for propagation, unless they
  # appear in regWhitelist (see above). All paths are relative to the
  # instance root directory. Directories and files are separated
  # by double-escaped backslashes (\\\\).
  "fileBlacklist" = { "^\\\\psconfig\\\\.*\\.db$";
                      "plugin\\\\debug\\\\.*";
                      "design\\\\src\\\\ui.build\\\\.*";
                      "design\\\\src\\\\ui\\\\node_modules\\\\.*"
                  };
}

In the above:

Blacklisting these entries ensures that the SENDER_EMAIL and ServerAddress are not propagated from the primary to the secondaries. These two entries will be unique to each server.
- SENDER_EMAIL system variable, so that each node can be given a separate "From:" field in outgoing emails, to be able to quickly distinguish what node originates what email.
- ServerAddres s bypasses the automatic computer-name detection on each node (for example, when iddb detects only the hostname in a node whose OS is not joined to a domain, and Bravura Privilege needs to register FQDNs instead - so that link passing between nodes, as in downloading recording archives, can succeed the TLS check in IIS)
The entry blacklisting the IDAPISOAP\endpoints registry key exists by default in the configuration file, in case each node has to provide different SOAP endpoints (directly to the hostname, or for zoning purposes).
Most registry changes are system variables listed in the registry section at Manage the system >Maintenance > System variables.
psconfig\*\*.db is where Bravura Privilege keeps list files from discovered systems in 12.0.0+; by default, those files are useful only on the primary node and sending them to replica nodes is a waste of resources, especially at the end of each auto discovery.
- For the same reason, check the output of updinst -showconfig to make sure that the psconfig\*.db files are also blacklisted (and if not, add a blacklist rule for ^psconfig\\\\*.db)
- Filtering the logs for psupdate or updinst durations can suggest what other large files can be excluded from auto discovery if they take too long.
plugin\debug \ is where (mostly componentized) Python scripts using IDMLib-based logging place their input/output KVGs and like other log files, those are usually not needed on secondaries from the primary.
design\src\ files should never change after patching. They are Angular app requirements and there is no need for them to be propagated to secondary servers, let alone proxies.
Whitelists trump blacklists. This means if the same item is matched both by a blacklist regex and a whitelist one, the whitelist wins and the item is propagated.
If an entry is not blacklisted (or if it was by default blacklisted, but is modified with a whitelist entry):
- It copies any files changed on the primary inside the instance folder and subfolders, and it overwrites any changes. In other words, it deletes any new files created on the secondary nodes and if files are modified on secondaries, the changes are reverted and not backed up.
- It copies any registry changes made on the primary node and overwrites any changes on the secondary nodes (removes them if they were not on the primary).
The main Bravura Security Fabric installer only installs/checks for the 64-bit VC++ redistributables. The Connector Pack MSI will install/check for 32-bit and 64-bit, so do not depend on file propagation to copy all the connector pack files to other nodes and proxies.

In this section: