# TuneVault Setup Guide

Connect your Oracle database to TuneVault in 5 steps. Covers direct TNS connections and the TuneVault Agent for environments without inbound network access.

Oracle 12.1+ ~15 min setup For DBAs and sysadmins
Step 01

## Create Oracle Reader Account

TuneVault uses a dedicated, read-only Oracle user to run diagnostic queries. This keeps your application credentials separate and limits the scope of database access to monitoring only.

Connect as `SYS` or `SYSTEM` and run each SQL statement below. Execute them one at a time.

SQL — Run as SYS or SYSTEM

    -- Create the dedicated read-only user
    CREATE USER tunevault_reader IDENTIFIED BY 'YourSecurePassword123!';

    -- Allow the user to log in to the database
    GRANT CREATE SESSION TO tunevault_reader;

    -- Grant read access to DBA_ data dictionary views
    GRANT SELECT ANY DICTIONARY TO tunevault_reader;

    -- Grant access to V$ dynamic performance views
    GRANT SELECT_CATALOG_ROLE TO tunevault_reader;

    -- Required for alert log checks (V$DIAG_ALERT_EXT)
    GRANT SELECT ON V_$DIAG_ALERT_EXT TO tunevault_reader;

What each permission does:
CREATE SESSION — allows the user to connect to the database. Without this, nothing else works.
SELECT ANY DICTIONARY — read access to DBA_ views including `DBA_TABLESPACES`, `DBA_SEGMENTS`, `DBA_INDEXES`, `DBA_JOBS`, and hundreds of others needed for health checks.
SELECT_CATALOG_ROLE — read access to V$ dynamic performance views including `V$SQL`, `V$SESSION`, `V$SYSSTAT`, `V$RMAN_BACKUP_JOB_DETAILS`, and AWR-related views.
GRANT SELECT ON V_$DIAG_ALERT_EXT — required for alert log analysis. This view requires an explicit grant even with `SELECT_CATALOG_ROLE`. Without it, alert log checks will show "insufficient privileges" instead of real log data.

Replace `YourSecurePassword123!` with a strong password of your choosing. Keep it — you'll enter it in TuneVault in Step 5.

EBS only

## Additional grants for Oracle E-Business Suite

If this database hosts Oracle E-Business Suite, run these additional grants to enable EBS health checks (Concurrent Manager, Workflow, ADOP patching, service components). Skip entirely for non-EBS Oracle databases.

SQL — Run as APPS or a DBA user with grant option

    -- EBS APPS schema views (EBS environments only — skip ORA-00942 errors, some views vary by version)
    GRANT SELECT ON APPS.FND_CONCURRENT_QUEUES TO tunevault_reader;
    GRANT SELECT ON APPS.FND_CONCURRENT_QUEUES_VL TO tunevault_reader;
    GRANT SELECT ON APPS.FND_CONCURRENT_REQUESTS TO tunevault_reader;
    GRANT SELECT ON APPS.FND_PRODUCT_GROUPS TO tunevault_reader;
    GRANT SELECT ON APPS.AD_TRACKABLE_ENTITIES TO tunevault_reader;
    GRANT SELECT ON APPS.FND_NODES TO tunevault_reader;
    GRANT SELECT ON APPS.AD_ADOP_SESSIONS TO tunevault_reader;
    GRANT SELECT ON APPS.AD_ADOP_SESSION_PATCHES TO tunevault_reader;
    GRANT SELECT ON APPS.FND_PROFILE_OPTIONS TO tunevault_reader;
    GRANT SELECT ON APPS.FND_PROFILE_OPTION_VALUES TO tunevault_reader;
    GRANT SELECT ON APPS.FND_SVC_COMP_PARAM_VALS_V TO tunevault_reader;
    GRANT SELECT ON APPS.FND_CONCURRENT_QUEUE_SIZE TO tunevault_reader;
    GRANT SELECT ON APPS.FND_SVC_COMPONENTS TO tunevault_reader;
    GRANT SELECT ON APPS.WF_ERROR TO tunevault_reader;
    GRANT SELECT ON APPS.WF_NOTIFICATIONS TO tunevault_reader;
    GRANT SELECT ON APPS.FND_OAM_METVAL TO tunevault_reader;
    GRANT SELECT ON APPS.FND_PRODUCT_INSTALLATIONS TO tunevault_reader;

Run as APPS or a DBA user with grant option. Skip any ORA-00942 errors — some views vary by EBS version and configuration. These grants are only needed for EBS-specific checks; standard Oracle health checks work without them.

Step 02

## Choose Your Connection Method

TuneVault supports two ways to reach your Oracle database. Choose based on your network setup.

Option A

#### Direct Connection (TNS)

TuneVault connects directly to your Oracle listener on port 1521. Use this when your database host is reachable from TuneVault's servers — for example, a cloud-hosted database or a server with port 1521 accessible from the internet.

Option B

#### TuneVault Agent

A lightweight agent runs on your database server (or inside your network) and opens an outbound HTTPS connection to TuneVault. No inbound firewall rules needed. Use this for on-premises databases or when port 1521 is not publicly reachable.

Not sure which to use? If you can run `telnet your-oracle-host 1521` from outside your network and get a response, use Option A (Direct). If not — or if your Oracle host is on-premises — use Option B (Proxy).

Step 03

## Direct Connection Setup (TNS)

If you chose Option A, no software installation is needed. Gather your TNS details and enter them directly in the TuneVault dashboard in Step 5.

Field | Description | Example
--- | --- | ---
Host | Hostname or IP address of the Oracle server | db.example.com
Port | Oracle listener port — default is 1521 | 1521
Service Name / SID | Oracle service name (e.g. `ORCL`, `ORCLPDB1`) or SID. Prefer service name for Oracle 12+. | ORCL
Username | The read-only account created in Step 1 | tunevault_reader
Password | Password set in Step 1 | YourSecurePassword123!

Using direct connection? Skip Step 4 entirely — Agent installation is only needed for Option B. Go straight to Step 5.

Step 04

## TuneVault Agent Installation

If you chose Option B, install the TuneVault Agent on your Oracle server or on any server inside your network that can reach Oracle on port 1521. Requires root / sudo access.

### System Requirements

The installer auto-installs all dependencies. If your server has restricted yum repos or internet access, pre-install these packages manually.

Requirement | RHEL / OL 7 | RHEL / OL 8 / 9 | Notes
--- | --- | --- | ---
Python 3.6+ | python3 | python3 | Auto-installed by script
Oracle Client libs | Included in ORACLE_HOME | Auto-detected from running Oracle process
GCC compiler | gcc | gcc | Usually pre-installed on DB servers
libffi headers | libffi-devel | libffi-devel | Required for pynacl / SSH Ed25519 support
Python dev headers | python3-devel | python3-devel | Required for pynacl / SSH Ed25519 support

### 4a. Download the proxy script

Choose the language that fits your environment. All three are functionally identical.

🐍
oracle-proxy.py
Python 3.6+
↓ ⬡
oracle-proxy.js
Node.js 14+
↓ 🖥
oracle-proxy.sh
Shell install script
↓
🔒 Verify download integrity (SHA-256)
Loading checksums…
Verify on Linux / macOS:
sha256sum oracle-proxy.py
Verify on Windows (PowerShell):
Get-FileHash oracle-proxy.py -Algorithm SHA256

### 4b. Edit proxy.env with your credentials

Create a file called `proxy.env` in the same directory as the proxy script. Fill in each value:

proxy.env

    # Required: API key (enter this in TuneVault when adding the connection)
    export TUNEVAULT_API_KEY="your-secret-key-here"

    # Oracle connection details
    export ORACLE_HOST="localhost"
    export ORACLE_PORT="1521"
    export ORACLE_SERVICE="ORCL"
    export ORACLE_USER="tunevault_reader"
    export ORACLE_PASSWORD="your-oracle-password"

    # Optional: listen port (default 3100)
    export PROXY_PORT="3100"

Where to get TUNEVAULT_API_KEY: In the TuneVault dashboard, click Add Connection and switch to the Proxy / HTTPS Proxy tab. Your unique API key will be displayed automatically — copy it into your `proxy.env` file before running the install script.
🔐 Securing proxy.env at rest

`proxy.env` contains your Oracle credentials and API key. Set restrictive file permissions immediately after creating it so only the service user can read it:

Terminal

    # Restrict proxy.env to owner-read only (no group, no world)
    chmod 600 proxy.env
    chown tunevault:tunevault proxy.env  # adjust to the service account that runs the proxy

For environments that require encryption at rest, you can use `openssl` to encrypt `proxy.env` with AES-256-CBC and decrypt it inline at startup:

Encrypt proxy.env

    # Encrypt (run once, then delete the plaintext file)
    openssl enc -aes-256-cbc -pbkdf2 -in proxy.env -out proxy.env.enc
    shred -u proxy.env  # securely delete plaintext

    # Decrypt at startup (use in your systemd ExecStart or wrapper script)
    set -a
    eval "$(openssl enc -d -aes-256-cbc -pbkdf2 -in proxy.env.enc -pass pass:$TUNEVAULT_CONFIG_PASSPHRASE)"
    set +a

Set `TUNEVAULT_CONFIG_PASSPHRASE` as a systemd environment variable or in a secrets manager (HashiCorp Vault, AWS Secrets Manager, etc.). The passphrase itself should never be stored in a file on disk.

### 4c. Run the install script

The install script registers the proxy as a system service and starts it. Run it as root or with sudo:

Terminal — run as root or with sudo

    # Make the install script executable
    chmod +x oracle-proxy-install.sh

    # Run the installer — registers and starts the systemd service
    sudo ./oracle-proxy-install.sh

Root access required. The install script writes to `/etc/systemd/system/` to register the proxy as a service. It must be run by a sysadmin with root or sudo privileges.

### 4d. Verify installation

After the installer finishes, verify each component is working:

Terminal — verify each component

    # Check the proxy is responding
    curl http://localhost:3100/health

    # Verify cx_Oracle can load (Oracle DB driver)
    python3 -c "import cx_Oracle; print('cx_Oracle OK')"

    # Verify pynacl is available (Ed25519 SSH key support)
    python3 -c "import nacl; print('pynacl OK (Ed25519 support)')"

pynacl check failed? Ed25519 SSH keys won't work, but the proxy itself and RSA/ECDSA keys are unaffected. To fix: `pip3 install --upgrade pip setuptools cffi pynacl` — if that fails, install the build dependencies first: `yum install -y libffi-devel python3-devel gcc`

### 4e. Restart after configuration changes

If you update `proxy.env` after the initial install, restart the service for changes to take effect:

Terminal

    sudo systemctl restart tunevault-proxy

Once running, the proxy listens on `http://your-server:3100` and forwards diagnostic queries from TuneVault to your Oracle instance. All traffic is outbound HTTPS from your server to TuneVault — no inbound firewall rules are required.

Step 05

## Connect in TuneVault Dashboard

With your Oracle reader account ready and your connection method set up, add the connection in TuneVault.

1. Sign in at tunevault.app and open your dashboard.
2. Click Add Connection (or the + New Connection button).
3. Click the Direct TCP or Proxy / HTTPS Proxy tab to match your setup from Step 2.
4. Enter the connection details — see the tables below.
5. Click Test Connection — you should see a green confirmation.
6. Save the connection and click Run Health Check.

### For Direct TCP connections (Option A)

Field | What to enter
--- | ---
Host | Oracle server hostname or IP (e.g. `db.example.com`)
Port | Listener port — almost always `1521`
Service / SID | Oracle service name or SID (e.g. `ORCL`, `ORCLPDB1`)
Username | `tunevault_reader` (the account from Step 1)
Password | The password you set in Step 1

### For Proxy Agent connections (Option B)

Field | What to enter
--- | ---
Proxy URL | Address where the proxy is listening — e.g. `http://your-server:3100`
API Key | The `TUNEVAULT_API_KEY` value from your `proxy.env` file in Step 4

Connection test failing?
Direct TCP: Verify port 1521 is reachable from outside your network with `telnet your-oracle-host 1521`. Also confirm the `tunevault_reader` account was created and has the grants from Step 1.
Proxy Agent: Check that the proxy service is running with `sudo systemctl status tunevault-proxy`. Verify `ORACLE_HOST` and `ORACLE_PORT` in `proxy.env` point to the correct Oracle server on your network.

All set — run your first health check and see what TuneVault finds.

Run Health Check →
See exactly what's wrong with your Oracle database.
Full diagnostic in minutes. 5 free health checks per company.
Run Your Free Health Check →