Configure system services
Use the twelve system areas to connect Obelisk, tune collection and reporting, and verify the services required by optional automation.
Locate the relevant area
Open Administration → System and utilities. Its areas cover identity and language; authentication; PBX and databases; paths; refresh intervals; queue health; trends and forecasts; Gemini; background analysis; SMTP and cleanup; installation checks; and licensing. Work in the area matching the actual symptom or requirement.
Change and save one area
Record the relevant existing values before replacing them. Connection settings, recording paths and retention switches have different consequences; changing an interface refresh interval does not repair an SQL or AMI connection.
Configure the dependency
Set the PBX/database connection, storage path or SMTP parameters required by the feature. For AI, review both the configured Gemini model and key, then the background worker settings.
Separate analysis and deletion
Review automatic analysis status independently from cleanup and retention. Enabling scheduled jobs alone does not enable recording deletion; those switches require their own deliberate configuration.
Navigate the twelve System panels
The side navigation contains eleven numbered settings and diagnostic panels plus the License panel. Some controls have their own save or confirmation action: read the local button and feedback before leaving the panel.
| Panel | What it controls |
|---|---|
| 1. Identity and language | Company and PBX-line identity, default report language, CSV separator and memory limit for audio and monthly report work. |
| 2. Security and login | Login attempt and lockout settings, plus normal and Display session duration controls with a dedicated save action. |
| 3. Asterisk and databases | AMI connection and credentials, application database and source CDR database connection fields. Check the correct service when a feature cannot connect. |
| 4. Recordings and log files | Asterisk recordings path, pending work from previous recording folders, allowed audio extensions, worker and application log paths, and public-IP geography configuration. |
| 5. Refresh intervals | Live refresh, cache, historical collection and AI request spacing, plus map tile URL and attribution. These intervals have different purposes. |
| 6. Queue health | SLA and waiting targets and penalties used by queue-health indicators; relate the resulting status to the actual operational situation. |
| 7. Trends and forecasts | Trend sensitivity, history window, forecast sample and horizon, cache, heatmap hours and quality word-cloud size. |
| 8. Google Gemini AI | API key, model and temperature, model tools, sampling policy and report time zone. Review displayed weekly and monthly scheduling information. |
| 9. Audio analysis and protection | Audio scan and batch limits, file size and stability checks, worker timing, transient-failure limits and automatic-analysis status. |
| 10. SMTP email and audio cleanup | Report recipients and sender, SMTP server and encryption, cleanup options and retention tools. Distinguish local deletion from remote AI file cleanup. |
| 11. Installation checks | Run read-only diagnostics, inspect database and runtime requirements and review any targeted corrective commands. |
| License | Read license type, current status and expiry when present; use the license-management link for activation tasks. |
Save session policy and timing deliberately
In Security and login, normal-session inactivity is expressed in minutes, normal-session maximum duration in hours and Display-session maximum duration in days. Use the session policy’s own Save button. Account management selects the session mode; this panel sets its allowed duration.
Understand the audio lifecycle with Gemini
An AI recording analysis sends audio to the configured Gemini service. Obelisk uses two paths according to the request size: audio included directly in the analysis request, or a temporary upload through the Files API. The cleanup behavior depends on that path.
Send the selected audio
Smaller requests include the audio directly. Larger requests upload a temporary file and wait until it is ready before requesting analysis. This upload does not delete the original PBX recording.
Complete the analysis attempt
Gemini processes the request and Obelisk handles its result or error. A Files API upload must remain available while that analysis is being attempted; deletion is not requested immediately after sending the file.
Request removal of the temporary file
For an uploaded file identified as its own, Obelisk attempts a deletion request when the analysis flow ends, including handled error paths. Directly included audio has no Files API object to delete. Local recording retention is managed separately.
Set the recording path and check symbolic links
In System and utilities → Recordings and log files, set the Asterisk recordings folder to an existing path on the Obelisk server. The default is /var/spool/asterisk/monitor, with year/month/day subfolders. The asterisk account needs to traverse the folders and read the audio. A remote SQL connection does not copy recording files to this path.
Use the real archive path
Prefer the real directory or the intended filesystem mount point, preserving year/month/day folders and filenames. Verify a known recording in Recordings, then check automatic-analysis status separately. Do not use chmod 777 or remove path checks to make a file appear.
When moving the same archive
Pause audio jobs and wait for work in progress to finish before moving files. Save the new recording path, then use the previous-folder backlog preview in this panel and explicitly confirm the transfer only for the same archive. This transfers queued work and scan history; it does not move or delete audio. Resume after verification.
| Operation | What happens to symbolic links |
|---|---|
| Browse, play and download | Paths are resolved against the recording root. A link to an existing target inside that resolved root can be read, including when the configured root itself is a link. A link that escapes the root is rejected. Page and action permissions still apply. |
| Automatic audio discovery | The worker resolves the root, but rejects symbolic links in year/month/day directories and skips files that are links. A file that can be played is therefore not necessarily eligible for automatic discovery. |
| Cleanup by error category | The cleaner refuses a configured root that is itself a symbolic link and skips links below the resolved root. Only the selected, verified error categories can be eligible; simply appearing in the catalogue does not authorize deletion. |
| Audio retention | Retention refuses symbolic links in the configured root or any of its parent directories, skips linked subfolders/files and skips files with multiple hard links. It also checks age, completed usable analysis and current file activity. |
Connect recording analysis to periodic reports
Configure Gemini’s key and model, review the sampling controls and choose the report time zone. The panel shows the weekly and monthly schedule and explains how late data is treated. Check report language under Identity and language and recipients, sender and SMTP under Email and cleanup.
Verify the model configuration
Use the available model-list and test tools, choose the intended model and save the selection. A test result alone does not save a different model or confirm a completed audio analysis.
Check the source analysis
Inspect automatic-analysis status and confirm that eligible recordings produce results. For suspended items, read the reason and correct it before requeueing selected recordings.
Verify generation and delivery separately
Review scheduled execution status and the appropriate weekly or monthly log, then check the recipient mailbox. A generated report and a successfully delivered email are two separate outcomes.
Verify configuration and execution
Run the relevant connection check and Installation diagnostics after saving. Review background execution status where applicable, then test the actual feature. A readiness check confirms required configuration, not successful delivery to Gemini or SMTP and not a complete production workflow.
Handle suspended analysis deliberately
An update preserves suspended recordings instead of restarting them silently. Inspect the reason in automatic analysis status and use Requeue only after correcting the cause. Keep report delivery recipients distinct from security alert recipients, and confirm the intended report language before scheduling distribution.
Keep cron and SQL definitions under support control
Cron jobs and SQL events serve different parts of processing. Do not edit the shipped schedules, worker commands, stored procedures or SQL event definitions unless Obelisk support gives you a specific instruction. Editing, running and restoring a procedure have different effects: none is a generic way to refresh a page.
Find third-party components and licenses
The installed application includes a readable list of bundled libraries, fonts, geographic data and their original license files. For the standard path, open /obelisk/assets/vendor/notices/THIRD_PARTY_NOTICES.txt on your Obelisk server; the same file is in /var/www/html/obelisk/assets/vendor/notices/THIRD_PARTY_NOTICES.txt over SSH. Replace the base path if your installation differs. The list separates bundled components from external chart/map services and optional data downloads.
Use the controls, understand what changes
Use the numbered side panel to find the setting, then read its unit and its own save action. Session durations use minutes, hours and days in different fields. Refresh frequency, historical collection and AI request spacing are different controls; changing one does not automatically change the others.
Complete product screenshots
Illustrative data. Open the screenshot to enlarge it and match the controls to the instructions in this chapter.
Open complete screenshot
Read the workspace section by section
Match the numbers and panels below to the complete workspace. These screenshots use illustrative data; the procedures above explain how to work with your own installation.
Application and PBX connections
Review the application database, FreePBX source and Asterisk AMI connection settings. Keep the credentials and endpoints of each integration distinct.
Paths and storage
Locate recordings, logs and application data. Review the configured paths and their status before processing audio or investigating an installation.
Refresh and collection intervals
Tune live refresh, shared AMI cache duration, history collection and spacing between web AI requests according to the installation.
Queue health
Configure the weights and thresholds behind queue-health indicators, so alerts reflect the service conditions you want to monitor.
Trends, forecasts and report display
Set trend sensitivity, waiting forecasts, SLA cache, matrix hours and the Quality & AI keyword cloud.
Gemini and AI settings
Choose the provider settings, models and analysis options for the AI features you activate. These settings also support the reports presented in Quality & AI.
Background processing
Review audio-worker status, recordings awaiting analysis, rejected requests and retry behaviour. Follow the processing queue and investigate items needing attention.
Email, retention and maintenance
Configure report recipients and SMTP delivery, connection timeouts and audio-cleaning choices. Set the application options used by the scheduled server tasks.
Installation diagnostics
Run the installation check and inspect individual results for connections, paths and required components. Open the dedicated guide to understand checks and permission-repair previews.
Installed licence
Check the licence type and, when applicable, its expiry. Open licence management from this panel to follow the activation or renewal process.