.. include:: ../variables.rst Server Management ***************** Command Line ============ The command line utility allows administrators to manage the |APPNAME| from the console application. The clearpath command line utility can only be run as root. .. code:: bash ./clearpath Header ------ .. code:: console clearPath System Manager Version : YY.MM.DD Copyright : Copyright 2026 sigmaIQ Support : support@cphs.cloud .. note:: where YY.MM.DD is the year, month, and day of the |APPNAME| build Command Line Switches --------------------- .. code:: console clearPath System Manager Version : YY.MM.DD Copyright : Copyright 2026 sigmaIQ Support : support@cphs.cloud --cmd configure configures cron jobs - only needs to run on reboot --cmd update checks memory usage, disk space, system plots, removes stuck locks --cmd lastauditcheck sends a notification in the event of 7 days or more with no audits --cmd optimize checks the database to improve performance and clean up --cmd housekeeping Updates system counters and flags and temporary files, trends --cmd password Generates a Password Expires Report --cmd archive Updates the Report Archive --cmd indicators Fixes the auditor mistakes for multiple indicators --cmd ulearn Updates the ULearn resources --cmd xml Updates the XML file for export --cmd backup Initiates a database backup --cmd notify Sends out Notifications --cmd removelocks Deletes all command locks --cmd schema Checks the current database schema to ensure its uptodate --cmd scripts Rebuilds the backup scripts --cmd accounts Notify Admin on accounts that are expiring --cmd certcheck Checks the TLS certificate expiry and alerts support via email --domain site.cphs.cloud Optional - include this parameter to check any tls certificate --cmd telemetry Sends Metric back to clearPath --type hourly sends back server load, disk space, memory usage, events by severity --type daily sends back the number of sync'd audits, overall compliance --type weekly sends back the number of sync'd audits, overall compliance --type monthly sends back more detailed usage and compliance --type onstartup sends back basic data to notify that the server has been restarted --type full sends everthing back. Should not normally be needed. Not included in the cron tasks --action pull gets messages from topics defined in db. Not normally needed for client sites. Not normally a scheduled in cron. If it is scheduled it should @daily --action listener persistent MQTT listener that subscribes to topics defined in db. Runs continuously until the process is stopped. Cron: @reboot clearpath --cmd telemetry --action listener --cmd clean Removes old events and event details, backups and audit logs --interval xxx xxx is the number of days of data to preserve. If not specified the default is 180 days --cmd reminders Send System Reminders --cmd audits Imports sync'd audits into database --cmd mail Gets incoming email followed by sending pending outgoing email --action pop Checks incoming email --action smtp Sends outgoing email --action clear deletes the outgoing email queue and attachments --action test sends a test email to support@cphs.cloud --copyto email@mydomain.com sends a test email to the specified email address --cmd info Returns information from system --copyto email@mydomain.com sends email to the specified email address --attach [ sysinfo includes system information as an attachment logs includes system logs as an attachment schema includes portable mysql schema as an attachment config includes configuration file as an attachment console includes email configuration as an attachment events includes system events from the last day as an attachment ] --cmd distribute Checks to see if any report distribution list need to be sent --action forceall sends all the active distribution lists right away --cmd reports Runs defined reports --scope marked runs reports that are marked for update --scope all forces all reports to update --action smart scans hhctsession/hhctdata and marks affected reports for update --create com|pro|ent|ultimate generates a PDF report set for every account based on edition, then marks them for update --cmd cron Manage cron jobs --action install installs any missing jobs --action clean removes all cron jobs and then adds in the new/updated --action remove removes all cron jobs --cmd httpd Configure httpd with Proxy settings --action install installs new httpd configuration file. Any existing config settings will be lost --action remove removes the proxy settings --domain client.domain.com domain name --cmd maintenance Shows current maintenance mode state --action enable Enables maintenance mode --action disable Disables maintenance mode --cmd import Imports Ministry and iScrub Legacy Data --type [1=iScrub,2=Ministry] Specifies the data format type --file filename.csv name of the filename.csv --account accountid specify the account ID --cmd sms Send SMS Test Message --send 1-xxx-xxx-xxxx Send to Number --msg "Hello World" Text Message (use double quotes) .. note:: The ``--attach sysinfo``, ``--attach logs``, and ``--attach schema`` options under ``--cmd info`` are only available on Linux production builds. .. only:: internal Command Reference (Internal Support) ------------------------------------ The reference below maps each ``--cmd`` to its handler in ``clearpath.system.manager.pas`` (``ParseCommandLine`` dispatch table at lines 2044-2086, individual procedures referenced inline). Use it when diagnosing why a command did or did not do what was expected. Almost every command takes a per-command **lock file** under ``vtTmpDirectory`` (``/var/tmp/`` on Linux); a stuck lock will silently no-op subsequent runs and log ``" already running"``. ``--cmd removelocks`` clears them all. **--cmd configure** *(handler: ConfigureSystem)* Reboot-time bootstrap. Runs the MySQL configuration check (``CheckMySQLServerConfiguration``), cleans the event detail table, adds appliance name to SSH login banner, configures hand hygiene method labels, upgrades report definitions, ensures a default custom audit category exists, disables SELinux, creates ``/mnt/usb``, updates ``/etc/rc.local``, rebuilds the backup shell scripts, and calls ``AddCronJobs``. Lock: ``configureLockFilename``. Linux-only work guarded by ``{$IFDEF LINUX}``. **--cmd update** *(handler: Update)* Hourly job. Calls ``CheckDiskSpace`` (currently a stub - returns 0) and, if ``aoForceCloseTimePeriod`` is set in the audit config, calls ``CloseStaleAuditingSessions`` to terminate audits older than the configured window. Despite the help text it does **not** currently touch memory plots or stuck locks - those are handled by ``housekeeping``. Lock: ``updateLockFilename``. **--cmd lastauditcheck** *(handler: CheckForAccountsThatAreNotAuditing, default 7 days)* Single SQL aggregate over ``corporation`` joined to ``hhctsession`` for each active account. Anything with no audit in the last 7 days emails ``defaultCompanyEmail`` (i.e. support, not the customer). No lock file - guarded only by ``CritSect``. **--cmd optimize** *(handler: RunTableOptimization -> OptimizeTables)* Runs MySQL ``OPTIMIZE TABLE`` over the application schema. Heavy; scheduled Saturday 18:00. No lock file. **--cmd housekeeping** *(handler: housekeeping)* Daily job. Sequence: ``IsDatabaseSchemaValid`` -> ``CheckDiskSpace`` -> ``CleanUpTempDirectory`` -> ``CleanUpUserSessions`` -> ``UpdateHandHygieneAnnualTrendGraph`` -> ``MarkReportsforUpdate`` -> ``CleanUpEventLogs`` (30 days) -> ``DedupMQTTTopics`` -> ``PruneMQTTResults`` (30-day hourly retention). Lock: ``housekeepingLockFilename``. **--cmd password** *(handler: PasswordAudit)* Generates the password-expiry report and queues an email summary. Weekly. Lock: ``passwordLockFilename`` (note: ``POPMail`` reuses this same lock - they cannot run concurrently). **--cmd archive** *(handler: Archive)* Walks the report archive table and rolls over completed reports. Lock: ``archiveLockFilename``. **--cmd indicators** *(handler: FixMultipleIndicators -> HandleMultipleIndicator)* Fixes auditor data-entry errors where the same hand-hygiene moment was logged twice. Runs every 5 minutes. Lock: ``fixIndicatorsLockFilename``. **--cmd ulearn** *(handler: UpdateUlearn -> UpdateResources)* Refreshes ULearn training resources. Daily. Lock: ``ulrearnLockFilename``. **--cmd xml** *(handler: XML -> TXMLThreadObj.Execute)* Regenerates the XML export file used by integrations. Daily. Lock: ``xmlLockFilename``. **--cmd backup** *(handler: Backup)* **Disabled.** The handler logs "Backup Disabled. See Backup Scripts." and returns. Real backups run from ``/usr/local/clearpath/scripts/clearpath*backupscript.sh`` (see Crontab section). If a customer asks why ``--cmd backup`` "did nothing," this is why. **--cmd notify** *(handler: Notify -> TNotifyObj.Execute)* Sends pending system notifications. Lock: ``notifyLockFilename``. **--cmd removelocks** *(handler: RemoveCommandLocks)* Deletes every known per-command lock file plus ``.cp.reportlock`` and ``.cp.reportlist``. First-line recovery for "command silently does nothing" symptoms. **--cmd schema** *(handler: IsDatabaseSchemaValid)* Compares ``SHOW TABLES`` against the in-code ``databasetablelist`` array, logging missing tables and unregistered tables. Returns a boolean used by ``housekeeping``. Lock: ``schemaLockFilename``. **--cmd scripts** *(handler: BuildBackUpScripts -> CreateBackupscript)* Linux-only. Rewrites the four backup shell scripts under ``/usr/local/clearpath/scripts/``. On Windows it logs "Backup Script Builds not supported on Windows" and exits. Lock: ``backupScriptLockFilename``. **--cmd accounts** *(handler: NotifyOnExpringAccounts -> TNotifiyAccountsObj)* Emails admin when accounts approach license expiry. Lock: ``accountLockFilename``. Currently scheduled ``@never`` - active manually only. **--cmd certcheck** *(handler: CertCheck)* With no ``--domain``, queries every ``corporation.domain`` and emails ``corporation.email`` if its TLS certificate is within the warning window. With ``--domain X``, checks only X. Daily. Lock: ``certCheckLockFilename``. **--cmd telemetry** *(handler: Telemetry)* Multi-mode. ``--action pull`` calls ``PullTelemetry`` (one-shot subscribe-and-drain of MQTT topics in the DB - usually only used at the central ``clearPath`` server, not customer sites). ``--action listener`` calls ``RunMQTTListener`` and **blocks forever** as a persistent MQTT subscriber - schedule as ``@reboot``, never as a periodic job. With no ``--action``, sends metrics out via ``TTelemetryObj.send`` keyed by ``--type`` (``hourly``, ``daily``, ``weekly``, ``monthly``, ``onstartup``, ``full``, ``spot``). ``--type spot`` is the cron default every 5 minutes. ``--type full`` is the heaviest payload; not in cron. Lock: ``telemetryLockFilename`` - the listener variant holds the lock for as long as it runs, which will block ``--type spot`` telemetry from cron. If both listener and metric telemetry are needed, run them under separate user accounts or expect spot telemetry to no-op. **--cmd clean** *(handler: CleanUpSystemEventsBackupsAndAuditLogs -> CleanUpDisk)* Deletes files older than ``--interval`` days (default 180) from the audit log directory, audit backup directory, and ``/mnt/usb``, then deletes events older than that cutoff from the ``events`` table. Monthly. Lock: ``cleanUpLockFilename``. **--cmd reminders** *(handler: reminders -> THandHygieneRemindersObj.Execute)* Sends scheduled reminders to auditors / admins. Daily. Lock: ``remindersLockFilename``. **--cmd audits** *(handler: AuditManager -> TAuditManagerObj.Execute)* Imports synced offline audit files into the database. Every 2 minutes. Lock: ``auditmanagerLockFilename``. **--cmd mail** *(handler: RunMailJobs)* Dispatcher: ``--action pop`` -> ``POPMail`` (incoming), ``--action smtp`` -> ``SMTPMail`` (outgoing), ``--action clear`` -> ``ClearAllEmail`` (purges queue + attachments), ``--action test`` -> ``TestSMTPMail`` (test message to ``defaultCompanyEmail``, optional ``--copyto``), ``--action info`` -> ``TestSMTPMail`` with ``--attach``. With **no** ``--action`` it runs both ``POPMail`` and ``SMTPMail`` sequentially - this is the cron form. Lock: ``mailLockFilename`` wraps the whole run; the inner ``POPMail`` and ``SMTPMail`` procedures take their own ``passwordLockFilename`` / ``smtpLockFilename`` locks (the ``passwordLockFilename`` reuse is a historical naming quirk). **--cmd info** *(handler: RunInfoJobs -> TestSMTPMail)* Sends a system-info email to ``--copyto`` with optional ``--attach``. Attach types: ``sysinfo`` (Linux only - dumps ``GetSystemInformation``), ``logs`` (Linux only - attaches ``/var/log/clearpath.log``), ``schema`` (Linux only - dumps the MySQL schema), ``config`` (the configuration file), ``console`` (the captured console output file), ``events`` (last day of system events as ``events.xlsx``). Lock: ``infoLockFilename``. **--cmd distribute** *(handler: RunDistributionList -> TSendDistributionListObj.Execute)* Sends due report distribution lists. ``--action forceall`` ignores the schedule and pushes every active list immediately. Daily at 06:30 (or every 2 minutes per the help comment - schedule per site). Lock: ``distributeLockFilename``. **--cmd reports** *(handler: GetReports)* ``--create com|pro|ent|ultimate`` calls ``CreateReportsForAllAccounts`` to seed a baseline report set per account based on license edition, then flags them. ``--action smart`` calls ``SmartMarkReports`` which runs a 2-statement SQL transaction over ``hhctsession`` and ``hhctdata`` to set ``markedforupdate=1`` on reports whose scope and date range cover newly-changed observation data - intended to run every 5 minutes. With no ``--create``/``--action``, runs ``TApplicationReportObj`` which honors ``--scope marked`` (default: only flagged reports) or ``--scope all`` (every report, regardless of flag). Locks: ``reportsSmartLockFilename`` (smart only), no lock on the main report run - the legacy ``.cp.reportlock`` / ``.cp.reportlist`` files are managed inside ``TApplicationReportObj``. **Conflict:** ``--scope all`` from the support shell will stomp on the ``*/1 * * * *`` ``--scope marked`` cron job; throw maintenance mode on first if running on a busy site. **--cmd cron** *(handler: RunCronJobs, Linux-only)* Authoritative cron installer. ``--action install`` -> ``AddCronJobs`` (default), ``--action clean`` -> ``RemoveCronJobs`` then ``AddCronJobs``, ``--action remove`` -> ``RemoveCronJobs``. The set of jobs installed is defined inline in ``BuildCronJobs`` (``clearpath.system.manager.pas:2895``) and is the source of truth - the Crontab section below this is illustrative only. Lock: ``cronLockFilename``. **--cmd httpd** *(handler: Configurehttpd)* ``--action install --domain client.domain.com`` writes an Apache ``conf.d`` virtual-host config that reverse-proxies 80/443 to ``localhost:8080`` and restarts httpd. ``--action remove`` deletes it. Existing manual edits to that conf file will be overwritten. Lock: ``httpdLockFilename``. **--cmd maintenance** *(handler: MaintenanceMode)* ``--action enable`` / ``--action disable`` toggle maintenance mode; no action shows current state. Lock: ``maintenaceLockFilename`` (note the typo in the constant name). **--cmd import** *(handler: Importfile)* One-shot CSV import. Requires ``--account`` (positive corporation ID), ``--file`` (relative to ``vtImportFileDirectory``), and ``--type`` (``iscrub``/``1`` or ``ministry``/``2``). Logs and no-ops if any of the three is invalid or the file is missing. Lock: ``importLockFilename``. Never run from cron. **--cmd sms** *(handler: SendSMSMsg, ``{$IFDEF SMS}`` builds only)* Diagnostic. ``--send`` is the recipient number, ``--msg`` is the body (quote it). Sends one SMS via the configured provider. Lock: ``smsmsgfilename``. **--cmd test** *(handler: RunTestProcedures, debug builds only)* Internal harness. ``--action targets`` exercises the target compliance functions and writes an Excel sheet. Not present in production builds. Examples ^^^^^^^^ To force all reports to update run the following: .. code-block:: bash /usr/local/clearpath/clearpath --cmd reports --scope all .. warning:: Including the **--scope all**, will force all reports regardless of their update status to refresh. This could take a long time depending on the number of reports on the system. To update reports that are marked for update: .. code-block:: bash /usr/local/clearpath/clearpath --cmd reports .. note:: Using the **--cmd reports** with no scope specified is faster and more efficient as it only updates the report are marked for update. To send out a MQTT telemetry message .. code:: bash /usr/local/clearpath/clearpath --cmd telemetry --type full Crontab ======= This is the standard crontab configuration. There may be slight differences in your cron configuration on your instance of |APPNAME|. To modify the cron run the following from the command line: .. code:: console crontab -e .. note:: root access is required to modify the cron jobs. .. note:: ``--cmd cron --action install`` (which calls ``AddCronJobs`` in ``clearpath.system.manager.pas``) is the authoritative installer for these jobs. The listing below mirrors that procedure as of the current build and is illustrative; if it ever drifts from a freshly-installed crontab, the source code wins. .. code:: console # System Manager - maintenance @reboot /usr/local/clearpath/clearpath --cmd configure -f 2>&1 >> /dev/null @hourly /usr/local/clearpath/clearpath --cmd update -f 2>&1 >> /dev/null 0 18 * * 6 /usr/local/clearpath/clearpath --cmd optimize -f 2>&1 >> /dev/null @weekly /usr/local/clearpath/clearpath --cmd lastauditcheck -f 2>&1 >> /dev/null @daily /usr/local/clearpath/clearpath --cmd housekeeping -f 2>&1 >> /dev/null @weekly /usr/local/clearpath/clearpath --cmd password -f 2>&1 >> /dev/null */5 * * * * /usr/local/clearpath/clearpath --cmd indicators -f 2>&1 >> /dev/null @daily /usr/local/clearpath/clearpath --cmd ulearn -f 2>&1 >> /dev/null @monthly /usr/local/clearpath/clearpath --cmd archive -f 2>&1 >> /dev/null # MQTT Telemetry @hourly /usr/local/clearpath/clearpath --cmd telemetry --type hourly -f 2>&1 >> /dev/null @daily /usr/local/clearpath/clearpath --cmd telemetry --type daily -f 2>&1 >> /dev/null @weekly /usr/local/clearpath/clearpath --cmd telemetry --type weekly -f 2>&1 >> /dev/null @monthly /usr/local/clearpath/clearpath --cmd telemetry --type monthly -f 2>&1 >> /dev/null @reboot /usr/local/clearpath/clearpath --cmd telemetry --type onstartup -f 2>&1 >> /dev/null */5 * * * * /usr/local/clearpath/clearpath --cmd telemetry --type spot -f 2>&1 >> /dev/null # TLS certificate expiry alerts @daily /usr/local/clearpath/clearpath --cmd certcheck -f 2>&1 >> /dev/null # Updates, Reminders and Notifications @daily /usr/local/clearpath/clearpath --cmd xml -f 2>&1 >> /dev/null @hourly /usr/local/clearpath/clearpath --cmd notify -f 2>&1 >> /dev/null @daily /usr/local/clearpath/clearpath --cmd reminders -f 2>&1 >> /dev/null @monthly /usr/local/clearpath/clearpath --cmd clean -f 2>&1 >> /dev/null */2 * * * * /usr/local/clearpath/clearpath --cmd audits -f 2>&1 >> /dev/null */5 * * * * /usr/local/clearpath/clearpath --cmd mail -f 2>&1 >> /dev/null 30 6 * * * /usr/local/clearpath/clearpath --cmd distribute -f 2>&1 >> /dev/null # Reports */1 * * * * /usr/local/clearpath/clearpath --cmd reports --scope marked -f 2>&1 >> /dev/null 0 3 * * * /usr/local/clearpath/clearpath --cmd reports --scope all -f 2>&1 >> /dev/null # Backups @hourly /usr/local/clearpath/scripts/clearpathhourlybackupscript.sh -f 2>&1 >> /dev/null @weekly /usr/local/clearpath/scripts/clearpathweeklybackupscript.sh -f 2>&1 >> /dev/null @daily /usr/local/clearpath/scripts/clearpathdailybackupscript.sh -f 2>&1 >> /dev/null @daily /usr/local/clearpath/scripts/clearpathoffsitebackup.sh -f 2>&1 >> /dev/null @daily /usr/local/clearpath/scripts/clearpathdailyauditsbackupscript.sh -f 2>&1 >> /dev/null # LetsEncrypt Auto Renewals @daily /bin/certbot renew -f 2>&1 >> /dev/null .. only:: internal ``--cmd accounts`` is defined in ``BuildCronJobs`` but commented out (no ``@never`` schedule exists in cron syntax). ``--cmd backup`` is intentionally **not** scheduled; the ``clearpath*backupscript.sh`` shell scripts above replaced it. ``--cmd dashboard`` and ``--cmd rss`` were removed from production builds. Run ``crontab -l`` on a freshly installed instance to confirm the live order.