Distributed Data Management Guide
Configuring Distributed Systems
An ECP application consists of one or more ECP data server systems data providers distributing to one or more ECP application server systems data consumers. The primary means of configuring an ECP application is using the [System] > [Configuration] > [ECP Settings]
page of the Management Portal. Navigate to this page by clicking
under the System Administration
under the Connectivity
Once you have decided how to distribute your data, configuring an ECP application is very straightforward:
If you are using Security, see the Managing ECP Privileges
section for a discussion on how resources, roles, and privileges are managed in an ECP configuration.
Specify each system that requests data as an ECP application server for each data server with which it wishes to communicate. See the Configuring an ECP Application Server
section for instructions.
In addition, configure each ECP application server system so that it can see remote data in the defined ECP data servers. See the Configuring ECP Remote Data Access
section for instructions.
A system operating as an ECP data server can simultaneously act as an ECP application server, and vice versa. You may configure your ECP application and data servers in any order; you do not need to enable an ECP data server before defining an application server.
ECP Client/Server Compatibility
Configuring an ECP Data Server
To configure a system as an ECP data server, you must first enable the ECP service from the [System] > [Security Management] > [Services]
page of the Management Portal. Click %Service_ECP
, select the Service enabled
check box in the Edit Service dialog, and click
. This is the only configuration setting required to use this system as an ECP data server.
Update the Maximum number of application servers
setting to specify the maximum number of application servers that can possibly access this data server simultaneously. InterSystems IRIS allocates a limited number of application server nodes. Increase the default value of 1
up to a maximum of 254
to avoid a system restart, which is required when the number of connections becomes greater than the number of allocated nodes.
If you increase the maximum number of application server, you must restart InterSystems IRIS.
The ECP data server is now ready to accept connections from valid ECP application servers.
You may wish to restrict access to the data server. See the following sections for ways to do this:
Restricting ECP Application Server Access
You can restrict which systems can act as ECP application servers for an ECP data server system by performing the following steps:
From the [System] > [Security Management] > [Services]
page, click %Service_ECP
If you enter IP addresses in the Allowed Incoming Connections
list, the ECP data server only accepts incoming ECP connections from application servers whose IP is in the list. If the list is empty, any application server can connect to this system if the ECP service is enabled.
Specifying ECP Privileges and Roles
For each specified IP address or range of addresses, click Edit
to display the Select Roles
area that allows you to specify the roles associated with the connection from the IP address. By default, the connection holds the %All role. If you specify one or more other roles, these roles are the only roles that the connection holds. Hence, a connection from an IP address with the %Operator role has only the privileges associated with that role, while a connection from a different IP address with no associated roles (and therefore %All) has all privileges.
To specify the roles associated with an IP address:
Select roles from those listed under Available
and click the right arrow to add them to the Selected
To remove roles from the Selected
list, click them and then click the left arrow.
To add all roles to the Selected
list, click the double right arrow; to remove all roles from the Selected
list, click the double left arrow.
to associate the roles with the IP address.
The Managing ECP Privileges
section discusses how InterSystems IRIS manages privileges within an ECP configuration.
The following discussion assumes that resources and roles refer to the same assets on each machine. To be granted access to a resource on the ECP data server, the role held by the process on the application server and the role set for the ECP connection on the data server must both include permissions for the same resource.
By default, InterSystems IRIS grants the ECP data server the %All privilege when the data server runs on behalf of an ECP application server. This allows it to return any data in any database that the application server requests. InterSystems IRIS restricts access to this data on the application server based on the privileges of the user requesting the data on the application server.
For example, for a user on the application server who only has privileges for the %DB_USER
resource, data in the USER
database on the data server is available (which by default is assigned the %DB_USER
resource), but attempting to access the SAMPLES
database on the data server results in a <PROTECT>
error. If a different user on the application server has privileges for the %DB_SAMPLES
resource, then the SAMPLES database on the data server is available.
You can also restrict the set of roles on the data server based on the IP Address of the application server. For example, on the data server you can specify that when interacting with an application server named NODE_A
the only available role is %DB_USER
. In this case, users on the application server granted the %DB_USER
role can access the USER
database on the data server. However, users on the application server with %DB_SAMPLES
access receive a <PROTECT>
error if they try to access the SAMPLES
database on the data server (since the data server is only set up with %DB_USER
The following are exceptions to this behavior:
InterSystems IRIS always grants the ECP data server the %DB_CACHESYS role since it requires Read access to the CACHESYS
database to run. This means that a user on an ECP application server with %DB_CACHESYS can access the CACHESYS
database on the ECP data server.
To prevent a user on the application server from having access to the CACHESYS
database on the data server, there are two options:
Do not grant the user privileges for the %DB_CACHESYS resource.
On the data server, change the name of the resource for the CACHESYS
database to something other than %DB_CACHESYS, making sure that the user on the application server has no privileges for that resource.
If the ECP data server has any public resources, they are available to any user on the ECP application server, regardless of either the roles held on the application server or the roles configured for the ECP connection.
Changes both to the configuration of the ECP connection and to the public permissions on resources require a restart of InterSystems IRIS before taking effect.
Security-related ECP Error Reporting
The behavior of security-related error reporting with ECP varies depending on whether the check fails on the application server or the data server and the type of operation:
If the check fails on the application server, there is an immediate <PROTECT>
For synchronous operations on the data server, there is an immediate <PROTECT>
Configuring an ECP Application Server
To configure a system as an ECP application server, you define an ECP data server from which to retrieve data. Add this remote ECP data server by performing the following steps:
Enter the following information for the data server:
Enter a logical name for the convenience of the application system administrator.
Host DNS Name or IP Address
Specify the host name either as a raw IP address (in dotted-decimal format or, if IPv6 is enabled, in colon-separated format) or as the Domain Name System (DNS) name of the remote host. If you use the DNS name, it resolves to an actual IP address each time the application server initiates a connection to that ECP data server host. For more information, see the IPv6 Support
section in the Configuring InterSystems IRIS
chapter of the System Administration Guide
When adding a mirror primary as an ECP data server, do not enter the virtual IP address (VIP) of the mirror, but rather the DNS name or IP address of the current primary failover member.
The port number defaults to 1972
; change it as necessary to the superserver port of the InterSystems IRIS instance on the data server.
Once you add a remote ECP data server, it appears in the list of defined data servers this application server can connect to at the bottom of this same portal page. Add additional ECP data servers to the list using the
link. Remove or edit server definitions using the
links, respectively. You may also click
of the connection. See the Monitoring Distributed Applications
chapter for details.
You may add as many data servers as allowed by the Maximum number of data servers
setting. Update this value to specify the maximum number of server connections the application server may need later so that InterSystems IRIS reserves enough system resources so as not to require a restart each time you add a data server. Increase the default value of 2
up to a maximum of 254
If you increase the maximum number of data servers, you must restart your InterSystems IRIS.
Your system is ready to act as an ECP application server. No further user intervention is required; when the ECP application server needs access to the ECP data server, it automatically establishes a connection to the server.
Configuring ECP Remote Data Access
After defining a list of one or more ECP data servers for an ECP application server, configure the ECP application server system so that it has access to data stored in the ECP data server system. Do this by defining a remote database on the ECP application server system.
A remote database
is a database that is physically located on an ECP data server system, as opposed to a local database
which is physically located on the local application server system.
To define a remote database on the ECP application server, perform the following steps:
Navigate to the [System] > [Configuration] > [Remote Databases]
page of the Management Portal.
to invoke the Database Wizard
, which displays a list of the logical names (the name you used when you added it to the list of ECP data servers) of the remote data servers on the application server.
Click the name of the appropriate ECP data server and click
The portal displays a list of database directories on the remote ECP data server. Select one of these to serve as the remote database.
Enter a database name (its name on the ECP application server; it does not need to match its name on the ECP data server) and click
. You have defined a remote database.
Next, define a new namespace (or modify an existing namespace) to view the data in the remote database as you would in a local database.
By using the Namespace Wizard
in the Management Portal, you can define a namespace and a remote database at the same time, thereby combining these two procedures for adding a remote database.
To define a new namespace that views the data in a remote database perform the following steps:
Navigate to the [System] > [Configuration] > [Namespaces]
page of the Management Portal.
Fill in the form with the following fields:
Choose a database for the new namespace. Select the remote database from the list (remote and local databases are listed together) and click
. You have a new namespace that is mapped to a remote database.
Any data retrieved or stored in this namespace is loaded from and stored in the physical database on the ECP data server and updated in the local application server system cache if it is already cached.
First, all the instances in an ECP configuration need to be within the secured InterSystems IRIS perimeter (that is, within an externally secured environment). This is because ECP is a basic security service (not a resource-based service), so there is no way to regulate which users have access to it. For more information on basic and resource-based services, see the Available Services
section of the Services
chapter of the Security Administration Guide