Expert CLI: recovery and utility catalogue
Choose a utility by the fault you have identified. Start with a diagnostic or preview, understand its scope, then use the documented recovery procedure. The presence of a PHP file does not make it a routine maintenance command.
Start with the appropriate diagnostic
These examples start in /var/www/html/obelisk and use the installed PHP CLI. Adapt paths if needed. A successful filesystem check does not certify SQL, AMI, HTTPS, audio or email delivery. Read warnings and compare the result with Administration diagnostics.
Inspect files and PHP CLI
Static read-only checks: does not execute the installation configuration, connect to services or open the database. Exit 0 means no errors but may include warnings; 1 means detected problems; 2 means invalid arguments. It checks this PHP CLI, not Apache/FPM.
Commandsudo -u asterisk /usr/bin/php utility/check_installation.php --jsonCheck the application database
Uses the saved SQL connection and checks required application tables/account schema without schema or data changes. It does not establish that telephone imports are up to date; examine source/import health in Administration separately.
Commandsudo -u asterisk /usr/bin/php utility/check_database.phpCheck the privileged update profile
For an update-profile problem, this root-only check diagnoses the existing SQL administrative profile. It does not migrate, change events or create a data backup. Missing credentials require the supported update flow or support, not editing the profile by hand.
Commandsudo /usr/bin/php utility/schema_profile.php --check
Recover an administrator password or 2FA enrollment
Use the official interactive tool on Linux through an authorized root SSH terminal. It requires an existing usable application database, the asterisk account, POSIX support and a terminal capable of hiding password input. It drops privileges before opening application configuration. A pipe, web request or noninteractive job is not supported.
Open recovery
Choose en, es or it for the prompts. The tool lists administrators when recovering an existing account; alternatively it can create a new administrator with a unique username. This is not an ordinary Team Leader password-reset utility.
Commandsudo /usr/bin/php utility/admin_recovery.php --lang=itChoose exactly what to recover
Select the account, explicitly reactivate it if inactive, and answer whether to reset its 2FA enrollment. Enter and confirm a password that meets the displayed policy, or leave it blank for a generated password. Review the summary before the final confirmation. Password recovery does not require deleting the shared 2FA key or altering other users.
Sign in and complete protection
Store a generated password privately when shown. Sign in with the recovered account; the password change invalidates that account’s previous session generation. Existing 2FA policy is retained: if required enrollment was reset, enroll again before normal access. A newly created administrator has optional 2FA; configure the intended policy. Verify the recovery entry in the access log.
Recover from an IP access-policy lockout
Use this only when the diagnosed cause is the application’s network access policy, for example after an administrator’s public IP changes. It does not reset the account password or 2FA. Resetting the policy restores defaults and clears its current security state; do not use it as a generic login fix.
Read the recovery help
Without --apply the command prints its instructions and does not reset the policy.
Commandsudo -u asterisk /usr/bin/php utility/security_reset.php --helpApply only the required reset
After confirmation of the cause, run once. Sign in, reconfigure the intended restrictions in Access security and verify the security_policy_reset entry in the access log.
Commandsudo -u asterisk /usr/bin/php utility/security_reset.php --apply
Recover an interrupted configuration restore
configuration_backup.php is a recovery entry point, not a CLI backup-creation or arbitrary archive-import command. It uses the authenticated local journal of an interrupted restore. Preserve its maintenance marker and journal. Run it as asterisk, never root. Keep the backup archive and encryption password available through the normal backup procedure.
Resume the authenticated recovery
Read whether the restore completed or was cancelled before database commit, retaining the prior configuration. On success follow the sign-in instruction for a restored administrator. On failure preserve the marker and contact support; do not delete it to force access.
Commandsudo -u asterisk /usr/bin/php utility/configuration_backup.php --recover
Preview a targeted historical report repair
Use this utility for a diagnosed inconsistency in derived report rows, with Obelisk support. It repairs historical episode number/ring-time fields and missing supported answered-transfer/outbound IDs. It does not recreate missing source records, migrate the E.164 policy or restore SQL procedure definitions. The dates refer to report-completion dates, or CDR call dates for outbound.
Preview the agreed date range
Replace the example dates before running. Inspect affected counts and missing sources. Preview is the default; --preview makes the intent explicit.
Commandsudo -u asterisk /usr/bin/php utility/repair_report_data.php --from 2026-09-01 --to 2026-09-30 --previewApply within planned maintenance
After backup, use the official installer pause, verify SQL events and Linux jobs are stopped and wait for active workers to finish. Only then run the agreed repair. --maintenance-confirmed declares that you have done this; the utility does not stop jobs itself. Recheck the affected report/date range, then resume with the official command. Do not apply a guessed wider range.
Commandsudo -u asterisk /usr/bin/php utility/repair_report_data.php --from 2026-09-01 --to 2026-09-30 --apply --maintenance-confirmed
Catalogue: diagnosis, maintenance and recovery
Use only the operation matching the diagnosed need. Commands below are reference syntax from the installed tools; an apply step is not a recommendation to run it routinely. Preview outputs describe the specific changes. After applying, repeat the relevant diagnostic and verify the user-visible function.
| Tool / operation | Purpose, effects and limits |
|---|---|
| check_installation.php / check_database.php / schema_profile.php | Read-only diagnostics described above: static installation, application SQL and existing privileged update profile, respectively. They diagnose different layers and do not repair them. |
| admin_recovery.php / security_reset.php / configuration_backup.php | Separate recoveries for administrator credentials/2FA, access policy and interrupted configuration restore. Follow their procedures above; do not substitute one for another. |
| repair_permissions.php --dry-run | Plans corrections for known installation ownership/modes and configured storage on Linux. Review the plan. Applying requires root and --apply --maintenance-confirmed after planned maintenance; it is not chmod -R and does not repair SQL privileges. |
| web_protection.php --dry-run | Previews managed Apache protection rules. Root --apply merges them, preserving custom rules and saving an identical .htaccess.obelisk-*.bak before changes. Verify HTTPS access and protected resources afterwards; this is not an IIS website configuration tool. |
| geoip_update.php --status / --update | Checks or downloads the local public-IP geography database. --update needs network access and write permission and is not scheduled automatically. Run as asterisk and recheck --status. It does not update telephone-prefix geography. |
| sync_trunks.php --sync | Imports the local FreePBX trunk inventory into the report catalog. It writes the catalog, not PBX telephony configuration. Run as asterisk; verify Lines/Trunks in Database. If local discovery is unavailable, use the reported Administration workflow/support. |
| clean.php --dry-run / recording_retention.php --dry-run | Previews eligible recording deletions by categories or retention age. Actual deletion additionally needs --apply and the appropriate enabled Administration switch. Review paths, criteria and backup first. These previews can use application storage/logs; they are not the static installation checker. |
| repair_report_data.php | Targeted historical data maintenance; preview and explicit maintenance confirmation as documented above. It does not stop jobs or recover missing telephone sources. |
| update.php --status | Inspect coordinated update state. Apply/check/rollback/prune must use the exact command, plan ID and hash generated for the current package in Administration. --check records a dated observation. Prune permanently removes recovery copies and disables that plan’s rollback; SQL rollback restores pre-update Obelisk data. |
| retired_files.php --dry-run | Previews only recognized, unchanged retired code. Root --apply also requires the exact preview --plan-hash. Modified/still-used files, settings, data and backups are preserved. After an interruption produce a fresh preview; do not replace this with a recursive deletion. |
Installer and support-only tools
The following files explain the package inventory; they are not a checklist to execute. Use the installer, coordinated update or an Obelisk-supported repair for these operations. Do not invoke internal application classes, test fixtures or package builders as customer maintenance commands.
| Tool / operation | Purpose, effects and limits |
|---|---|
| provision_database.php --connection-stdin | Installer-only schema provisioning with separate SQL administrative credentials on stdin. Creates application objects. It is not the database health check and must not be used to reinitialize a live installation. |
| initialize_installation.php [--admin-stdin] | Initial application defaults/first administrator, normally orchestrated by the installer. Preserves existing accounts/settings on repeat runs but can initialize missing data. It is not the password-recovery tool. |
| provision_routine_guard.php --interactive | SQL-administrator recovery/provisioning of the MySQL routine privilege guard, described in the administration guide. Asks separately for SQL server, schema and runtime account; no password in arguments. MariaDB does not need this guard. Use only for the diagnosed profile/grant condition, not to restore procedures. |
| queue_number_settings.php | One-time E.164 schema upgrade for older installations, with a preview and local SQL-root socket requirements. Current new installations already include it. Configure number policy through Administration; do not rerun this to change normalization. |
| upgrade_phone_geography.php | Telephone-prefix catalog migration/import. Default preview; --apply needs appropriate SQL rights and a catalog backup. Stock entries/schema can change; customized rows are retained. Geographic classifications may change. This is separate from GeoIP and must follow the supported update/repair plan. |
| upgrade_report_indexes.php | Explicit additive SQL index upgrade with preview by default; requires ALTER for missing indexes. It preserves records and usable indexes, but DDL can wait or take time on large tables. Use only the approved release/diagnostic procedure, not speculative optimization. |
| upgrade_import_sql.php | Historical test reference excluded from the current distributable runtime. It is not a supported administration tool. Do not copy it from old sources or use it to replace the versioned schema/update workflow. |
Understand the FreePBX custom-file integration
Obelisk uses the existing FreePBX installation and its real /etc/asterisk directory. The installer checks the custom configuration before applying changes. It preserves unrelated content and stops on an unknown or conflicting Obelisk definition instead of erasing the file.
Keep a backup of the original custom files before installation or PBX maintenance. If a check stops, read the named file and resolve the reported duplicate, changed block or include directive with the PBX administrator. Do not delete the whole file or add another spy context. An include directive can require manual review even when it is legitimate.
| File in /etc/asterisk | Installer action |
|---|---|
| queues_custom_general.conf | Ensures log_membername_as_agent = yes for queue-event identities, preserving other settings and comments. |
| extensions_custom.conf | Adds or reuses the verified custom-obelisk-spy context for AMI supervision. New blocks are delimited by BEGIN/END OBELISK MANAGED SPY CONTEXT. Do not include this context in from-internal. |
| manager_custom.conf | Adds a marked, dedicated local AMI account only when Create is selected. Existing-account or manual configuration does not create that account. A conflicting account or changed managed block is preserved and reported. |