Install Oracle OSWatcher as a Linux Service in RHEL / CentOS / OEL 7.x and 8.x Updated for Oracle Linux 9 & 10 Viability

 

Update Notice — OSWatcher Viability Across Oracle Linux Releases

Since the original version of the post (2019) (https://debapriyabiswas.blogspot.com/2019/04/install-oracle-oswatcher-as-linux.html) , Oracle’s stance on OS-level performance monitoring has shifted significantly. Before following the installation steps below, review this viability matrix to determine whether OSWatcher is the right tool for your Oracle Linux version.

OEL Version	OSWatcher Viable?	Recommended Tool	Notes
OEL 7	Yes	OSWatcher (OSWbb)	Fully documented. SysV init via chkconfig works. Systemd unit file also supported. Oracle recommends migrating to OEL 8 or 9.
OEL 8	Yes (with caveats)	OSWatcher or PCP	OSWbb documented in official OEL 8 guide. RPM in ol8_addons. Requires net-tools. Use systemd, not SysV init. PCP also available.
OEL 9	Not recommended	Performance Co-Pilot (PCP)	OEL 9 docs replace OSWatcher chapter with PCP. No OSWatcher RPM in ol9_addons. pcp-oracle-conf package provides Oracle-tuned PCP instead.
OEL 10	No	Performance Co-Pilot (PCP)	PCP is the only OS monitoring tool documented for OEL 10. OSWatcher is not referenced. PCP ships pre-installed and enabled by default on OCI images.

Bottom line: If you are on OEL 7 or 8, OSWatcher remains a valid choice and the steps below apply. If you are on OEL 9 or 10, skip OSWatcher and use Performance Co-Pilot (PCP) — see the PCP section at the end of this document.

Prerequisites (OEL 7 and 8)

Install net-tools (OEL 8 Only)

OSWatcher’s discovery phase checks for ifconfig and netstat, which are part of the net-tools package. On OEL 8 (and RHEL/CentOS 8), net-tools is not installed by default — it has been deprecated in favour of iproute2 (ip, ss).

Install it before deploying OSWatcher:

sudo dnf install net-tools -y

Verify:

which ifconfig && which netstat

Note: On OEL 7, net-tools is typically installed by default but may be absent on minimal installations. Install with: yum install net-tools -y

 

Download and Extract OSWatcher

Download OSWBB from Oracle Support (MOS Doc ID 301137.1).

For example, download and keep the file at /Downloads/oswbb812.tar.

Copy the OSWatcher binary to the host and extract:

cp /Downloads/oswbb812.tar /opt/

cd /opt

tar -xvf oswbb812.tar

Create a log directory for OSWatcher:

mkdir -p /var/log/oswbb

 

Option A — Systemd Service (Recommended for OEL 7 and 8)

Since OEL 7, systemd is the default init system. While the legacy SysV init approach (Option B) still works on OEL 7 via compatibility, a native systemd unit file is the correct approach for both OEL 7 and 8.

Create the systemd unit file

/etc/systemd/system/oswatcher.service:

[Unit]

Description=Oracle OSWatcher Black Box (OSWbb)

After=network.target

[Service]

Type=forking

WorkingDirectory=/opt/oswbb

ExecStart=/opt/oswbb/OSWatcher.sh 30 168 gzip /var/log/oswbb

ExecStop=/opt/oswbb/stopOSWbb.sh

PIDFile=/opt/oswbb/OSWatcherFM.pid

Restart=on-failure

RestartSec=30

[Install]

WantedBy=multi-user.target

Parameters

Parameter	Description
30	Snapshot interval in seconds
168	Hours of archive data to retain (168 hours = 7 days)
gzip	Compress archived log files
/var/log/oswbb	Archive directory

Enable and start the service

sudo systemctl daemon-reload

sudo systemctl enable oswatcher.service

sudo systemctl start oswatcher.service

Check service status

sudo systemctl status oswatcher.service

Stop the service

sudo systemctl stop oswatcher.service

View logs

journalctl -u oswatcher.service

 

Option B — SysV Init Script (Legacy, OEL 7 Only)

Note: This is the original method from the 2019 version of this post. It uses chkconfig and service, which are SysV init commands. On OEL 7, these work via systemd’s compatibility layer. On OEL 8, chkconfig is not installed by default — use Option A (systemd) instead.

Create the service script as /etc/init.d/oswatcher:

#!/bin/bash

#

# chkconfig: 2345 15 90

# description: Starts and stops the OSWatcher

#

OSWBB_SRC_DIR=/opt/oswbb

echo $OSWBB_SRC_DIR

echo "******************************************************" >> $OSWBB_SRC_DIR/init_oswbb.log

case $1 in

'start')

        echo "...Starting OSWBB from init at `date` " >> $OSWBB_SRC_DIR/init_oswbb.log

        cd $OSWBB_SRC_DIR; nohup ./OSWatcher.sh 30 168 gzip /var/log/oswbb &

        touch /var/lock/subsys/oswatcher

;;

'stop')

        echo "...Stopping OSWBB from init at `date` " >> $OSWBB_SRC_DIR/init_oswbb.log

        cd $OSWBB_SRC_DIR; ./stopOSWbb.sh

        rm -f /var/lock/subsys/oswatcher

;;

'status')

        ps -aef |grep OSWatcher |grep -v grep

;;

*)

        echo "Usage: $0 start|stop" >&2

        exit 1

;;

esac

exit 0

Make it executable and register:

chmod +x /etc/init.d/oswatcher

chkconfig --add oswatcher

chkconfig --list oswatcher

Start / Stop / Status:

service oswatcher start

service oswatcher status

service oswatcher stop

 

Alternative — RPM-Based Install (OEL 6, 7, 8 Only)

Oracle provides an OSWatcher RPM in the Addons repository for OEL 6, 7, and 8. This RPM is a separate package from the OSWbb tarball (MOS Doc ID 301137.1) and includes its own systemd/init configuration.

Install via dnf / yum

# OEL 8

sudo dnf install --enablerepo=ol8_addons oswatcher -y

 # OEL 7

sudo yum install --enablerepo=ol7_addons oswatcher -y

Configure

The RPM stores its configuration at /etc/sysconfig/oswatcher:

# The directory where oswatcher logs should be kept

DATADIR=/var/log/oswatcher

 # The interval (in seconds) between collection runs

INTERVAL=10

 # The maximum age (in hours) of the various log files

MAXAGE=1

 # An optional program used to compress the log files

ZIP=

Manage the service

sudo systemctl enable oswatcher

sudo systemctl start oswatcher

sudo systemctl status oswatcher

Note: This RPM package is not available for OEL 9 or 10. There is no oswatcher RPM in the ol9_addons or ol10_addons repositories.

 

Verify Data Collection

Data is stored in the archive directory (/var/log/oswbb for tarball install, /var/log/oswatcher for RPM install).

# Check archive size

du -h /var/log/oswbb

ls -alrth /var/log/oswbb

# Verify OSWatcher processes are running

ps -aef | grep OSWatcher | grep -v grep

 

Run the GUI Analyzer (OSWbba)

Note: Prerequisite: Java 1.4.2 or higher must be installed.

cd /opt/oswbb

java -jar oswbba.jar -i /var/log/oswbb

Navigate to the analysis/<hostname>/dashboard folder and open index.html to view the graphical dashboard.

For OEL 9 and 10 — Use Performance Co-Pilot (PCP) Instead

Starting with OEL 9, Oracle officially recommends Performance Co-Pilot (PCP) as the replacement for OSWatcher. PCP collects the same categories of OS and network metrics (CPU, memory, disk I/O, network) but stores data in a binary, machine-readable format with richer querying and graphing capabilities.

Install PCP (OEL 9 / 10)

sudo dnf install pcp pcp-system-tools -y

For Oracle-tuned PCP configuration (available in ol9_addons):

sudo dnf install --enablerepo=ol9_addons pcp-oracle-conf -y

Enable and start PCP services

sudo systemctl enable --now pmcd pmlogger

Verify

pcp

Expected output (example from an OEL 9 host):

Performance Co-Pilot configuration on myhost:

  platform: Linux myhost 5.15.0-305.176.4.el9uek.x86_64 ...

  hardware: 4 cpus, 1 disk, 1 node, 31636MB RAM

  timezone: Asia/Kolkata

  services: pmcd

  pmcd: Version 6.2.2-7, 12 agents, 6 clients

  pmlogger: primary logger: /var/log/pcp/pmlogger/myhost/...

  pmie: primary engine: /var/log/pcp/pmie/myhost/pmie.log

Configuration

Logging Interval

The default logging interval depends on the install method: pcp-zeroconf uses 10 seconds, while a base pcp install uses 60 seconds. To change it, edit the control file:

sudo vi /etc/pcp/pmlogger/control.d/local

Add -t <interval> to the arguments. For example, to log every 30 seconds:

LOCALHOSTNAME   y   n   PCP_ARCHIVE_DIR/LOCALHOSTNAME   -r -T24h10m -t 30s -c config.default

Then restart pmlogger:

sudo systemctl restart pmlogger

Metric Selection

Use pmlogconf to interactively configure which metric groups are logged:

sudo pmlogconf /var/lib/pcp/config/pmlogger/config.default

This walks through each metric group (CPU, disk, memory, network, filesystem, process, etc.) and lets you enable/disable and set per-group intervals.

Archive Retention

By default, PCP retains archives for 14 days. To change retention to 30 days:

sudo vi /etc/sysconfig/pmlogger_timers

# Add or modify:

PMLOGGER_DAILY_PARAMS="-E -k 30"

The -k 30 flag tells pmlogger_daily to keep archives for 30 days. Compressed archives use approximately 10:1 compression, so storage requirements are modest — roughly 10–15 MB/day uncompressed per typical server.

Important: Ensure sufficient space on /var (or the mount containing /var/log/pcp). Red Hat recommends at least 5 GB for small servers, 10 GB for larger systems, on an ongoing basis.

 

Using PCP — Common Commands

Task	Command
System overview	pcp
Live vmstat equivalent	pmrep :vmstat  or  pcp vmstat
Live iostat equivalent	pmrep :iostat  or  pcp iostat
Live mpstat (per-CPU)	pmrep :mpstat
Live top equivalent	pcp htop  or  pcp atop
Live dstat equivalent	pcp dstat
Network interface stats	pmrep network.interface
Free memory / swap	pmrep mem.util.free mem.util.swapFree
List all available metrics	pminfo | less
Describe a specific metric	pminfo -dt kernel.all.load
Query a metric value live	pmval -s 5 -t 2 kernel.all.load
Replay archived vmstat	pmrep -a /var/log/pcp/pmlogger/$(hostname)/<archive> :vmstat
Compare two time periods	pmdiff <archive1> <archive2>
Graph archived data (GUI)	pmchart -a <archive>
Check PCP service status	systemctl status pmcd pmlogger pmie

OSWatcher to PCP Equivalence

OSWatcher Utility	PCP Equivalent
vmstat	pmrep :vmstat  or  pcp vmstat
iostat	pmrep :iostat  or  pcp iostat
mpstat	pmrep :mpstat
netstat	pmrep network.interface
top	pcp htop  or  pmrep :proc-cpu
ifconfig	pmrep -i <iface> network.interface
OSWbba (analyzer)	pmchart (graphical), pmdiff (comparison), pmval (ad-hoc queries)

Retrospective analysis

PCP archives are stored at /var/log/pcp/pmlogger/<hostname>/. To replay:

pmrep -a /var/log/pcp/pmlogger/$(hostname)/$(date +%Y%m%d).0 :vmstat

For full details, refer to the official Oracle documentation:

Oracle Linux 9: Collecting and Analyzing Metrics With Performance Co-Pilot

Oracle Linux 10: Collecting and Analyzing Metrics With Performance Co-Pilot

 

References

•       OSWatcher Black Box — MOS Doc ID 301137.1

•       OSWbba Analyzer User Guide — MOS Doc ID 461053.1

•       Install and Configure OSWatcher as RPM — MOS Doc ID 2560609.1

•       Oracle Linux 8: Working With OSWatcher Black Box — docs.oracle.com

•       Oracle Linux 9: Working With Performance Co-Pilot — docs.oracle.com

•       Oracle Blog: Better Diagnostics with Performance Co-Pilot — blogs.oracle.com

About the Author

Debapriya Biswas
Oracle ACE Apprentice | Sr. Consultant – Cloud Technologies
Focused on OCI Compute, Networking, and Automation