Configuring Enterprise Manager Federation

18 Configuring Enterprise Manager Federation

Enterprise Manager Federation allows customers to have a consolidated view of all Enterprise Manager sites providing a summary of all Enterprise Manager sites deployed across the enterprise.

This chapter contains the following sections:

For troubleshooting, see Enterprise Manager Federation Troubleshooting.

Overview

Enterprise Manager Federation allows customers to have a consolidated view of all Enterprise Manager sites providing a summary of all Enterprise Manager sites deployed across the enterprise.

The Enterprise Manager Federation user interface offers federated summary and also, links to specific Enterprise Manager sites summary pages for in depth analysis. The Federation Overview page offers federated summary for the following areas: Targets summary, Incidents summary, Problems summary and Jobs summary.

The Enterprise Manager Federation supports the use of cURL commands and REST API.

Enterprise Manager Federation Dashboard

The federated Enterprise Manager sites data is accessible from a single interface. The Enterprise Manager Federation Dashboard summarizes:

Targets
Incidents
Problems
Jobs

You can also drill down from any of the summary options described above. For example, you can drill down into an individual Enterprise Manager's All Targets page, Job activity page or Incident overview page for details.

Enterprise Manager Federation Dashboard

Enterprise Manager Federation Set Up and Configuration

The following steps are required to be executed only once by any EM Super Administrator user to set up the Enterprise Manager Federation:

Step 1: Set Up the Primary Enterprise Manager Site

Step 2: Add list of Enterprise Manager sites to be federated

Step 3: Import Certificates

Step 1: Set Up the Primary Enterprise Manager Site

The Enterprise Manager administrator needs to select a Primary Enterprise Manager site from the entire enterprise. It can be any Enterprise Manager site running Enterprise Manager 13c Release 4 Update 5 (13.4.0.5) or higher version.

To set up the Primary Enterprise Manager site, you need to use emctl utility and run the following:

emctl set property -name "oracle.sysman.federation.masterEM" -value "true"

Step 2: Add list of Enterprise Manager sites to be federated

The Enterprise Manager administrator needs to add a list of the Enterprise Manager sites that will be part of the federation and their respective URLs to the Primary Enterprise Manager site using cURL command line tool. Any Enterprise Manager 13c Release 4 Update 4 (13.4.0.4) or higher can be a federated site.

To add a list of Enterprise Manager sites, you can use cURL command line tool and run the following:

curl -X POST <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{"siteURL":
"<EM_site1_URL>:EM_site1_port>", "name": "host"}'

Example using cURL

curl -X POST https://primary_em.sample.com:5416/em/websvcs/restful/fed/emSites -u 'user1' -H 'content-type: application/json' -d '{"siteURL":
"https://em_site1.sample.com:5416", "name": "host"}'

Response

The response from this command returns the following:

Successful operation: It returns the newly generated EM Site GUID for a successful response. This value will be used in the following step. For example, it will return "422cf85c13354336874a1971c1d57a70" as the EM Site GUID for em_site1.sample.com site.
Invalid input: It returns an error code and a message for a failed response.

The cURL command supports one Enterprise Manager site at a time. Repeat this step to add more Enterprise Manager sites as federated sites. The maximum number of federated Enterprise Manager sites supported is 10.

Step 3: Import Certificates into Primary Enterprise Manager site's trust store

To allow https connectivity to other Enterprise Manager sites, the Enterprise Manager administrator imports the federated Enterprise Manager sites certificates into the Primary Enterprise Manager site's trust store.

The administrator needs to ensure the certificates provided are PEM encoded (DER encoded certificates are not supported).

The customer will provide other Enterprise Manager's certificate by using cURL command line tool

curl -X POST <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM Site GUID>/certificates -u '<EM_user_from_Primary_EM_host>' -H 'content-type: multipart/form-data' -F file=@<certificate file>

Example using cURL

curl -X POST https://primary_em.sample.com:5416/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/certificates -u 'user1' -H 'content-type: multipart/form-data' -F file=@em_site1.pem

Response

The response from this command returns the following:

Successful operation: It returns the Certificate GUID and the PEM content of the file uploaded for a successful response.
Invalid input: It returns an error code and a message for a failed response.

The certificate is stored in Enterprise Manager credential framework.

For information about how to secure Enterprise Manager, including configuring custom certificates, see Custom Configurations in the Enterprise Manager Cloud Control Security Guide.

Enterprise Manager Federation Post Configuration Tasks

The following post configuration tasks are required to be performed by any individual user who wants to have access to the Enterprise Manager Federation Dashboard which resides in the Primary Enterprise Manager site. Users will need to create credentials and link it to the federated Enterprise Manager site. The credentials are private to that user and not shared.

Create credentials for the user

To connect to a federated Enterprise Manager site, you need to create credentials for the user in the Primary Enterprise Manager site.

A credential includes user name, password and an optional credential name. It's private and not shared with others.
```
curl -X POST <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/credentials -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{"userName": "<user_name>", "password": "<password>", "name": "<optional_credential_name>"}'
```
Example using cURL
```
curl -X POST https://primary_em.sample.com:5416/em/websvcs/restful/fed/credentials -u 'user1' -H 'content-type: application/json' -d '{"userName": "emuser", "password": "oracle", "name": "default"}'
```
Response

The response from this command returns the following:
- Successful operation: The newly created Credential GUID is returned for a successful response. For example, "3f1e2492016740f9aae9d2647d09efb0". This value will be used in the following step.
- Invalid input: The error code and message are returned for a failed response
Note:

If there's a credentials change in any Enterprise Manager site, the new credentials also must be updated in the Primary Enterprise Manager site (Enterprise Manager Federation) using the following command:
```
curl -X PUT <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/credentials -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{"userName": "<user_name>", "password": "<password>", "name": "<optional_credential_name>"}'
```
Link the user credentials to federated Enterprise Manager site

After the credentials are created, you need to link the user credentials to the federated Enterprise Manager site.

The Enterprise Manager Federation dashboard uses the user credentials to retrieve data from the federated Enterprise Manager site using the value of the EM Site GUID.
```
curl -X POST <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM Site GUID>/credential -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{"id": "<Credential GUID>"}'
```
Example using cURL
```
curl -X POST https://primary_em.sample.com:5416/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/credential -u 'user1' -H 'content-type: application/json' -d '{"id":"3f1e2492016740f9aae9d2647d09efb0"}'
```
- Successful operation: A string is returned for a successful response.
- Invalid input: The error code and message are returned for a failed response.
(Optional) Configure groups to view federated Enterprise Manager sites by groups

Starting with Enterprise Manager 13 Release 5 Update 1 (13.5.0.0.1), group based filtering is supported by configuring groups to view information specific to selected group(s) across federated Enterprise Manager sites.

Groups are used to logically organize, manage and monitor the targets in individual Enterprise Manager sites or federated Enterprise Manger sites. Creating a federation group in the primary Enterprise Manager enables the federation dashboard to get data specific to the configured groups from the federated Enterprise Manager sites. For example, the super administrator can create groups for specific applications or business units: One group for Customer Service applications and other group for Finance applications. The groups created by the super administrator user are available to all users.
Requirement:
- The Primary Enterprise Manager site must have installed Enterprise Manager 13c Release 5 Update 1 (13.5.0.0.1) or higher.
- The federated Enterprise Manager sites must have installed Enterprise Manager 13c Release 4 Update 9 (13.4.0.0.9) or higher.
To add a group, you can use the following cURL command:
```
curl -X POST https://<Primary_EM_host_name>.<Primary_EM_host_domain>/em/websvcs/restful/fed/composites -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{ "targetName":"<Group_Name>", "targetType":"composite"}'
```
For example, to add a group called "Finance DB", use the following command:
```
curl -X POST https://primary_em.sample.com/em/websvcs/restful/fed/composites -u 'superadmin' -H 'content-type: application/json' -d '{ "targetName":"Finance DB", "targetType":"composite"}'
```

After the groups are configured, Enterprise Manager Federation will have two dashboard types available:

By Sites

It allows filtering down data to specific federated group across all federated Enterprise Manager.
By Groups

It consolidates data for all federated groups across all federated Enterprise Manager sites. This dashboard is useful for users interested to see data only related to the federated groups, and not the whole enterprise.

Enterprise Manager Federation Troubleshooting

This section covers common troubleshooting tasks for Enterprise Manager Federation using cURL command line tool for the following EM Federation resources:

EM Site Management

Get EM site

curl -X GET <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X GET https://primary_em.sample.com:5416/em/websvcs/restful/fed/emSites -u 'user1'

Update EM site

curl -X PUT <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID> -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d ' {"siteURL": "<EM_site1_URL>:EM_site1_port>", "name": "ProdHost"} '

For example:

curl -X PUT https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70 -u 'user1' -H 'content-type: application/json' -d ' {"siteURL": "https://em_site1.sample.com:5416", "name": "ProdHost"} '

Delete EM site

curl -X DELETE <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID> -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X DELETE https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70 -u ‘user’

Note:

The <EM-SITE_GUID> value is returned when creating an EM Site. You can also obtain it using the GET API.

EM Certificate Management

Get certificate

curl -X GET <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID>/certificates -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X GET https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/certificates -u ‘user1’

Delete certificate

curl -X DELETE <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID>/certificates -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X DELETE https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/certificates -u ‘user1’

Note:

The <EM-SITE_GUID> value is returned when creating an EM Site. You can also obtain it using the GET API.

EM Credentials Management

Get credentials

curl -X GET <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/credentials -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X GET https://primary_em.sample.com/em/websvcs/restful/fed/credentials -u ‘user1’

Update credentials

curl -X PUT <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/credentials/<CREDENTIAL_GUID> -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d ' {"userName": "<username>", "password": "<user_password>", "name": "default"}'

For example:

curl -X PUT https://primary_em.sample.com/em/websvcs/restful/fed/credentials/3f1e2492016740f9aae9d2647d09efb0 -u ‘user1’ -H 'content-type: application/json' -d ' {"userName": "abc", "password": "abc123”, "name": "default"}'

Delete credentials

curl -X DELETE <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/credentials/<CREDENTIAL_GUID> -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X DELETE https://primary_em.sample.com/em/websvcs/restful/fed/credentials/3f1e2492016740f9aae9d2647d09efb0 -u ‘user1’

EM Credentials Mapping

Get credentials mapping

curl -X GET <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID>/credential -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X GET https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/credential -u ‘user1’

Update credentials mapping

curl -X PUT <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID>/credential -u '<EM_user_from_Primary_EM_host>' -H 'content-type: application/json' -d '{ "id":"<CREDENTIAL_GUID>" }'

For example:

curl -X PUT https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/credential -u ‘user1’ -H 'content-type: application/json' -d '{ "id”:”5ef12492016740f9aae9d2647d09efb0" }'

Delete credentials mapping

curl -X DELETE <Primary_EM_host_URL>:<Primary_EM_host_port>/em/websvcs/restful/fed/emSites/<EM-SITE_GUID>/credential -u '<EM_user_from_Primary_EM_host>'

For example:

curl -X DELETE https://primary_em.sample.com/em/websvcs/restful/fed/emSites/422cf85c13354336874a1971c1d57a70/credential -u 'user1'