Service Manager The host-level control plane that keeps Microservices deployments discoverable, startable, upgradeable, and operationally coherent.
Service Manager is easy to underestimate because it does not capture redo, move trail records, or apply transactions. That is exactly why it deserves a tighter mental model. In modern GoldenGate, Service Manager is the watchdog and lifecycle anchor for deployments on a host: it keeps inventory, provides the top entry point for administration, owns host-side deployment state changes, and becomes the first dependency you feel when provisioning, patching, troubleshooting, or scaling out to multiple deployments.
Understand what Service Manager controls, what remains inside the deployment, and where classic Manager still belongs as a separate concept.
Choose security mode, address model, deployment home, and operating mode correctly before the first deployment locks in bad assumptions.
Use the web UI, Admin Client, local scripts, and OS service controls without confusing host-level state with deployment-level replication state.
Boundary and job description
Service Manager is the primary watchdog service for Oracle GoldenGate Microservices on a host. Its job is to control and administer local deployments and the Microservices attached to them. That sounds generic until you separate it from the rest of the stack. Service Manager is not the place where you define Extract parameters, create Replicat mappings, or inspect table-level replication behavior. Those activities live inside the deployment, primarily through Administration Service and the deployment-specific REST endpoints.
The practical boundary is simple: Service Manager owns host-side deployment lifecycle, service reachability, inventory, entry-point authentication for the Service Manager console, and the top-level path into configuration details, logs, and deployment state. It does not own the data movement logic itself. Distribution Service, Receiver Service, Extract, and Replicat remain the runtime replication components.
Classic Architecture Manager is a different control process with its own responsibilities, including starting classic Extract and Replicat processes and handling classic trail housekeeping. Service Manager is the Microservices host-level watchdog and lifecycle coordinator. Treating them as synonyms leads to bad runbooks, bad upgrade plans, and the wrong troubleshooting entry point.
What Service Manager owns
Local deployment inventory, top-level service state, Service Manager level user access, host-side deployment details, and lifecycle actions such as start, stop, restart, add, remove, and upgrade coordination.
What stays inside the deployment
Process definitions, parameter files, credential store usage for replication, Extract and Replicat behavior, path configuration, lag analysis, and most replication-specific administration.
What it means operationally
If Service Manager is down, you lose the normal host-side control surface. If Service Manager is up but a deployment is stopped, the problem is narrower and usually recoverable without guessing at process internals.
Control plane topology
On a modern GoldenGate host, Service Manager sits above one or more deployments. Each deployment then exposes its own Administration Service, Distribution Service, Receiver Service, and optionally Performance Metrics Service. In other words, the hierarchy is host first, deployment second, replication processes third.
| Component | Primary concern | Good reasons to open it first | What not to expect from it |
|---|---|---|---|
| Service Manager | Host-wide deployment supervision and entry-point control | Host startup issues, deployment state, service reachability, OGG_HOME changes, top-level diagnostics, multi-deployment inventory | Detailed Extract/Replicat design, parameter authoring, mapping logic, or database-specific replication tuning |
| Administration Service | Deployment-side administration of replication objects | Creating processes, editing parameters, managing credentials, starting and stopping process groups, runtime diagnostics inside a deployment | Host-wide inventory of all deployments on a machine |
| Classic Manager | Classic Architecture process control and housekeeping | Classic Extract and Replicat startup, port management, classic trail purging, classic event handling | Microservices deployment inventory, web-based host control plane, or Service Manager style deployment lifecycle |
If you are working with OCI GoldenGate, do not expect Service Manager to be exposed the way it is in a host-managed Microservices installation. That distinction matters when you adapt on-prem runbooks to a managed service footprint.
Creation-time decisions that are expensive to revisit
The best Service Manager runbooks start before the software is provisioned. Several decisions happen only once or become much harder to change later: whether the deployment is secure or non-secure, how clients will reach the host, where the Service Manager deployment home lives, and whether the host will run Service Manager manually, as an OS service, or under XAG.
Four decisions to settle early
- Security model: choose secure or non-secure at deployment creation. Do not assume you can flip the deployment later without rebuilding.
- Address model: pick the host or IP that browsers, Admin Client, peer services, and certificates will all agree on.
- Directory model: keep the Service Manager deployment home outside
OGG_HOME. TreatOGG_HOMEas software and the deployment home as state. - Operating mode: manual mode, daemon or service mode, and XAG mode all change how startup and recovery are supposed to happen.
Why experts care
- Misplacing deployment state under the software home complicates upgrades and rollback.
- Using the wrong listen address forces certificate or proxy rework later.
- Choosing manual mode for a host that must survive reboot unattended creates a support gap.
- Choosing daemon or XAG mode changes which start and stop scripts exist and who is authoritative for restart behavior.
| Service Manager mode | Who starts it | What you gain | Operational tradeoff |
|---|---|---|---|
| Manual | Local scripts in the Service Manager deployment home | Simple labs, explicit control, easy isolated testing | Host reboot does not restore the environment automatically; operators must manage variables and startup order |
| Daemon / service | The operating system | Boot persistence, predictable service management, better fit for stable single-host operations | Manual start/stop scripts are not created for interactive use; recovery should follow OS service discipline |
| XAG integrated | Cluster Ready Services through the XAG stack | Cluster-managed availability and cluster-aware restart ownership | Version coordination becomes stricter during upgrade and the CRS stack is now part of your GoldenGate lifecycle design |
Pre-create checklist
- Confirm whether one Service Manager per host is the right default for this node. In most non-XAG designs, it is.
- Reserve distinct ports for Service Manager and every deployment-side microservice that will live on the host.
- Decide whether the Service Manager administrator and deployment administrator should share credentials or remain separate.
- For secure deployments, line up the certificate model before you run OGGCA, not after the host is already in use.
Provisioning path with OGGCA
Service Manager is created from the GoldenGate Configuration Assistant. On the first run, you create a new Service Manager and the first deployment together. On later runs, you typically attach additional deployments to the existing Service Manager on that host. This division matters because the Service Manager is the stable host anchor, while deployments come and go underneath it.
Launch the configuration assistant from the software home
export OGG_HOME=/srv/ogg/ms26 cd $OGG_HOME/bin ./oggca.sh
Key Service Manager decisions inside OGGCA
| OGGCA field | What it controls | Why it matters |
|---|---|---|
| Create New Service Manager vs Existing | Whether OGGCA creates the host control plane or attaches to an existing one | The first host configuration creates the Service Manager. Later runs should usually reuse it. |
| Software Home | The read-only OGG_HOME path |
This is the binary home that later becomes relevant during patches and home switches. |
| Deployment Home | The directory that stores Service Manager state | Keep it outside OGG_HOME. Mixing state into the software tree weakens upgrade hygiene. |
| Hostname / IP address | The listen endpoint for browsers, Admin Client, and service interactions | If the endpoint does not match your network and certificate model, the deployment becomes awkward immediately. |
| Register as service / daemon | Whether the operating system becomes the startup authority | This changes reboot behavior and whether manual startup scripts exist for the Service Manager. |
| Service Manager administrator account | Top-level Service Manager access | This account can sign in to Service Manager, but it does not automatically gain deployment-wide access unless you choose to reuse it. |
The Service Manager deployment home should never be a subdirectory of OGG_HOME. Keep software and mutable deployment state separate so upgrades remain a controlled pointer change instead of a filesystem disentangling exercise.
Credential scope is stricter than many teams expect
The Service Manager administrator user can sign in to Service Manager. That does not automatically mean the same account can manage Administration Service or the other deployment microservices. OGGCA gives you the option to use the same credentials for the deployment administrator, but that is a design choice, not an automatic inheritance rule. This matters later when Admin Client needs credentials that work with both the Service Manager and the deployment you intend to manage.
Adding a later deployment is not just a repeat of the first run
When you add a deployment to an existing Service Manager, reuse the host control plane and choose the deployment-specific settings carefully. On mixed GoldenGate hub hosts, Oracle documents an important nuance: if you are creating a deployment for a database-specific GoldenGate build that differs from the build used to create the existing Service Manager, you run OGGCA from the database-specific build that matches the deployment you are adding.
Day-2 operations: web entry, Admin Client, startup authority, and logs
Most daily Service Manager work falls into four buckets: connect, confirm status, change host-side service state, and use the diagnostic surfaces without confusing them for deployment-specific problem analysis. The trap is to stay too long in Service Manager when the issue already belongs inside the deployment. The value of Service Manager is fast triage and controlled lifecycle transitions.
1. Connect through the web UI or Admin Client
The web interface starts at the Service Manager endpoint. Admin Client can also connect through Service Manager and select a deployment, which is especially useful when multiple deployments share the same host. For secure deployments, the client side certificate trust path matters.
export PATH=/srv/ogg/ms26/bin:$PATH
export OGG_CLIENT_TLS_CAPATH=/srv/ogg/trust/root-ca.pem
adminclient
CONNECT <protocol>://<sm-host>:<sm-port> DEPLOYMENT ledger_west AS smops_admin
# Use ! only when you intentionally need to override invalid self-signed certificate handling.
CONNECT <protocol>://<sm-host>:<sm-port> DEPLOYMENT ledger_west AS smops_admin !
If the account you use works in Service Manager but fails once you move into deployment administration, check whether the deployment was configured to use the same administrator credentials. Service Manager and deployment users are scoped differently.
2. Start and stop the Service Manager the way the chosen mode expects
Do not improvise startup. Service Manager has an authoritative startup owner based on how it was configured. Manual mode uses local scripts. Daemon or service mode uses the operating system. XAG mode hands state control to the CRS stack. If you ignore that boundary, you create confusing half-recovery states.
export OGG_HOME=/srv/ogg/ms26 export OGG_ETC_HOME=/srv/ogg/sm/etc export OGG_VAR_HOME=/srv/ogg/sm/var /srv/ogg/sm/bin/startSM.sh /srv/ogg/sm/bin/stopSM.sh
# Linux systemctl start OracleGoldenGate systemctl status OracleGoldenGate systemctl stop OracleGoldenGate # Windows net start OracleGoldenGate net stop OracleGoldenGate
If you registered Service Manager as a daemon or service, the interactive start and stop scripts for manual use are not created. Teams often waste time searching for startSM.sh on a host that was intentionally configured not to use it.
3. Use Service Manager for triage before drilling down
From the Service Manager overview, confirm which deployments exist on the host, whether they are running or stopped, and whether individual microservices are reachable. Then use the deployment details, configuration views, and diagnosis surfaces to narrow the boundary further.
| Question | Check from Service Manager | Why it helps |
|---|---|---|
| Is the host control plane alive? | Can you sign in to Service Manager and load the overview page? | If not, the issue is at or below the Service Manager layer, not inside Extract or Replicat logic. |
| Is the deployment stopped or unreachable? | Inspect deployment state and actions from the overview page. | This separates host-side lifecycle problems from deployment-side replication problems. |
| Is the service running under the expected home? | Open the details page and verify the GoldenGate home and environment configuration. | This becomes critical after upgrades, patching, or home switches. |
| Where do I start reading logs? | Use the Diagnosis page or the configuration and log views from Service Manager. | Service Manager can show collective log information for processes, trails, paths, and deployments. |
4. Treat logs as a hierarchy, not a single stream
Service Manager gives you access to both Service Manager level and deployment level log detail. That is useful because not all failures originate in the same place. Service Manager deployment logs include items such as ServiceManager.log, AdminClient.log, and RESTAPI.log. User deployments then produce their own service and process logs such as adminsrvr.log, distsrvr.log, recvsrvr.log, extract.log, and replicat.log.
If sign-in or host control fails, read Service Manager level logs first. If Service Manager is healthy and the deployment exists, move down to the deployment service logs. If the deployment services are healthy, move to process-level logs and runtime diagnostics.
Multi-deployment host patterns
Service Manager becomes more valuable, not less, as the host accumulates deployments. A single Service Manager per host is the modern default because it centralizes host-side lifecycle and reduces redundant maintenance. That matters even more during patching and upgrade windows, because the Service Manager home relationship becomes a coordination point for every deployment attached to it.
One control plane
Keep one Service Manager as the host anchor unless your XAG or cluster design requires a different split.
Many deployments
Source, target, or environment-specific deployments can coexist while remaining separately administered.
Shared discipline
Port allocation, naming discipline, and credential scoping have to be deliberate or the host becomes messy.
Shared maintenance
Patching, upgrade order, and restart policy become easier when the Service Manager pattern is consistent.
Adding a deployment to an existing Service Manager
export OGG_HOME=/srv/ogg/ms26-oracle
cd $OGG_HOME/bin
./oggca.sh
# In OGGCA, select Existing Service Manager and point to the host control plane.
| Failure pattern | What usually caused it | Better operating rule |
|---|---|---|
| New deployment will not attach cleanly to the host | OGGCA was run from the wrong database-specific GoldenGate build for that new deployment | When the deployment requires a different build, run OGGCA from that matching build even though the Service Manager already exists. |
| Unexpected sign-in failures after provisioning | Operators assumed Service Manager credentials automatically grant access to the new deployment | Confirm whether the deployment reused Service Manager credentials or created a separate deployment administrator. |
| Port conflicts during deployment creation | Ports were allocated informally instead of reserved host-wide | Treat the host as a port inventory problem before treating it as a deployment wizard problem. |
| User expectations bleed across deployments | Teams assume Service Manager or deployment users are global across the host | Remember that deployment users are scoped to their own deployment and are not automatically available in other deployments. |
Upgrade and patch lifecycle: Service Manager goes first
Service Manager is not just another service to restart after patching. In Microservices, upgrade order is explicit: Service Manager must be upgraded before the deployments it manages. Oracle also documents that the Service Manager software version must be higher than or equal to the version of the deployments it manages. That allows a newer Service Manager to supervise older deployments during a staged upgrade, but XAG changes the tolerance: with XAG enabled, the managed deployments must also be upgraded and mixed-release operation under the upgraded Service Manager is not supported.
1. Install new home
Lay down the new GoldenGate Microservices software in a separate OGG_HOME.
2. Upgrade Service Manager
Point the Service Manager deployment to the new home and restart it.
3. Stop cleanly
Gracefully stop Extract and Replicat before moving each deployment to the new home.
4. Adjust environment
Update deployment-side variables and home settings that the release requires.
5. Restart and verify
Restart the deployment, then verify services, processes, and the home actually in use.
Service Manager home switch by REST
curl -u svcadmin:'<password>' -X PATCH \
-H 'cache-control: no-cache' \
-d '{"oggHome":"/srv/ogg/ms26ai","status":"restart"}' \
<service-manager-base>/services/v2/deployments/ServiceManager
Verification after the switch
ps -ef | grep -i ServiceManager
If you move deployments first and Service Manager later, you are working against the documented lifecycle. That usually shows up as state confusion, mismatched homes, or unnecessary recovery time during what should have been a controlled upgrade.
Removing a deployment is not the same as removing the Service Manager. The Service Manager removal path is only available once no remaining deployments depend on it.
Verification matrix
A strong Service Manager checklist does not stop at "the page loads." It confirms startup authority, directory intent, credential scope, deployment visibility, and post-change home alignment. The table below is intentionally biased toward what matters after a new install, an added deployment, or an upgrade.
| Moment | What to verify | How to verify it | What it tells you |
|---|---|---|---|
| After first provisioning | Service Manager is reachable and the overview loads | Sign in through the Service Manager endpoint and confirm the overview page appears | The host control plane is up and accepting access |
| After first provisioning | Deployment shows the expected microservices and status | Inspect the deployment row and microservice states from the overview | The first deployment is registered correctly under the host control plane |
| After Admin Client setup | The chosen credentials work end to end | Connect through Service Manager and select the target deployment from Admin Client | You do not have a Service Manager only account when you actually need deployment access |
| After adding a deployment | The new deployment appears under the existing Service Manager | Refresh the Service Manager overview and inspect the deployment list | The host inventory updated correctly and OGGCA attached to the right Service Manager |
| After upgrade or patch | Service Manager is running from the intended home | Inspect the details view and confirm the running binary path with the OS process list | The home switch actually took effect and you are not still running from the old release |
| After upgrade or patch | Deployment-side services restart cleanly | Use the Service Manager overview plus deployment detail pages | The control plane and deployment plane are aligned after the change |
| During triage | Diagnosis page includes the expected scope of log data | Search log information by date, severity, and message from the Diagnosis page | You are reading host-managed log context, not guessing from one process file alone |
Troubleshooting flow for Service Manager problems
Service Manager issues are rarely fixed by jumping straight to Extract and Replicat commands. The faster route is to classify the failure by layer. Start with the host control plane, then move into deployment services, and only then drill into runtime replication components.
| Symptom | Likely cause | What to inspect next | Next action |
|---|---|---|---|
| Cannot open the Service Manager login page | Service Manager is stopped, started from the wrong mode, or failing early during startup | Startup owner for this host, OS service status or manual script usage, SM level logs | Use the correct startup authority first, then inspect Service Manager logs before touching deployment processes |
| Admin Client reaches Service Manager but cannot manage deployment | Credential scope mismatch or wrong deployment selection | Whether the deployment reused SM credentials, and whether DEPLOYMENT was specified explicitly |
Reconnect with credentials that are valid for both the Service Manager and the chosen deployment |
| Expected manual scripts are missing | Service Manager was registered as a daemon or service | The original OGGCA mode choice and OS service state | Use OS service control instead of searching for startSM.sh on a daemon-managed host |
| Deployment exists but does not start after reboot | Manual mode was chosen on a host that needed unattended restart behavior | Service Manager mode, OS service registration, reboot expectations in the runbook | Correct the operating model rather than repeatedly doing manual recovery after each host event |
| Upgrade completed but the host still behaves like the old release | Service Manager or deployment is still pointing at the old OGG_HOME |
Details page home values, environment variables, OS process path | Re-check the home switch, restart in the documented order, and verify with both UI and OS-level inspection |
| New deployment creation fails on a mixed GoldenGate hub | OGGCA was started from the wrong database-specific build | The exact GoldenGate build needed for the target database of the new deployment | Run OGGCA again from the correct build and attach the deployment to the existing Service Manager |
| Secure deployment connections fail from Admin Client | Missing client trust configuration or invalid certificate path | OGG_CLIENT_TLS_CAPATH, certificate validity, and temporary override usage |
Fix trust first. Use certificate override only as a deliberate short-term diagnostic measure |
Service Manager is the host-level control plane for Oracle GoldenGate Microservices. Use it to answer four questions quickly: is the host control surface alive, which deployments exist here, what state are those deployments in, and which home or configuration are they actually running from? Once those questions are answered, move down a layer. That discipline keeps troubleshooting short, upgrades orderly, and multi-deployment hosts readable under pressure.
Test your understanding
Select an answer and click Check.
Q1 — Service Manager is installed at what scope in a GoldenGate Microservices installation?
Q2 — What happens to Service Manager's assigned port after it is provisioned?
Q3 — Which OGGCA wizard option creates a new Service Manager instance?
Q4 — If Service Manager is down, what happens to running deployment services?
No comments:
Post a Comment