# Command Line Scripts (CLI) Cacti supports a number of command line scripts. You will find them in the `./cli` directory. The CLI scripts fall into multiple categories, they include: - **Automation** - Utilities to help automate adding objects to Cacti - **Maintenance** - Utilities to help keep Cacti healthy - **Repair** - Utilities to help with repairing Cacti database components - **Repair/Migration** - Utilities to help with repairing or migrating Cacti components - **Install/Upgrade** - Utilities to help with installing and upgrading Cacti In the table below, each of the CLI scripts are categories and explained briefly. ## Automation Scripts | Script | Category | Description | | ---------------------- | ----------- | ----------------------------------------------------------------------------------------------- | | add_device.php | Automation | Allows adding a Device to Cacti. Most device options are included. Some plugin options may not. | | change_device.php | Automation | Allows editing device details such as IP/Poller association | | add_data_query.php | Automation | Allows adding a Data Query to Cacti. | | add_graph_template.php | Automation | Allows adding a Graph Template to Cacti. | | add_graphs.php | Automation | Allows adding a Graph to Cacti. | | add_perms.php | Automation | Allows adding permissions to Cacti. | | add_tree.php | Automation | Allows adding tree's tree branches and objects to Cacti Trees. | | copy_user.php | Maintenance | Allows creating new users from Templates | ## Maintenance Scripts | Script | Category | Description | | ------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | input_whitelist.php | Maintenance | To onboard new Data Input Methods when using Cacti in a high security environment where new Data Input Methods must always be vetted before enabling for general use. | | poller_graphs_reapply_names.php | Maintenance | Allows selecting re-running of Cacti's suggested values engine for Graphs | | poller_reindex_hosts.php | Maintenance | Batch method to re-index Cacti Devices | | analyze_database.php | Maintenance | Analyzes all Cacti tables rebuilding their index cardinality. Important to run after having added large numbers of Devices and Graphs to Cacti. | ## Repair Scripts | Script | Category | Description | | ------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | poller_output_empty.php | Repair | Removes bad entries from Cacti's poller output table. | | rebuild_poller_cache.php | Repair | Batch process to re-populate Cacti's poller cache. NOTE: This script can run for a very long time on large systems. | | repair_database.php | Repair | Utility to look for common problems with old Cacti databases where objects were removed while still in use. Also rapairs all tables after a system crash. | | repair_graphs.php | Repair | Utility to repair Cacti Graphs whose structure is damaged due to legacy Cacti behavior. | | repair_templates.php | Repair | Utility to repair Cacti Templates whose structure was damaged due to legacy Cacti behavior. | ## Repair/Migration Scripts | Script | Category | Description | | ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | audit_database.php | Repair/Migration | Script to audit your Cacti schema, and repair any tables that don't match the stock Cacti schema. It will also upgrade the Cacti schema and run plugin upgrade functions. This is a good migration tool to move database from old versions of Cacti. | | convert_tables.php | Repair/Migration | Convert all tables from their current form to the Cacti preferred table type, collation and charset | | splice_rra.php | Migration | Utility that allows two RRDfiles to be merged, and also assists with resampling an old RRDfile to a new RRA configuration, for example moving a Cacti system from 5 minute polling to 1 minute polling. | ## Install/Upgrade Scripts | Script | Category | Description | | ----------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | import_package.php | Install/Upgrade | Import a Cacti package from a tgz file. | | install_cacti.php | Install/Upgrade | Script to install Cacti from a raw schema. Used primarily by distribution maintainers. | | md5sum.php | Install/Upgrade | Utility to verify the MD5SUM of a file. | | sqltable_to_php.php | Install/Upgrade | Utility for Plugin Developers to create an object for creating tables in plugins. | | structure_rra_paths.php | Install/Upgrade | Utility to convert a system from a flat directory path to a heirarchial one. Important for certain file systems that don't perform well when there are tens or hundreds of thousands of files in a single directory. | | upgrade_database.php | Install/Upgrade | Utility to upgrade a Cacti database from a point in time to the current release. Or even rerun the database upgrade from a point in the past to catch up with changes. This script should be used in conjunction with the `audit_database.php --repair --upgrade` option. | > **NOTE**: Package maintainers may wish to utilize the CLI methods of > install_cacti.php and upgrade_database.php to perform in place installations > and upgrades. In the sub-sections below, we will demonstrate the use of a few of these CLI scripts. > **Caution**: In the following examples, several numbers are shown as output > from various scripts. They will vary between different installations. So don't > bother, if your numbers will vary. ## Rebuild Poller Cache The poller cache holds all commands that cacti will issue during the polling process in an internal format. It is possible, to review the current contents of the poller cache by visiting `System Utilities`, `View Poller Cache`. It is possible to apply filters to this view; it will show up like ```console Localhost - Hard Drive Space Script Server: /var/www/html/cacti/scripts/ss_host_disk.php ss_host_disk 127.0.0.1 1 1:161:500:somesecret:::::: get total 6 RRD: /var/www/html/cacti/rra/localhost_hdd_total_61.rrd Localhost - Load Average Script: /usr/bin/perl /var/www/html/cacti/scripts/loadavg_multi.pl RRD: /var/www/html/cacti/rra/localhost_load_1min_5.rrd Localhost - Logged in Users Script: /usr/bin/perl /var/www/html/cacti/scripts/unix_users.pl RRD: /var/www/html/cacti/rra/localhost_users_6.rrd Localhost - Memory - Free Script: /usr/bin/perl /var/www/html/cacti/scripts/linux_memory.pl MemFree: RRD: /var/www/html/cacti/rra/localhost_mem_buffers_3.rrd Localhost - Memory - Free Swap Script: /usr/bin/perl /var/www/html/cacti/scripts/linux_memory.pl SwapFree: RRD: /var/www/html/cacti/rra/localhost_mem_swap_4.rrd Localhost - mtaReceivedMessages SNMP Version: 1, Community: somesecret, OID: .1.3.6.1.2.1.28.1.1.1.1 RRD: /var/www/html/cacti/rra/localhost_mtareceivedmessages_47.rrd Localhost - mtaReceivedVolume SNMP Version: 1, Community: somesecret, OID: .1.3.6.1.2.1.28.1.1.4.1 RRD: /var/www/html/cacti/rra/localhost_mtareceivedvolume_49.rrd ``` There are several circumstances, that may result in the poller cache being out of sync. An example would be a change of the name of a script used in a `Data Input Method`. This change is _not_ automatically propagated to the poller cache. It is required, to run `php -q rebuild poller_cache.php` manually. Calling the script with the parameter `--help` yields ```console shell>php -q rebuild_poller_cache.php --help Cacti Rebuild Poller Cache Script 1.0, Copyright 2004-2026 - The Cacti Group usage: rebuild_poller_cache.php [-d] [-h] [--help] [-v] [--version] -d - Display verbose output during execution -v --version - Display this help message -h --help - Display this help message ``` Debug mode lists the data sources items that are worked upon. ```console shell>php -q rebuild_poller_cache.php -d WARNING: Do not interrupt this script. Rebuilding the Poller Cache can take quite some time DEBUG: There are '38' data source elements to update. DEBUG: Data Source Item '1' of '38' updated DEBUG: Data Source Item '2' of '38' updated DEBUG: Data Source Item '3' of '38' updated DEBUG: Data Source Item '4' of '38' updated .... ``` Without any parameter, some dots are shown as progress indicators. ```console shell>php -q rebuild_poller_cache.php WARNING: Do not interrupt this script. Rebuilding the Poller Cache can take quite some time ...................................... shell> ``` > **Caution** > > Rebuilding the poller cache interferes with the poller operation. Make sure > that the poller is not running and will not start during a rebuild operation ## Re-Index Hosts Re-Indexing is required only for SNMP/Script Data Queries. Remember, that when applying a Data Query to a Host, a `Re-Index Method` has to be chosen. This reindex method governs the automatic re-indexing based on specific events. ###### Table 20-1. Re-Index Methods | Re-Index Method | Description | | --------------------- | ------------------------------------------------------------------ | | Uptime Goes Backwards | Refers to a system reboot | | Index Count Changed | Refers to a change of the number of indexed items | | Verify All Fields | All index fields of the according XML file are checked for changes | If the method is set to `Uptime Goes Backwards`, Cacti will detect if the target has been rebooted by querying sysUptime (.1.3.6.1.2.1.1.3.0). If the current value for the uptime is lower than the previous one (uptime goes backwards), a reboot is assumed and a re-index is performed If the method is set to `Index Count Change`, e.g. the number of interfaces, without checking sysUptime. It is of particular interest in cases, where indexed entries may change without the need of a reboot. As modern operating systems seldom require reboots for system configuration changes, you may want to consider this setting for many cases (e.g. creating of a new filesystem without a reboot). The index to be considered is defined by the according XML file. If the method is set to `Verify All Fields`, all indexes of the data source are checked for changes. This is of particular interest e.g. in cases, where the index is non-numeric (e.g. a MAC address). It should be noted that in the 1.0 and 1.1 releases, this method was found to be broken and has been corrected since 1.2. If you feel the need for manual re-indexing, you may run it from CLI. Calling the script with the parameter `--help` yields ```console shell>php -q poller_reindex_hosts.php --help Cacti Reindex Host Script 1.2, Copyright 2004-2026 - The Cacti Group usage: poller_reindex_hosts.php --id=[host_id|All] [--qid=[ID|All]] [--host-descr=[description]] [-d] [-h] [--help] [-v] [--version] --id=host_id - The host_id to have data queries reindexed or 'All' to reindex all hosts --qid=query_id - Only index on a specific data query id; defaults to 'All' --host-descr=description - The host description to filter by (SQL filters acknowledged) --debug - Display verbose output during execution -v --version - Display this help message -h --help - Display this help message ``` Running it in debug mode for the host with `id=2` may yield ```console shell>php -q poller_reindex_hosts.php -id=2 -d WARNING: Do not interrupt this script. Reindexing can take quite some time DEBUG: There are '1' data queries to run DEBUG: Data query number '1' host: '2' SNMP Query Id: '1' starting DEBUG: Data query number '1' host: '2' SNMP Query Id: '1' ending ``` A silent run for all devices is issued by ```console shell>php -q poller_reindex_hosts.php -id=All WARNING: Do not interrupt this script. Reindexing can take quite some time .....shell> ``` You may run this script against a specific data query id using `--qid=[data query id]` like ```console shell>php -q poller_reindex_hosts.php --id=All --qid=1 -d WARNING: Do not interrupt this script. Reindexing can take quite some time DEBUG: There are '3' data queries to run DEBUG: Data query number '1' host: '1' SNMP Query Id: '1' starting DEBUG: Data query number '1' host: '1' SNMP Query Id: '1' ending DEBUG: Data query number '2' host: '2' SNMP Query Id: '1' starting DEBUG: Data query number '2' host: '2' SNMP Query Id: '1' ending DEBUG: Data query number '3' host: '15' SNMP Query Id: '1' starting DEBUG: Data query number '3' host: '15' SNMP Query Id: '1' ending ``` It is possible, to select a host based on its host description using `--host-descr=[host description]`. It is allowed to apply an SQL filter expression for the description like `--qid=some%descr`. Use this parameter in conjunction with either `--id=[host id]` or `--qid=[data query id]` or both: ```console shell>php -q poller_reindex_hosts.php --id=All --qid=1 --host-descr=ga%f -d WARNING: Do not interrupt this script. Reindexing can take quite some time DEBUG: There are '1' data queries to run DEBUG: Data query number '1' host: '2' SNMP Query Id: '1' starting DEBUG: Data query number '1' host: '2' SNMP Query Id: '1' ending ``` > **Caution** > > Re-Indexing interferes with the poller operation. Make sure that the poller is > not running and will not start during a reindex operation ## Empty Poller Output Table During normal poller operation, all retrieved results are intermediately stored in the table named poller_output After execution of cmd.php or Spine, this table holds all results. The poller.php finally issues all rrdtool update operations. Thus, after polling has completed, the table should be empty. Conditions may arise, where the table is not (completely) emptied. The most often known issue is lack of php memory. In those cases, the table is bigger than the php memory size, thus not all items are handled correctly. If that issue occurs, you may save all pending updates _after increasing PHP memory appropriately_ by running this very script. Calling the script with the parameter `--help` yields ```console shell>php -q poller_output_empty.php --help Cacti Empty Poller Output Table Script 1.0, Copyright 2004-2026 - The Cacti Group usage: poller_output_empty.php [-h] [--help] [-v] [--version] -v --version - Display this help message -h --help - Display this help message ``` You see, no parameter is required for operating successfully. Under normal circumstances, running this script should yield ```console shell>php -q poller_output_empty.php There were 0, RRD updates made this pass shell> ``` In case, you hit the poller process or if the table was really not fully processed, you may find ```console shell>php -q poller_output_empty.php OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.04 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.00 r:0.05 OK u:0.00 s:0.01 r:0.06 There were 21, RRD updates made this pass shell> ``` If logging level verbosity was switched to `DEBUG` you may find additional debug messages that usually show up in `cacti.log` ## Reapply Suggested Names to Graphs For a general understanding of suggested names used with data queries, please see ?. Be aware, that changes to the `Suggested Names` section of a data query will not automatically be propagated to all existing graphs. This is, where poller_graphs_reapply_names.php drops in. Calling the script with the parameter `--help` yields ```console shell>php -q poller_graphs_reapply_names.php --help Cacti Reapply Graph Names Script 1.0, Copyright 2004-2026 - The Cacti Group usage: poller_graphs_reapply_names.php -id=[host_id|All][host_id1|host_id2|...] [-s=[search_string] [-d] [-h] [--help] [-v] [--version] -id=host_id - The host_id or 'All' or a pipe delimited list of host_id's -s=search_str - A graph template name or graph title to search for -d - Display verbose output during execution -v --version - Display this help message -h --help - Display this help message ``` Assume a situation, where the suggested names where changed for the standard data query named `SNMP - Get Mounted Partitions`. In this case, you will want to rework all graphs for this data query only. A verbose run will yield ```console shell>php -q poller_graphs_reapply_names.php -id=All -d -s="Used space" WARNING: Do not interrupt this script. Interrupting during rename can cause issues DEBUG: There are '6' Graphs to rename DEBUG: Graph Name 'Localhost - Used Space - Memory Buffers' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - Memory Buffers' DEBUG: Graph Name 'Localhost - Used Space - Real Memory' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - Real Memory' DEBUG: Graph Name 'Localhost - Used Space - Swap Space' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - Swap Space' DEBUG: Graph Name 'Localhost - Used Space - /' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - /' DEBUG: Graph Name 'Localhost - Used Space - /sys' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - /sys' DEBUG: Graph Name 'Localhost - Used Space - /boot' starting DEBUG: Graph Rename Done for Graph 'Localhost - Used Space - /boot' ``` Notice the miss-spelling of the word “Space”. The `-s=` option is not case sensitive. ## Copy Local Cacti Users For use and understanding the limitation of this script, it is of importance to read [User Management](User-Management.md) Calling the script with the parameter `--help` yields ```console shell>php -q copy_user.php --help Cacti Copy User Utility, Version 1.2.0, Copyright (C) 2004-2026 The Cacti Group usage: copy_cacti_user.php