Oracle Dba Enterprise Manager Oem Tooling

Oracle DBA - Enterprise Manager (OEM) / Tooling

OEM (Cloud Control) target/agent/blackout/template management and repository administration via emcli/emctl (host-boundary tools), read-only repository reporting via SQLcl dba_ai_conn, and the plan-only Tier-3 OEM/Cloud Control upgrade + repository DR runbooks. Targets EM Cloud Control 13.5 (on a 19c repository) and EM 24ai (on a 23ai repository), EE, single-instance and Data Guard, on-prem. Everything self-executing is T1 (observe) or T2 (reversible, dry-run-default). The OEM upgrade, repository DB upgrade, OMS/repository DR, and destructive repository administration are T3 and live only in references/runbooks.md — they print commands for a human and never self-execute.

Routing. emcli/emctl are HOST-boundary tools and are not reachable through the SQLcl MCP server (restrict level 4 = no host commands). They run as generated .sh/.ps1 scripts (candidates to later front a guarded oracle-dba-ops MCP). In-DB reads/maintenance (repository health, SYSMAN stats, scheduler-job pause/resume) run through SQLcl MCP run-sql on dba_ai_conn (sql/*.sql + supported SYSMAN package calls). T3 -> runbook + approval token.

Scope & risk map

Preconditions

• SQLcl MCP connection dba_ai_conn is reachable and wallet-backed. All in-DB repository reads (sql/repository_health.sql, sql/repository_dictionary.sql), the repository_admin status probe, the SYSMAN optimizer-stats gather, and the scheduler-job pause/resume run through it via connect_db / Connect-Db. Never SYS/SYSTEM — except inside a T3 runbook that explicitly states AS SYSDBA, supplied interactively by the operator (e.g. repository restore, RepManager).
• emcli / emctl are HOST-boundary tools with a pre-established, wallet-backed session. Run emcli login (wallet) out of band before the wrappers; on the OMS host for emctl. The scripts NEVER accept a password on argv/env and refuse any plaintext-credential pattern (user/pass@db, password=, identified by) with ERR_SECRET (8). Override binaries only with paths: ODB_EMCLI_BIN, ODB_EMCTL_BIN.
• Secrets resolve from the Oracle Wallet / external password store. No plaintext anywhere — not in argv, env, files, or the runbooks. SYSMAN/SYS passwords for T3 installer/RepManager steps are entered interactively at the prompt.
• Helpers are sourced from _common (scripts/lib.sh / lib.ps1): connect_db, log_event, emit_metric, require_dry_run, guard_blocked_dry_run, require_approval_token, precheck, postcheck, print_banner. Not reinvented.
• Logging: structured key=value lines to the canonical paths /var/log/oracle-dba/oem/oem.log (Linux) / C:/ProgramData/oracle-dba/logs/oem/oem.log (Windows); skill segment oem.
• T2 dry-run default: every T2 script previews and changes nothing unless given --execute. The repository is the SYSMAN schema inside an ordinary Oracle DB; the read-only SQL degrades gracefully (prints a NOTE) when SYSMAN is not visible.

Procedures

Scripts ship as behaviour-equivalent .sh (Linux) / .ps1 (Windows) pairs. T2 scripts default to --dry-run; pass --execute to act. See each script's header / usage.

OEM target & agent management

• Trigger: onboard/offboard a target, move monitoring to another agent, or resync an agent after config drift.
• Precheck: active emcli session (emcli sync); idempotency probe via get_targets.
• Action: scripts/manage_targets.sh {list|add|sync|relocate|remove} … --execute / .ps1 {list|add|sync|relocate|remove}. list is T1 (immediate, read-only).
• Postcheck: target/agent now (or no longer) appears in get_targets.
• Rollback note: add<->remove and relocate-back are the reversals; sync is repeatable. Removing a target only stops monitoring it — it does not touch the DB.

OEM blackout management

• Trigger: suppress monitoring/notifications during planned maintenance; end a blackout early when work finishes.
• Precheck: active emcli session; get_blackouts state probe.
• Action: scripts/manage_blackout.sh {list|create|stop} … --execute / .ps1. --indefinite or --duration HH:MM controls the window; list is T1.
• Postcheck: blackout exists/started after create; not active after stop.
• Rollback note: blackouts are inherently reversible — create <-> stop.

OEM monitoring template management

• Trigger: standardise metrics/thresholds across like targets; export a golden template; apply it to new targets; retire an old one.
• Precheck: active emcli session; list_templates existence probe; create requires the XML file to exist and be non-empty.
• Action: scripts/manage_template.sh {list|export|create|apply|delete} … --execute / .ps1. --copy on apply replaces target settings (override); default merges.
• Postcheck: template present after create; file written after export; still present after apply; absent after delete.
• Rollback note: delete<->create (from the exported XML); revert an apply by applying a baseline/previous template to the same targets.

OEM repository administration

• Trigger: check OMS + repository health; freshen SYSMAN optimizer stats (slow console / loader backlog); pause repository collection jobs for DB maintenance and resume after.
• Precheck: status is read-only (no precheck); gather-stats/pause/resume require SYSMAN visible via dba_ai_conn.
• Action: scripts/repository_admin.sh {status|gather-stats|pause|resume} --execute / .ps1. status is T1 and runs emctl status oms -details + repository_health.sql.
• Postcheck: fresh SYSMAN stats (<1d) after gather; all SYSMAN jobs disabled after pause / none disabled after resume.
• Rollback note: stats restorable via DBMS_STATS.RESTORE_SCHEMA_STATS; pause<->resume. DESTRUCTIVE repository ops are refused and routed to references/runbooks.md#repo-destructive.

Repository read-only reporting (T1)

• Trigger: inventory the managed estate (targets, agents, blackouts, templates) or report repository health/headroom; underpins emcli idempotency probes.
• Action: via dba_ai_conn: @sql/repository_dictionary.sql (inventory) and @sql/repository_health.sql (OMS-repo DB health + SYSMAN internals).
• Postcheck: n/a — emits KEYVAL lines (machine-parseable). Read-only.
• Rollback note: none — read-only; degrades gracefully without SYSMAN visibility.

Tier-3 runbooks

The OEM / Cloud Control upgrade and the destructive repository operations are Tier 3 and live in references/runbooks.md: #oem-upgrade (OMS + repository schema upgrade, e.g. 13.5 -> 24ai), #repo-db-upgrade (repository database upgrade, e.g. 19c -> 23ai, delegated to patching-and-upgrades), #oem-dr (OMS/repository disaster recovery / failed-upgrade restore), and #repo-destructive (DROP SYSMAN, AQ/loader reset, purge-policy redesign, repository re-create/move).

These runbooks PRINT exact emcli/emctl/installer/SQL commands for a human operator and NEVER self-execute. They are gated by require_approval_token / Require-ApprovalToken: an automated agent's only sanctioned action is to print the relevant section and stop with ERR_APPROVAL (6) until a human supplies a real change ticket/token (--token <TICKET> or ODB_APPROVAL_TOKEN; placeholders are rejected). The T2 repository_admin script deliberately refuses the destructive escape hatches (schema drop, AQ reset, purge redesign) and points to the runbook instead. SYSDBA / SYSMAN passwords are a T3-only, interactively-supplied exception. When in doubt, runbook.

See references/version-notes.md for EM 13.5-vs-24ai and 19c-vs-23ai repository deltas. Schedulable T1/T2 jobs are in cron/crontab.d (Linux) and cron/task-scheduler.xml (Windows).