TuneVault Setup Guide

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.

-- 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;

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

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.

-- 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;

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

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.

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.

4a. Download the proxy script

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

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:

# 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"

# 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

# 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

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:

# 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

4d. Verify installation

After the installer finishes, verify each component is working:

# 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)')"

4e. Restart after configuration changes

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

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.

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)

For Proxy Agent connections (Option B)