Managing Port Usage
Large, complex configurations can use a large number of ports. The Port Authority searches for items in productions that have a setting with the name of *Port. It can access port information from multiple namespaces, instances, and servers and stores the collected data in a Document Database (%DocDB) Database/table. The resulting report enables you to determine which ports are configured for use. It does not reflect whether the port is actually being used when the report is generated. This information is useful when you need to select ports to use when adding productions to the configuration. The functionality provided is for reporting purposes only. Any data created or functionality added is not used in the processing of production messages. Consolidate report requires USE permissions for %Ens_Portal due to the call to %SYS.Ensemble::GetStatusAll() to find all local interoperable namespaces. Privileges to call %DocDB APIs are also required.
Configuring the Port Authority
The Port Authority consolidates information into a table in a single namespace. To select the namespace that contains this table, select Interoperability > Manage > Configuration > Setting Report Application Configuration. Choose a namespace from the drop-down list and select Apply. This page is protected by the resource %Ens_SettingsReportConfig. By default, read and write permission is given to %EnsRole_Administrator and read permission to %EnsRole_Operator.
Configuring a Port Authority Task
In order to generate a Port Authority report through the Management Portal, you need to create a task. Select System Operation > Task Manager > New Task. You can generate the Port Authority report on demand, or as a scheduled task.
For general information on how to create a task, see Using the Task Manager. The following list describes settings specific to a new Port Authority task.
-
Namespace to run task in—choose from the list of defined namespaces in which to run the task. You should select the same namespace you set as the location for the data table.
-
Task type—select Interoperability Productions Settings Report. Selecting this value opens the following list of task-specific settings.
-
SettingReportClass—Select Port Settings from the drop-down list.
-
AllNamespaces—Whether to include all available namespaces in the report. The default value is True.
-
SpecificNamespace—The specific namespace to include in the report if AllNamespaces is False.
-
IncludeExternalClients—Whether to include external clients that are marked as REST clients in the report. The default value is False. If True and SpecificExternalClientRegistryID is blank, the report includes all external clients. All clients included in the report must be able to run the Port Authority and be configured to run their own Port Authority report.
-
SpecificExternalClientRegistryID—If IncludeExternalClients is True, provides the registry ID for a single external client to include in the report. The external client registry ID is of the format: name||domain||version, for example, DevPorts||IRISInteroperabilityPorts||1. The report is limited to this external client. For more information on configuring an external client, see Configuring a Port Authority External-Service Registry.
-
ExternalClientRESTPath—Lets you specify an optional REST path for an external client, which overrides the default REST path.
-
LogExternalCallErrors—If the REST call returns a non-200 status, log a warning entry in the event log. The default value is False.
-
PostSaveProcessing—Whether to run the code to look for conflicts, free ports and reservations that are used. The default value is True.
-
-
Run task as this user—Choose from the list of defined users. To choose a different user than the one you are logged in as, you must have the %Admin_Secure:Use privilege. The user running the report needs permissions to access all namespaces that run productions and to access the data.
-
Open output file when task is running and Output file—An output file is not required because output is collected in the report table.
Configuring a Port Authority External-Service Registry
To configure an external client for use by the Port Authority use the External-Service Registry. Select Interoperability > Configure > External-Service Registry and select New Service. For general information on the External-Service Registry, see Administering the External Service Registry. The following list shows the properties and their values:
-
Name – User specified.
-
Domain – Use the DocDBName. For Ports this is IRISInteroperabilityPorts.
-
Version – 1
-
Service Protocol – REST
-
Lifecycle Stage – To disable querying, set to Defunct. All other options are currently treated as equal.
-
Endpoint – The URI of DocDB endpoint. Can be configured as per user requirements. The default, using the <baseURL> for your instance, is:http<s>://<baseURL>/api/docdb/v1/<namespace>/find/IRISInteroperabilityPorts.
-
Attributes – Name/Value pairs that are used to set properties of the adapter used by EnsLib.REST.GenericOperationOpens in a new tab.
-
Credentials with a value equal to an Interoperability Credentials ID entry. See Defining Production Credentials.
-
If the external endpoint is https then SSLConfig with a value equal to an existing TLS system configuration to use.
-
If the external endpoint is https then SSLCheckServerIdentity could be used as appropriate.
-
Using the Port Authority Report
The report is a snapshot of the state of the system the last time the report was generated. To view the report generated by the Port Authority, select Interoperability > View > Port Authority Report. This page and the %DocDB database are protected by the resource %Ens_PortSettingsReport. By default, read and write permission is given to %EnsRole_Administrator and read permission to %EnsRole_Operator.
The report view has the following tabs:
Each tab presents a table containing report data. At the top of each table column is a field which lets you filter the table contents based on the value of the column. In addition, buttons are provided at the top of the report page:
-
Export Current Page—Exports the current page content in tab-delimited format to a file with a .csv extension.
-
Import Data—Imports data from a tab-delimited .csv file. Enabled only for the Reservations and Advice tables. The first line of the file contains column headers, subsequent lines provide table records. You can export a Reservations or Advice report, edit the resulting file, or create one having the same format, and import. If the import source file provides a value for Reservation ID that matches a record already in the table, the original record is silently overwritten.
-
Reset Column Filters—Removes filtering from all columns in the table.
-
Refresh Page—The refresh button () refreshes the page content.
Production Ports
The Production Ports tab lists all the ports found that are configured for use, with additional information about how they are being used. The content of the report reflects status at the time the report is run. It gathers information from all active productions, including those that are stopped.
-
Server/Mirror—Each port is used by a production running on a server or a mirror, so one or the other of these two columns contains a value.
-
Instance—The name of the InterSystems IRIS instance from which the data point was retrieved. If an instance is in a mirror, then the report includes data from one instance per mirror/namespace combination.
-
Production—The name of the InterSystems IRIS Production from which the data point was retrieved.
-
ItemName—The name of the item in the production that is configured to use the port.
-
Port—The port number. Two text fields and a Find button at the top of the column let you limit the ports displayed to those falling between specified beginning and ending port numbers.
-
Direction—Direction of port traffic. Available values are Inbound and Outbound.
-
Interface—The network interface, if any, that the port is bound to.
-
IPAddress—The IP address of the server the port is attached to, for outbound connections.
-
Enabled—Whether the Item was enabled when the data point was retrieved. Available values are Yes and No.
-
Categories—The category of the Item from which the data point was retrieved.
-
Namespace—The name of the InterSystems IRIS Namespace that from which the data point was retrieved.
-
Mode—The instance mode, for example, LIVE or DEVELOPMENT.
-
Partner—The Specific Business Partner ID.
Port Reservations
The Port Reservations tab enables you to reserve ports for future use. This reservation feature records your intention to use the ports. It is purely informational and does not configure the ports or in any way prevent their use by others. This part of the report warns you if ports you are trying to reserve are already configured for use or reserved for future use by other users.
A number of columns on this tab have the same name and function as on the Production Ports tab. New columns on this tab are:
-
Mode (extended)—Reports both the four system modes, Live, Test, Development, and Failover, and any modes added for the site.
-
Comment—A comment about the reservations.
-
User—The InterSystems IRIS Username of the user making the reservation.
-
LastModified—Date when this reservation was last modified.
-
Expiry—The expiration date for the reservations.
-
In Use—A flag to indicate whether the reserved port is in use.
-
ReservationID—A unique ID number assigned to each reservation.
Edit and Delete buttons at the end of each row enable you to edit and delete the reservation.
To create a new reservation, select the Add button () and fill in the form:
-
Server/Mirror—Select a value for the Server or Mirror from the drop-down list. If an instance is a mirror member then use the mirror name.
-
Instance—Select the instance from the drop-down list.
-
Production—Select the production from the drop-down list.
-
Mode (extended)—Enter the instance mode. In addition to entering one of the system specified, modes Live, Test, Development, and Failover, it is possible to enter any text to use as the site requires.
-
Number of Consecutive Ports—Along with Start Port and End Port, provide ways to the specify a range of consecutive ports. Range requests are valid only for Inbound ports. If you use this field to supply the required number of consecutive ports, the form automatically sets Start Port and End Port to values that provide the first occurrence of the requested number of ports within the searched range. You can use the Reservation Boundary, set on the Port Usage Advice tab, to bound the range searched. The default range is 1074 to 65535. An individual reservation table entry is created for each reserved port.
-
Start Port—The starting port for a group of consecutive ports. Can be set automatically in response to Number of Consecutive Ports, or you can set it directly.
-
End Port—The ending port for a group of consecutive ports. Can be set automatically in response to Number of Consecutive Ports and Start Port, or you can set it directly. If you specify both Start Port and End Port, Number of Consecutive Ports is ignored.
-
Direction—Specify Inbound or Outbound.
-
Interface—If the port is bound to a network interface, enter it here.
-
IPAddress—Enter the IP address of the server the port is attached to, for outbound connections.
-
ItemName—Enter a name for the item in the production that is configured to use the port. Cannot be used when configuring a range of ports.
-
Comment—A comment describing the reservations.
-
User—The InterSystems IRIS Username of the user making the reservation.
-
Partner—The Specific Business Partner ID.
-
Expiry—Enter an expiration date for the reservations. The default is 45 days from the creation of the reservation.
Select Save to create the specified reservations. If a port you are trying to reserve is already in use or reserved you receive a warning to that effect:
Select Cancel to abort the Save and avoid reserving an unavailable port.
Port Usage Advice
The Port Usage Advice tab enables you to limit the search to specified groups of port numbers when creating port reservations, and serves as a general advice repository. A number of columns on this tab have the same name and function as on the Production Ports and Port Reservations tabs. New columns on this tab are:
-
Classification—Enter arbitrary text, or select the value Reservation Boundary from the available list. Reservation Boundary identifies boundary suggestions for inbound reservations. Boundary identification is based on server or mirror and optional production, instance & mode fields.
The default used to bound an inbound reservation range request is 1074 to 65535.
You can enter other site-specific Classification entries as required.
-
Start Port—The starting port for a group of consecutive ports.
-
End Port—The ending port for a group of consecutive ports.
-
AdviceID—A unique ID number assigned to each advice record.
To create a new usage advice record, select the Add button () and fill in the form:
-
Classification—Either select Reservation Boundary or enter a site-specific classification.
-
Server/Mirror—Select a value for the Server or Mirror from the drop-down list.
-
Instance—Select the instance from the drop-down list.
-
Production—Select the production from the drop-down list.
-
Mode (extended)—Enter the instance mode.
-
Start Port—Specify the starting port for a group of consecutive ports.
-
End Port—Specify the ending port for a group of consecutive ports.
-
Direction—Specify Inbound or Outbound.
-
Comment—A comment describing the reservations.
-
User—The InterSystems IRIS Username of the user making the reservation.
-
Partner—The Specific Business Partner ID.
Inbound Production Conflicts
The Inbound Production Conflicts tab shows you ports that have potential conflicts calculated at the time the report is run. Columns on this tab have the same name and function as on previously described tabs. The table is populated with items containing ports that are used more than once. This information allows you to anticipate potential port-usage conflicts. Note that only port values from production settings are used.
Ranges Not Used in Productions
The Ranges not used in Productions tab shows you ranges of unused port numbers calculated at the time the report is run. Columns on this tab have the same name and function as on previously described tabs. The table is populated with ranges of port numbers that are not used in any production. This information helps you to select groups of consecutive ports when configuring port advice or port reservations. Note that only port values from production settings are used.