Manage Deployments from the Service Manager

About Service Manager

The Service Manager is the primary watchdog service within Oracle GoldenGate MA that allows you to control and administer the deployments and associated services running on the host server.

From OGGCA you can configure the Service Manager to run in three different modes:

• Manually
• As a Daemon
• Integrated with XAG agent

Its primary functions include the following tasks:

• View and manage the status of microservices
• Manage Deployment Configuration
• Manage Service Manager Configuration
• Start and stop deployments
• Access the microservices associated with a deployment
• Access details for Administration Service, Distribution Service, Performance Metrics Service, and Receiver Service
• Add and Manage Oracle GoldenGate Users
• Add and Manage Certificates
• Add and Manage Authorization Profile for External Identity Providers
• Monitor Log Information for Diagnosing Errors
• Enable and Manage Debug Logs

Log in to Service Manager

To start using your Oracle GoldenGate MA deployment, you have to connect to the Service Manager:

1. Open a web browser and connect to the Service Manager that you created with Oracle GoldenGate Configuration Assistant. The URL is similar to http://host:port, where host is the name of the service or IP of the service that is running the Service Manager and port is the port number of the Service Manager. For a secure deployment, the URL is similar to https://localhost:9001.

2. Enter the user name and password you created during deployment and sign in.

Start and Stop the Service Manager

The start and stop process of the Service Manager within Oracle GoldenGate Microservices Architecture is different based on how the Service Manager is configured within your environment.

• If the Service Manager is configured in manual mode then there are scripts in the $DEPLOYMENT_HOME/servicemanager/bin directory that you can run to start or stop the Service Manager. The $DEPLOYMENT_HOME is the directory where Oracle GoldenGate is installed.

  • To start the Service Manager: $DEPLOYMENT_HOME/servicemanager/bin/startSM.sh
  • To stop the Service Manager: $DEPLOYMENT_HOME/servicemanager/bin/stopSM.sh

  Note:

  If you want to start or stop the Service Manager, you also have to set the $OGG_ETC_HOME and $OGG_VAR_HOME to the Service Manager sub-directories.

• If the Service Manager is configured as a daemon, the scripts required to start or stop for manual interaction are not created. The operating system is responsible for starting or stopping the Service Manager.

  For OEL 7 and OEL 8:

  systemctl start OracleGoldenGate
  
  systemctl status OracleGoldenGate
  
  systemctl stop OracleGoldenGate

• If the Service Manager is configured to run with the XAG agent in an Oracle Cluster Ready Service (CRS); then the start and stop process is handled by the CRS stack.

Topics:

Add Users to a Deployment

Each deployment has its own set of users with specific roles. The administrator account user, which is created when the Service Manager is created for a host, can log into the Service Manager and other microservices. This user can also create users with specific roles to access or operate Oracle GoldenGate processes. This administrator account user can access all deployments that are added to this existing Service Manager.

However, all other users created from either the Service Manager or Administration Service are associated with the specific deployment. These users are not available with other deployments on the same host server.

Each deployment has its own set of users with specific roles. The administrator account user, which is created when the Service Manager is created for a host using OGGCA, can log into the Service Manager and other microservices. This user can also create users with specific roles to access or operate Oracle GoldenGate processes. This administrator account user can access all deployments that are added to this existing Service Manager. However, all subsequent users created from either the Service Manager or Administration Service are associated with the specific deployment. These users are not available with other deployments on the same host server. The other users are specific to the MA deployment and the security user needs to create users to every MA deployment individually.

To create users from the Service Manager or Administration Service:

1. Log in to either the Service Manager or the Administration Service.

2. From the left navigation pane, select Administrator.

3. Click Users (+) to add users.

4. Enter a unique user name.

5. Select one of the roles from the Role list box. The options are User, Operator, Administrator, and Security.

   Role ID	Privilege Level
   User	Allows information-only service requests, which do not alter or effect the operation of either the MA. Examples of Query/Read-Only information include performance metric information and resource status and monitoring information.
   Operator	Allows users to perform only operational actions, such as creating, starting and stopping resources. Operators cannot alter the operational parameters or profiles of the MA server.
   Administrator	Grants full access to the user, including the ability to alter general, non-security related operational parameters and profiles of the server.
   Security	Grants administration of security related objects and invoke security related service requests. This role has full privileges.

6. Select the user type from the Type list box as Password or Certificate.

   If you select the user type as Password, then the authentication is done based on the username and password.

   If you select the user type as Certificate, then the user will authenticate itself by presenting a client certificate. After you select the Certificate option, you need to enter the common name (in the certificate that will be presented such CN="certuser").

   Note:

   The certificate is with the user and not saved by the Oracle GoldenGate service. When presented for authentication, the Oracle GoldenGate service first authenticates that the certificate presented can be trusted and then checks if the common name in the certificate has been registered as a valid user. If yes, it will assign the appropriate user role.

7. Enter information that describes the user.

8. Click Submit. The user is registered.

Topics:

Edit Users

User role cannot be changed. You must delete a user and add it, as required. However, you can modify or edit the following user attributes:

• You can switch the User Type from Basic to Certificate or the other way around.
• You can also change the password for the user, if required.

To edit user attributes:

1. Navigate to the Administrator page from the Service Manager or Administration Service.

2. Click the Edit User (pencil) in the Action column of the Users table.

3. Change the required attribute.

4. Click Submit to confirm the modifications to the user attributes.

Delegate User Authentication and Authorization to an External ID Provider

Learn about delegating user authentication and authorization to an external ID provider.

Topics:

Configure the Authorization Profile to Set Up IDCS Access Credentials

Oracle GoldenGate interoperates with external identity provider Oracle Identity Cloud Service (IDCS) for authentication and authorization of user credentials that are associated with your deployment.

After you set up the Oracle Identity Cloud Service (IDCS) user credentials in OGGCA on the Administrator Account screen, you need to perform these steps to set up an authorization profile for IDCS. This authorization profile will allow connecting and accessing the IDCS server to authorize users for Oracle GoldenGate.

To configure this type of user authentication and authorization, you need to create an authorization profile in Oracle GoldenGate.

Access the Authorization Profile

Use the following steps to set up this type of authorization profile for your deployment:

1. Click the deployment name or the Service Manager name from the Service Manager Overview page's Deployment section.
2. From the Deployment or Service Manager Details page, click the Authorization Profiles tab.
3. Click the plus sign (+) next to the Profiles section to start creating an authorization profile. Enter the following details for the profile:
   • Profile Name: Name of the authorization profile.
   • Description (optional): Short summary of the profile being created.
   • Enable Profile: Activates the profile for the deployment.
   • Authorization Profile Type: IDCS
   • Tenant Discovery URI: IDP server's OpenID Discovery Docs endpoint (/.well-known/openid-configuration).
   • Client ID: IDP application’s client ID
   • Client Secret: IDP application’s client secret (securely stored)
4. In the Group Mapping section, the user mapping for IDCS groups to Oracle GoldenGate user roles is configured. You need to enter the name of the IDCS group with the corresponding user role. These values are case-sensitive. Here are the user role options that map the name of a group with respective role in IDCS:
   • Security Role
   • Administrator Role
   • Operator Role
   • User Role
5. Click Submit to create an authorization profile.
6. To enable the authorization profile for your deployment, select the authorization profile that you want to enable and click the Enable Profile toggle switch.

Manage Certificates for Deployments

Learn about managing certificates for deployments.

Topics:

Apply Certificates to an Oracle GoldenGate Deployment

Certificates can apply to:

• A specific deployment: These certificates are local to the deployment. See Create Different Types of Certificates for a Secure Deployment.

• Shared across deployments added to the same Service Manager: These are shared certificates created from the Service Manager Certificate Management page. These certificates can be shared across multiple deployments supervised by one Service Manager.

• Different source and target deployments: These are called external certificates (extern) with different source and target deployments. See unresolvable-reference.html#GUID-00744E00-2C19-4232-BC59-3C49E82A7A9A.

Note:

Adding a non-CA self-signed certificate as a trusted certificate using Certificate Management page's CA Cert section is not supported and will result in an error.

Replace Certificates in a Deployment

You cannot renew a certificate. You can only replace it with a new certificate. Make sure to check the expiry details of certificates that you intend to replace. Use the following steps to replace certificates:

1. Click the Certificate Management tab from the left navigation pane of the Service Manager.
2. Select the deployment from the drop-down list to view information about the server, client certificates, and CA certificates.
3. Click the Detail icon from the Action column of the certificate store table to view details about the certificate including certificate start and expiration dates, shown in the following image:
   
4. Click the Replace (pencil) icon to replace server certificates.
5. Click the Delete icon in the Action column to delete the certificate.

Add Client Certificate

To add a client certificate:

1. Click the plus (+) sign next to the Client Certificates section. The Add Client Certificate dialog box appears.
2. Enter the following details for the client certificate:
   • Unique Name: Name of the certificate.
   • Certificate PEM: Enter a certificate .pem file or upload a .pem file.
   • Private-Key PEM: Enter or upload the private key for the .pem file.
   • CA Certificates: Enter or upload the CA certificate.
3. Click Add.

Add a CA Certificate

To add a CA certificate:

1. Click the plus (+) sign next to CA Certificates. The Add CA Certificate dialog box appears.
2. Enter the following details for the CA certificate:
   • Unique Name for the CA certificate.
   • Certificate PEM value can be entered in the box or uploaded.
   • Certificate location can be shared. CA Certificates for the Service Manager are always shared and cannot be local. When adding or replacing CA certificates, the Shared option is always force-checked.
3. Click Add.

Modify Configuration for the Service Manager

Learn about how to modify configuration for the Service Manager.

Topics:

Access the Service Manager Information Page

To modify the Service Manager:

1. Select the Service Manager from the Deployments section of the Service Manager Overview page.
2. Use the Service Manager information page to edit the configuration for the Service Manager using these tabs. The tabs that you can edit for the Service Manager are the same as the tabs for the deployment.

   The following tabs can be used to set up options for the Service Manager:

Details Tab

Use this tab to review the selected deployment configuration. All the deployment directories that you configured with OGGCA are displayed. For Oracle database, you can only edit the Oracle GoldenGate home (OGG_HOME) directory. This allows you to use a different installation than the one you originally configured.

For SQL Server and Db2 z/OS, you need to follow the steps given in the Setting up Environment Variables for Db2 z/OS, Setting up for DB2 z/OS, and Setting up for SQL Server sections in the Using Oracle GoldenGate on Oracle Cloud Marketplace guide.

Note:

It's important to do the settings for SQL Server and DB2 z/OS to make sure that the Administration Service starts when using either of these databases.

Configuration Tab

Use this tab to review and change the selected deployment environment variables. The environment variables that you configured with OGGCA are displayed. You can add new variables, modify existing variables, and delete selected variables. For Oracle database, make sure that TNS_ADMIN is set. See Specify Environment Variables for more information.

Certificates

Use this tab to add and manage certificates for the server, client and CA certificates. There is a difference between the Certificates tab and the Certificate Management page. The Certificates tab is associated with the deployment or Service Manager because you arrive at this tab by clicking the deployment name or the Service Manager. However, the Certificate Management page allows you to manage certificates by selecting the deployment or Service Manager on that page itself.

See Manage Certificates for Deployments for more information.

Authorization Profiles

Use this tab to delegate user and group management to external ID providers such as Oracle Identity Cloud Service (IDCS). Integration with an external Identity Management (IDM) system using OpenID/OAuth2.0 protocol provides Oracle GoldenGate users with:

• A single sign-on experience
• Ease of deploying Oracle GoldenGate cloud integration with IDCS.

See Delegate User Authentication and Authorization to an External ID Provider for more information.

Modify Configuration for the Deployment

Learn about how to modify the configuration for the deployment.

Topics:

Access the Deployment Information Page

To modify the Service Manager:

1. Select the Service Manager from the Deployments section of the Service Manager Overview page.
2. Use the Service Manager information page to edit the configuration for the Service Manager using these tabs. The tabs that you can edit for the Service Manager are the same as the tabs for the deployment.

   The following tabs can be used to set up options for the Service Manager:

Details Tab

Use this tab to review the selected deployment configuration. All the deployment directories that you configured with OGGCA are displayed. For Oracle database, you can only edit the Oracle GoldenGate home (OGG_HOME) directory. This allows you to use a different installation than the one you originally configured.

For SQL Server and Db2 z/OS, you need to follow the steps given in the Setting up Environment Variables for Db2 z/OS, Setting up for DB2 z/OS, and Setting up for SQL Server sections in the Using Oracle GoldenGate on Oracle Cloud Marketplace guide.

Note:

It's important to do the settings for SQL Server and DB2 z/OS to make sure that the Administration Service starts when using either of these databases.

Configuration Tab

Use this tab to review and change the selected deployment environment variables. The environment variables that you configured with OGGCA are displayed. You can add new variables, modify existing variables, and delete selected variables. For Oracle database, make sure that TNS_ADMIN is set. See Specify Environment Variables for more information.

Certificates

Use this tab to add and manage certificates for the server, client and CA certificates. There is a difference between the Certificates tab and the Certificate Management page. The Certificates tab is associated with the deployment or Service Manager because you arrive at this tab by clicking the deployment name or the Service Manager. However, the Certificate Management page allows you to manage certificates by selecting the deployment or Service Manager on that page itself.

See Manage Certificates for Deployments for more information.

Authorization Profiles

Use this tab to delegate user and group management to external ID providers such as Oracle Identity Cloud Service (IDCS). Integration with an external Identity Management (IDM) system using OpenID/OAuth2.0 protocol provides Oracle GoldenGate users with:

• A single sign-on experience
• Ease of deploying Oracle GoldenGate cloud integration with IDCS.

See Delegate User Authentication and Authorization to an External ID Provider for more information.

Manage the Status of Deployment and Microservices

Learn about managing the status of the deployment and the Microservices.

Topics:

Change the State of a Deployment

The state of a deployment is visible from the Status column of the Deployments section of the Service Manager Overview page. It is either in Running or Stopped state.

Note:

If the Service Manager is registered as a system daemon, then the Service Manager along with the other servers are automatically started when the host server is (re)started.

To change the state of a deployment:

1. Log in to the Service Manager using the administrator account credentials.
2. In the Deployments section of the Service Manager Overview page, locate the deployment that you need to start or stop.
3. From the Action column, you can select from the available options:
   • Start: If the deployment is in stopped state, this option allows you to start the deployment.
   • Stop: If the deployment is running, this option allows you stop it.
   • Restart: If the deployment is running but there are certain changes that are applied upon restart, then this option allows you to restart the deployment.

   The option displayed depends on the current state of the deployment.

4. Verify that all the microservices associated with the deployment are in the same state as the deployment. By default, all microservices are in Running state after the deployment process is successful.

Change the State of Microservices in a Deployment

You can toggle between the states of the microservices associated with a deployment, to manage errors or apply changes to a deployment configuration in microservices. The microservices can be in the following states:

• Running
• Stopped
• Disabled

To change the state of the microservices associated with a deployment:

1. From the Services section of the Service Manager Overview page, go to the Action column for the specific microservice.
2. Choose from the available options to change the state of the microservice:
   • Start/Stop: If the microservice is running, then the Stop option is available, and if its stopped, then the Start option appears.
   • Disable/Enable: If the microservice is in Stopped state, only then you can use the Disable option to disable the service. When a microservice is disabled, then the Action button changes to the Enable button, which implies that to change the state of the microservice, you would first need to enable it.

Manage the Microservices Configuration Details

Learn about managing the Microservices configuration details.

Topics:

View and Edit the Microservice Configuration

Use the Service Manager Overview page to view and edit the microservices configuration and restart options.

Note:

For all microservices, the configuration and restart options are the same but may have different values.

To access the configuration details of any of the microservices:

1. Click the See Details icon in the Details column of the Service section in the Service Manager Overview page. The Service Information page is displayed.
2. In the Details tab of the Service Information page, click the pencil icon in the Service Configuration section to edit the following configuration options for a microservice:
   • Port: Use this field to change the port number for the corresponding microservice.
   • U-Mask: File mode creation mask
   • Config Force: Use this toggle switch to enable or disable storing of configuration data forcefully.
   • Enabled: Displays if the microservice is enabled or not. You can choose the toggle switch to enable the microservice.
   • Status: Displays the status of the service.

View and Edit the Restart Options for Microservices

The restart options for a microservice allow you to define the behavior of a microservice, when it needs to restart. To modify the restart options from the Service Information page:

1. Click the pencil icon from the Restart Options section of the Service Information page.
2. View or edit the following restart options for the microservice:
   • Enabled: If set to true, then the service will attempt to restart automatically if it encounters an error.
   • On Success: If set to false, then the service is only restarted if it fails.
   • Delay: The time (in minutes) to pause between discovering that a process is terminated abruptly and restarting it.
   • Retries: The maximum number of trials to restart the service, before aborting the retry effort.
   • Window: The time interval in which the retries are counted. The default is 120 minutes.
   • Disable on Failure: If set to true, the service is disabled after it fails all execution attempts in an execution window.

Monitor Oracle GoldenGate Processes, Trails, and Paths

Learn about how to monitor Oracle GoldenGate processes, trails, and paths.

Topics:

Search and Read the Log Information from the Diagnosis Page

Log information allows you to monitor all the messages logged for your Service Manager. This includes processes, trails, paths, microservices, and deployments managed from the Service Manager.

Collective log information for all processes, trails, and paths associated with all deployments and microservices can be accessed from the Diagnosis page in Service Manager. Log information includes details such as the following:

• Lag information for Extract, Replicat processes, which provides the latency value between the last record processed and its timestamp in the data source.
• Heartbeat table activities from the heartbeat history table. Also see Monitor Lag Using Automatic Heartbeat Tables.
• Status messages for Oracle GoldenGate processes, trails, and paths
• Error messages for Oracle GoldenGate processes, trails, and paths
• Status of deployments and microservices
• Error messages of deployments or microservices
• Heartbeat

You can perform the following tasks on this page:

• Sort the Log Information table by column
• Refresh the log using the Refresh button
• Search for specific log messages using the search criteria as date, severity, and message

Notice the Notifications tab at the bottom of the page. It displays messages from the service, which are not updated in the log due to transaction errors. For example, failure to log in to the database using the database credentials.

Access the Diagnosis page from the Application Navigation pane of the Service Manager. The complete log information is displayed on the page.

Topics:

Search for Log Messages

If you want need to search for a specific message, you can also search for it by following these steps:

1. Enter a search criteria in the Search box. The search criteria can be Date, or Severity of the message(s), or the Message string itself. You can add multiple search criteria in the search box.
2. If you select Date, then you get the options:
   • Starting on: Displays the log information from the specified start date.
   • Ending on: Displays the log information till the specified end date.
   • Range between: Displays the log information between the start and end date range.

   
   

   
   Description of the illustration log_info.png

   
   

   The screen shows the Date search criteria with the Starting on date.

3. If you select Severity of the message in the log, then you get to choose from the following levels of severity:
   
   

   
   Description of the illustration log_info_severity.png

   
   

   The screen shows various severity levels of messages. You can select any of these severity levels and search for log messages.

   • Warn
   • Fatal
   • Report
   • Info
   • Debug
   • Success
   • Error
4. Click Clear Filter if you want to delete the search criteria.

Search and Read Log Information for Microservices in a Deployment

You can view and search for log messages associated with one specific microservice in a deployment. This option narrows the log information to display the messages for the selected microservice in the deployment. To access the log information in this manner:

1. From the Services section of the Service Manager Overview page, click the See Details icon in the Details column.
   
   

   
   Description of the illustration see_details.png

   
   
2. Click the Log tab on the Service Information page. Log information specific to the microservice is displayed on this page.
3. Select the search criteria in the Search box to view specific log messages.
   
   

   
   Description of the illustration log_info_microservice.png

   
   
4. Enter values for the search criteria as discussed in Search for Log Messages.

Manage the Debug Log

Learn about managing the Debug Log.

Topics:

Enable Debug Logging

To enable debug logging:

1. Click the Debug Log option from the navigation pane of the Service Manager page.
2. Click the Enable Debug Log toggle switch to start logging debug information.

Use the Debug Log

You can view, download, delete the debug log file to from this page. It is recommended that you delete the debug log after some time. You can maintain a local copy of the debug log to help with debugging issues and then delete the debug log to avoid space issues on the host server.

1. Click the Download Debug Log File option to save a local copy of the debug log.
2. Click the Load Debug Log File option to view the debug log on this page.
3. Click the Delete Debug Log File button to delete a debug log.
4. Search for specific entries in the debug log using the Search By box, if required.
5. Click Refresh to get the latest log information, if it doesn't get refreshed automatically.