Oracle Data Safe Connector Service Installer¶

Comprehensive guide for installing and managing Oracle Data Safe On-Premises Connectors as systemd services using install_datasafe_service.sh.

Overview¶

The installer uses a two-phase model to separate concerns between the DBA (who owns the connector files) and the root/system admin (who controls systemd and sudoers).

Phase	Who	What
1 - Prepare	oracle user (no root)	Generates service unit and README in connector `etc/` directory
2 - Install	root or oracle with sudo	Copies unit to `/etc/systemd/system/`, installs sudoers, enables and starts
- Uninstall	root or oracle with sudo	Stops, disables, and removes service unit; preserves shared sudoers file

Once the sudoers file is installed (after the first --install), the oracle user can run --prepare, --install, and --uninstall without root shell access.

Directory Structure¶

$ORACLE_BASE/product/
├── jdk/                                        # Java Development Kit
└── <connector-name>/                           # Connector directory (one per connector)
    ├── oracle_cman_home/
    │   ├── bin/cmctl
    │   └── network/admin/cman.ora
    ├── etc/
    │   └── systemd/
    │       └── oracle_datasafe_<name>.service  # Generated by --prepare
    ├── log/
    └── SERVICE_README.md                       # Generated by --prepare

System locations (managed by --install):

/etc/systemd/system/oracle_datasafe_<name>.service   # copied from connector etc/
/etc/sudoers.d/oradba-datasafe                        # shared, installed once
/var/log/oracle/                                      # log directory created

Phase 1 - Prepare (oracle user, no root)¶

Run as the oracle user to generate service configuration files.

# List available connectors (shows install state)
install_datasafe_service.sh --list

# Prepare a specific connector
install_datasafe_service.sh --prepare -n exacc-wob-vwg-ha3

# Prepare all discovered connectors
install_datasafe_service.sh --prepare --all

# Preview what will be generated (no changes)
install_datasafe_service.sh --prepare -n exacc-wob-vwg-ha3 --dry-run

# Check current install state
install_datasafe_service.sh --check -n exacc-wob-vwg-ha3
install_datasafe_service.sh --check --all

Generated per connector:

<connector-home>/etc/systemd/oracle_datasafe_<name>.service
<connector-home>/SERVICE_README.md

Note: JAVA_HOME and CMAN directory validation run only during --prepare. --install, --uninstall, and --check skip those checks. OS_USER and OS_GROUP are read directly from the prepared service file - no sudo -E needed.

Phase 2 - Install (root or oracle with sudo)¶

Copy prepared configuration to system locations and start the service.

# Install a single connector
sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3

# Install all prepared connectors
sudo install_datasafe_service.sh --install --all

# Non-interactive (no confirmation prompt)
sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3 --yes

# Dry-run preview
sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3 --dry-run

What --install does:

Validates the prepared service file exists in <connector-home>/etc/systemd/
Copies service unit to /etc/systemd/system/oracle_datasafe_<name>.service
Installs /etc/sudoers.d/oradba-datasafe (shared, once - skipped if already current)
Cleans up legacy per-connector sudoers files (/etc/sudoers.d/<user>-datasafe-<name>)
Creates log directory /var/log/oracle/
Runs systemctl daemon-reload
Enables and starts the service

Sudo Configuration¶

The installer uses a single consolidated sudoers file that covers all Data Safe connector services via wildcards.

File: /etc/sudoers.d/oradba-datasafe

# Managed by install_datasafe_service.sh - do not edit manually
Cmnd_Alias ORADBA_DATASAFE_CTL = \
    /usr/bin/systemctl start   oracle_datasafe_*.service, \
    /usr/bin/systemctl stop    oracle_datasafe_*.service, \
    /usr/bin/systemctl restart oracle_datasafe_*.service, \
    /usr/bin/systemctl reload  oracle_datasafe_*.service, \
    /usr/bin/systemctl enable  oracle_datasafe_*.service, \
    /usr/bin/systemctl disable oracle_datasafe_*.service

Cmnd_Alias ORADBA_DATASAFE_ADMIN = \
    /path/to/odb_datasafe/bin/install_datasafe_service.sh, \
    /path/to/odb_datasafe/bin/uninstall_all_datasafe_services.sh

oracle ALL=(root) NOPASSWD: ORADBA_DATASAFE_CTL
oracle ALL=(root) NOPASSWD: ORADBA_DATASAFE_ADMIN

This file is:

Installed once (shared across all connectors)
Not removed during per-connector --uninstall
Regenerated only when --prepare + --install is re-run with a changed OS_USER

DBA Self-Service¶

Once the sudoers file is in place (after the first install by root), the oracle user can run the full workflow without a root shell:

# Oracle user can now run the full workflow via sudo
install_datasafe_service.sh --prepare -n exacc-wob-vwg-ha3
sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3
sudo install_datasafe_service.sh --uninstall -n exacc-wob-vwg-ha3

Note: The very first install on a new host still requires root to write the initial /etc/sudoers.d/oradba-datasafe file.

To skip sudoers management entirely (if sudoers is handled by your config management tool), use --skip-sudo:

sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3 --skip-sudo

Service Management¶

Start, Stop, Restart¶

# Via oradba_dsctl.sh (recommended - delegates to systemd when service unit exists)
oradba_dsctl.sh start exacc-wob-vwg-ha3
oradba_dsctl.sh stop  exacc-wob-vwg-ha3
oradba_dsctl.sh restart exacc-wob-vwg-ha3

# Direct systemctl (oracle user with sudo, or root)
sudo systemctl start   oracle_datasafe_exacc-wob-vwg-ha3.service
sudo systemctl stop    oracle_datasafe_exacc-wob-vwg-ha3.service
sudo systemctl restart oracle_datasafe_exacc-wob-vwg-ha3.service

Status and Logs¶

# systemd view
systemctl status oracle_datasafe_exacc-wob-vwg-ha3.service

# Port-based live status (authoritative)
oradba_dsctl.sh status exacc-wob-vwg-ha3

# Follow logs in real time
journalctl -u oracle_datasafe_exacc-wob-vwg-ha3.service -f

# Logs since last boot
journalctl -u oracle_datasafe_exacc-wob-vwg-ha3.service -b

# Logs from last hour
journalctl -u oracle_datasafe_exacc-wob-vwg-ha3.service --since "1 hour ago"

Enable/Disable Auto-start¶

sudo systemctl enable  oracle_datasafe_exacc-wob-vwg-ha3.service
sudo systemctl disable oracle_datasafe_exacc-wob-vwg-ha3.service

List All Connector Services¶

# All oracle_datasafe_* units
systemctl list-units "oracle_datasafe_*.service"
systemctl list-unit-files "oracle_datasafe_*.service"

# Via oradba_dsctl.sh
oradba_dsctl.sh services

Uninstall¶

Single Connector¶

sudo install_datasafe_service.sh --uninstall -n exacc-wob-vwg-ha3

Uninstall stops the service, disables it, and removes the unit file from /etc/systemd/system/. The shared /etc/sudoers.d/oradba-datasafe is preserved.

All Connectors¶

uninstall_all_datasafe_services.sh is a thin wrapper around install_datasafe_service.sh:

# List all installed connector services
./uninstall_all_datasafe_services.sh --list

# Preview what would be removed
sudo uninstall_all_datasafe_services.sh --dry-run

# Uninstall all services (prompts for confirmation)
sudo uninstall_all_datasafe_services.sh --uninstall

# Non-interactive
sudo uninstall_all_datasafe_services.sh --uninstall --force

# Non-interactive dry-run
sudo uninstall_all_datasafe_services.sh --uninstall --dry-run --force

Preserved after full uninstall:

/etc/sudoers.d/oradba-datasafe
Connector home directories and all connector files
OraDBA configuration (oradba_homes.conf)

oradba_dsctl.sh Integration¶

When ${ORADBA_BASE}/etc/oradba_homes.conf exists and contains an entry for the connector, --prepare generates a Type=oneshot service that delegates to oradba_dsctl.sh instead of calling cmctl directly.

oradba_homes.conf entry format (field 1 = alias, field 2 = connector home):

dscon3:/appl/oracle/product/exacc-wob-vwg-ha3:datasafe:...

Resulting service unit excerpt:

Type=oneshot
RemainAfterExit=yes
ExecStart=/opt/oradba/bin/oradba_dsctl.sh start exacc-wob-vwg-ha3
ExecStop=/opt/oradba/bin/oradba_dsctl.sh stop exacc-wob-vwg-ha3
ExecReload=/opt/oradba/bin/oradba_dsctl.sh restart exacc-wob-vwg-ha3

Without a matching oradba_homes.conf entry, the script falls back to direct cmctl calls with Type=forking.

Why this matters: cmctl shutdown exits 0 immediately without waiting for the connector process to terminate. oradba_dsctl.sh stop includes a force-kill of remaining cmgw processes, ensuring systemctl stop actually terminates the connector.

oradba_dsctl.sh uses INVOCATION_ID to detect whether it is running inside systemd:

Called externally: delegates start/stop to sudo systemctl start/stop
Called as ExecStart/ExecStop by systemd (INVOCATION_ID set): calls cmctl directly

This prevents infinite delegation loops and ensures systemd always tracks the correct state.

Options Reference¶

Flag	Short	Description
`--prepare`		Phase 1: generate service files as oracle user (default mode)
`--install`		Phase 2: copy files to system, enable and start service (requires root or sudo)
`--uninstall`		Stop, disable, and remove service unit
`--all`		Batch mode - process all discovered connectors; implies `--yes`; mutually exclusive with `-n`
`--connector <name>`	`-n`	Target a specific connector by directory name
`--base <path>`	`-b`	Override `CONNECTOR_BASE`
`--user <user>`	`-u`	OS user for the service (default: `oracle`)
`--group <group>`	`-g`	OS group for the service (default: `dba`)
`--java-home <path>`	`-j`	Override `JAVA_HOME`
`--list`	`-l`	List discovered connectors with install state (no root)
`--check`	`-c`	Check install status for connector(s) (no root)
`--yes`	`-y`	Non-interactive mode (skip confirmation prompts)
`--dry-run`	`-d`	Show what would be done without making changes
`--skip-sudo`		Skip sudoers file management
`--verbose`	`-v`	Verbose output
`--help`	`-h`	Show usage information

Environment Variables¶

Variable	Default	Description
`CONNECTOR_BASE`	`${ORACLE_BASE:-/u01/app/oracle}/product`	Base directory containing connector subdirectories
`ORADBA_BASE`	`${ORADBA_PREFIX:-/opt/oradba}`	OraDBA installation root; locates `oradba_dsctl.sh` and `oradba_homes.conf`
`OS_USER`	`oracle`	OS user that owns the service
`OS_GROUP`	`dba`	OS group for the service
`JAVA_HOME`	`${ORACLE_BASE:-/u01/app/oracle}/product/jdk`	Java installation path

When CONNECTOR_BASE does not exist, the installer automatically probes candidate paths (/appl/oracle/product, /u01/app/oracle/product, etc.) via find_connector_base().

Troubleshooting¶

Service fails to start¶

# 1. Check service status
systemctl status oracle_datasafe_exacc-wob-vwg-ha3.service

# 2. Check recent logs
journalctl -u oracle_datasafe_exacc-wob-vwg-ha3.service --since "10 minutes ago"

# 3. Verify ExecStart binary
grep ExecStart /etc/systemd/system/oracle_datasafe_exacc-wob-vwg-ha3.service

# 4. Check CMAN configuration
cat /appl/oracle/product/exacc-wob-vwg-ha3/oracle_cman_home/network/admin/cman.ora

# 5. Verify Java
${JAVA_HOME}/bin/java -version

systemd shows active (exited) but connector is stopped¶

Cause: Type=oneshot + RemainAfterExit=yes tracks only whether ExecStart returned 0, not the live process state. If the connector was stopped outside systemd, systemd still reports active (exited).

Fix: Always stop via systemd or oradba_dsctl.sh to keep state synchronized:

sudo systemctl stop oracle_datasafe_exacc-wob-vwg-ha3.service
sudo systemctl start oracle_datasafe_exacc-wob-vwg-ha3.service

Use oradba_dsctl.sh status for an authoritative port-based check:

oradba_dsctl.sh status exacc-wob-vwg-ha3

Verify connector is listening¶

# Find configured port
grep -i port /appl/oracle/product/exacc-wob-vwg-ha3/oracle_cman_home/network/admin/cman.ora

# Check if port is listening (replace 1563 with actual port)
ss -tnlp | grep :1563
# older systems:
netstat -tnlp | grep :1563

# Check process
ps aux | grep cmgw

Reinstall a service¶

# Remove and re-prepare from scratch
sudo install_datasafe_service.sh --uninstall -n exacc-wob-vwg-ha3
install_datasafe_service.sh --prepare -n exacc-wob-vwg-ha3
sudo install_datasafe_service.sh --install -n exacc-wob-vwg-ha3

Wrong ORADBA_BASE¶

If oradba_dsctl.sh is not found or oradba_homes.conf is at a non-default location, set ORADBA_BASE before running --prepare:

export ORADBA_BASE=/custom/path/oradba
install_datasafe_service.sh --prepare -n exacc-wob-vwg-ha3

The generated service file embeds the ExecStart path at prepare time. After changing ORADBA_BASE, re-run --prepare followed by --install to update the unit file.