IceGrid Persistent Data
The IceGrid registry and node both store information in files. This section describes what type of information the registry and node are storing, and discusses backup and recovery techniques.
On this page:
Registry Database
Data Stored
The registry stores the following data in the LMDB database specified through the IceGrid.Registry.LMDB.Path property:
- Applications deployed using the
addApplicationoperation on theIceGrid::Admininterface (which includes the IceGrid GUI and command-line administrative clients). Applications describe servers, well-known objects, object adapters, replica groups, and allocatable objects. Applications can be removed with theremoveApplicationoperation. - Well-known objects registered using the
addObjectandaddObjectWithTypeoperations on theIceGrid::Admininterface. Well-known objects added by these operations can be removed using theremoveObjectoperation. - Adapter endpoints registered dynamically by servers using the
Ice::LocatorRegistryinterface. The propertyIceGrid.Registry.DynamicRegistrationmust be set to a value larger than zero to allow the dynamic registration of object adapters. These adapters can be removed using theremoveAdapteroperation. - Some internal proxies used by the registry to contact nodes and other registry replicas during startup. The proxies enable the registry to notify these entities about the registry's availability.
Client session and administrative sessions established with the IceGrid registry are not stored in this database. If the registry is restarted, these sessions must be recreated. For client sessions in particular, this implies that objects allocated using the allocation mechanism will no longer be allocated once the IceGrid registry restarts.
If the registry's database is corrupted or lost, you must recover the deployed applications, the well-known objects, and the adapter endpoints. You do not need to worry about the internal proxies stored by the registry, as the nodes and registry replicas will eventually contact the registry again.
Depending on your deployed applications and your use of the registry, you should consider backing up the registry's database, especially if you cannot easily recover the persistent information.
For example, if you rely on dynamically-registered adapters, or on well-known objects registered programmatically via the IceGrid::Admin interface, you should back up the registry database because recovering this information may be difficult. On the other hand, if you only deploy a few applications from XML files, you can easily recover the applications by redeploying their XML files, and therefore backing up the database may be unnecessary.
Be aware that restarting the registry with an empty database may cause the server information stored by the nodes to be deleted. This can be an issue if the deployed servers have databases stored in the node data directory. The Node Persistent Data section below provides more information on this subject.
Limits Imposed by the Registry Database
Key Size
A LMDB database consists of one or more persistent key-value maps, and the size of the keys in these maps is limited to 511 bytes. For example, IceGrid stores applications in a persistent map where the keys are the application names, encoded using the Ice encoding for strings, and this LMDB limitation means you cannot select an application name with an arbitrary size.
| IceGrid Registry Database Key | Slice Type | Max Encoded Size |
|---|---|---|
| Adapter ID | string | 511 bytes |
| Application Name | string | 511 bytes |
| Well-known Object Identity | Ice::Identity | 511 bytes |
| Well-known Object Type | string | 511 bytes |
If you attempt to save an application, adapter ID or well-known object that is too large for the LMDB database, IceGrid will throw an IceGrid::DeploymentException or an Ice::UnknownException depending on the operation invoked.
This maximum key size is not configurable. If you exceed this limit, you need to shorten the corresponding name, ID or identity.
Map Size
A LMDB database has a maximum size, known as its map size. The IceGrid registry database can store up to IceGrid.Registry.LMDB.MapSize megabytes of data in its database; any attempt to store more data will fail with an Ice::UnknownException. If you exceed this limit, increase IceGrid.Registry.LMDB.MapSize and restart the IceGrid registry.
If you don't set IceGrid.Registry.LMDB.MapSize, or set it to 0, IceGrid uses a map size of 10 MB on Windows, and 100 MB on Linux and OS X.
On Windows, LMDB immediately allocates a file with the given map size, while on Linux and OS X LMDB uses sparse files and the allocated data file starts small and grows as needed, until it reaches the configured limit.
The default MapSize provided by the IceGrid registry is expected to be sufficient for most applications. Unless you have an extremely large IceGrid deployment on Windows, we recommend keeping the default setting.
Use the mdb_stat utility to monitor the pages used by your IceGrid registry database. The example below shows a LMDB database with the default size on Linux (100 MB):
$ mdb_stat -e registry Environment Info Map address: (nil) Map size: 104857600 Page size: 4096 Max pages: 25600 Number of pages used: 18 Last transaction ID: 8 Max readers: 126 Number of readers used: 0 Status of Main DB Tree depth: 1 Branch pages: 0 Leaf pages: 1 Overflow pages: 0 Entries: 8
Backing up the Registry Database
You should consider making regular backups of your IceGrid registry database. We recommend using one of the following tools to perform backups while the IceGrid registry is running:
Node Persistent Data
Each IceGrid node stores information in a directory specified through its IceGrid.Node.Data property - the node's data directory. In IceGrid descriptors, the node.data variable is substituted with the path of the node data directory.
Each node stores configuration files, user data and occasionally database environments and distribution data, for each server in a sub-directory named servers/<server ID>, where <server ID> represents the unique server ID of that server. Per-server or per-service user data can be stored in the sub-directories named servers/<server ID>/data and servers/<server ID>/data_<service name>. In IceGrid descriptors, the server.data and service.data variables are replaced with the paths of the server or service data directory.
The node's data directory also contains a distrib directory to store per-application distribution data. This directory contains a subdirectory for each application that specifies a distribution and has a server deployed on the node.
If a server directory is deleted, the node recreates it at startup. The node will also recreate the server configuration files and the database environment directories. However, the node cannot restore the prior contents of a server's database environment or user data directory. It is your responsibility to back up the user data and database environment directories and restore them when necessary. If the server or application distribution data is deleted from the node's data directory, you can easily recover the deleted information by patching these distributions again using the IceGrid administrative tools.
If you store your server database environments outside the node's data directory (such as in a directory that is regularly backed up), or if you do not have any database environments inside the node's data directory, you do not need to back up the contents of the node's data directory.