# Oracle Dba Enterprise Manager Oem Tooling

> USE THIS SKILL WHENEVER the user mentions Oracle Enterprise Manager (OEM), Cloud Control, EM 13.5 / EM 24ai, the OMS (Oracle Management Service), the Management Repository / SYSMAN schema, emcli or emctl, a management agent, OEM targets, blackouts, monitoring templates, metric/threshold templates, OEM repository administration, or an OEM / Cloud Control upgrade — EVEN IF they do not name the specific task. Covers OEM target/agent management (add/sync/relocate/remove), blackout management (create/stop), monitoring template management (export/create/apply/delete), repository administration (status, SYSMAN stats gather, pause/resume repository collection jobs), and the plan-only Tier-3 OEM/Cloud Control upgrade + repository DR + destructive-repo runbooks. Follows the oracle-dba-common contracts: SQLcl MCP saved connection dba_ai_conn, Oracle Wallet secrets (never plaintext), --dry-run defaults on T2, and tier gating (max self-execute = T2; the OEM upgrade and destructive repository ops are T3).

- Skill: `shreyas70773/oracle-dba-enterprise-manager-oem-tooling` (Agent Skill, multi-file: 15 files)
- Install (CLI): `npx skillmds@latest add shreyas70773/oracle-dba-enterprise-manager-oem-tooling`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shreyas70773/oracle-dba-enterprise-manager-oem-tooling/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Shreyas70773 (https://skillmd.com/u/shreyas70773)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shreyas70773/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

| Task | Level | Tier | Mechanism (script / sql / runbook path) | Idempotent? |
|------|-------|------|------------------------------------------|-------------|
| OEM target management — list | L2 | T1 | `scripts/manage_targets.sh list` / `.ps1 list` | yes — read-only (emcli `get_targets`) |
| OEM target management — add | L2 | T2 | `scripts/manage_targets.sh add` / `.ps1 add` | yes — noop if target already managed (`get_targets` probe) |
| OEM target management — relocate | L2 | T2 | `scripts/manage_targets.sh relocate` / `.ps1 relocate` | yes — reversible (relocate back); postcheck target still managed |
| OEM target management — remove | L2 | T2 | `scripts/manage_targets.sh remove` / `.ps1 remove` | yes — noop if not managed; reversible (re-add) |
| OEM agent management — sync/resync | L2 | T2 | `scripts/manage_targets.sh sync` / `.ps1 sync` | yes — `resyncAgent` is repeatable/reversible |
| OEM blackout — list | L2 | T1 | `scripts/manage_blackout.sh list` / `.ps1 list` | yes — read-only (`get_blackouts`) |
| OEM blackout — create | L2 | T2 | `scripts/manage_blackout.sh create` / `.ps1 create` | yes — noop if a blackout of that name is already active; reversible (stop) |
| OEM blackout — stop | L2 | T2 | `scripts/manage_blackout.sh stop` / `.ps1 stop` | yes — noop if not active; reversible (re-create) |
| OEM monitoring template — list | L2 | T1 | `scripts/manage_template.sh list` / `.ps1 list` | yes — read-only (`list_templates`) |
| OEM monitoring template — export | L2 | T2 | `scripts/manage_template.sh export` / `.ps1 export` | yes — read-only on repo; writes/overwrites a local XML; postcheck file exists |
| OEM monitoring template — create/import | L2 | T2 | `scripts/manage_template.sh create` / `.ps1 create` | yes — noop if template name exists; reversible (delete) |
| OEM monitoring template — apply | L2 | T2 | `scripts/manage_template.sh apply` / `.ps1 apply` | yes — re-appliable; reversible (apply baseline); precheck template exists |
| OEM monitoring template — delete | L2 | T2 | `scripts/manage_template.sh delete` / `.ps1 delete` | yes — noop if absent; reversible (re-create from exported XML) |
| OEM repository administration — status | L2 | T1 | `scripts/repository_admin.sh status` / `.ps1 status` + `sql/repository_health.sql` | yes — read-only (`emctl status oms` + repo-health probe) |
| OEM repository administration — gather SYSMAN stats | L2 | T2 | `scripts/repository_admin.sh gather-stats` / `.ps1 gather-stats` | yes — re-runnable; reversible (`DBMS_STATS.RESTORE_SCHEMA_STATS`) |
| OEM repository administration — pause collection | L2 | T2 | `scripts/repository_admin.sh pause` / `.ps1 pause` | yes — noop if no enabled SYSMAN jobs; reversible (resume) |
| OEM repository administration — resume collection | L2 | T2 | `scripts/repository_admin.sh resume` / `.ps1 resume` | yes — noop if none disabled |
| OEM repository inventory report | L2 | T1 | `sql/repository_dictionary.sql` (via `dba_ai_conn`) | yes — read-only (SYSMAN MGMT$ views) |
| OEM / Cloud Control upgrade (OMS + repository schema) | L3 | **T3** | `references/runbooks.md#oem-upgrade` | no — rewrites SYSMAN schema; rollback = restore from backup |
| Repository DB upgrade prerequisite (19c->23ai under EM) | L3 | **T3** | `references/runbooks.md#repo-db-upgrade` | no — DB upgrade; delegated to patching-and-upgrades |
| OMS / repository disaster recovery (rebuild / restore) | recovery | **T3** | `references/runbooks.md#oem-dr` | no — restore from backup; failed-upgrade recovery |
| Destructive repository admin (DROP SYSMAN, AQ reset, purge redesign, repo move) | L3 | **T3** | `references/runbooks.md#repo-destructive` | n/a — refused by `repository_admin` |

## 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).