Cactidocumentation/General-Installing-Instructions.md

General Installing Instructions

Note

: As of Cacti 1.2.31, PHP 8.1 is required and PHP Composer is required. Composer installs the vendor libraries and keeps them up to date.

Make sure the following packages are installed according to your operating system's requirements. Verify that Apache and MySQL/MariaDB start at system startup.

A special note on installing Cacti in LXC containers such as those found on Proxmox

We recommend creating a privileged container. You may need to update your container's config file with

lxc.apparmor.profile: unconfined

This will allow ICMP ping and other functions to work.

A tested configuration file like the one below should work. Tune it to your own needs and standards.

arch: amd64
cores: 2
hostname: cacti
memory: 2048
net0: name=eth0,bridge=vmbr0,firewall=1,hwaddr=mac-id,ip=dhcp,type=veth
ostype: ubuntu
rootfs: local-lvm:vm-110-disk-0,size=8G
swap: 2048
lxc.apparmor.profile: unconfined

Required Packages for Most Operating Systems

Depending on your operating system and PHP version, certain packages are required for Cacti. The largest variable in these requirements comes with regard to PHP and MySQL/MariaDB.

Installation requirements include the packages below. The installation of these packages will vary by operating system.

Base OS

• Apache, IIS, or nginx

• net-snmp, net-snmp-utils

• rrdtool

• help2man (for spine)

• dos2unix (for spine)

• development packages (gcc, automake, autoconf, libtool, either mysql-devel or mariadb-devel, net-snmp-devel, help2man)

  (for spine)

Database

MySQL versions 8.0/8.4+ and MariaDB versions 10.5 through 11.x+ are supported.

• mysql

• mysql-server

• libmysqlclient

or

• mariadb

• mariadb-server

• libmariadbclient

PHP Modules

The installation of these modules varies by OS. Use the php -m command to verify that they are installed.

• posix

• session

• sockets

• PDO

• pdo_mysql

• xml

• ldap

• mbstring

• pcre

• json

• openssl

• gd

• zlib

PHP Optional Modules

The following modules are optional, but preferred to be installed.

• snmp

• gmp (for plugin support)

• com or dotnet (Windows only)

A special note for systems using PHP-FPM

Before starting the Cacti setup process, restart the PHP-FPM daemon to rebuild its cache, or you may receive an HTTP 500 error.

systemctl restart php-fpm

FreeBSD

There are two ways to install on FreeBSD. In both cases Cacti pulls in its dependent packages, so you do not need to install anything else. Each way has trade-offs:

• Compiled packages: fast, but with fixed dependency versions (for example an older MySQL server or PHP version).

  pkg install cacti
  pkg install spine
  

• FreeBSD ports: compilation can take a long time, but dependency versions are not fixed (see Using the Ports Collection)

  pkg install git
  git clone https://git.FreeBSD.org/ports.git /usr/ports
  git -C /usr/ports pull
  # Choose either MariaDB or MySQL:
  cd /usr/ports/databases/mariadb106-server
  make install clean
  cd /usr/ports/net-mgmt/cacti
  make install
  cd /usr/ports/net-mgmt/spine
  make install
  

Apache and other software can be installed using packages or Ports as well.

Everything in FreeBSD is installed under /usr/local/. This documentation shows paths such as /etc/php.ini and /usr/bin/spine.

Use the FreeBSD equivalents instead: /usr/local/etc, /usr/local/bin/spine.

For Spine, set the suid bit (without it, ICMP ping cannot function):

chmod +s /usr/local/bin/spine

Configure PHP

Verify that the modules are installed and configured correctly. There are several ways to do so - consult PHP configuration instructions for a complete description.

It is imperative that you set the date.timezone in your /etc/php.ini, or /etc/phpX/apache/php.ini and /etc/phpX/cli/php.ini files. Failure to do so will result in errors after the install is complete.

Most other PHP configuration is done automatically by the base OS, so there is no need to discuss that here.

Configure the Webserver (Apache)

Most Linux and UNIX systems automatically configure the web server to allow PHP content, so no additional configuration should be needed. The section below is included for reference in case you are running a UNIX version that does not configure the web server correctly. It is written specifically for RHEL and its variants, so the instructions may vary.

Find the file /etc/httpd/conf/httpd.conf or its equivalent and make the following changes to it:

# Load config files from the config directory "/etc/httpd/conf.d".
Include conf.d/*.conf

Now, locate the PHP configuration file at /etc/httpd/conf.d/php.conf

# PHP is an HTML-embedded scripting language which attempts to make it
# easy for developers to write dynamically generated webpages.
LoadModule php_module modules/libphp.so
#
# Cause the PHP interpreter to handle files with a .php extension.
AddHandler php-script .php
AddType text/html .php
#
# Add index.php to the list of files that will be served as directory
# indexes.
DirectoryIndex index.php

Configure MySQL/MariaDB

Set a password for the root user, and record this password. If you lose control of this password, you may have to re-install your database server in the case of any system disaster or recovering from a crash.

mysql_secure_installation

You must also load timezone information into the database. This is required for various plugin use. Later, you will be required to grant access to the time_zone_name table during the final installation steps.

shell> mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql

Since Cacti 1.x is supporting internationalization (i18n), it is important that the default character set for MySQL/MariaDB be i18n compatible. The Cacti installer will make specific recommendations on MySQL/MariaDB settings. Follow those as applicable for your OS.

Galera clustering: several tables use the MEMORY storage engine. Those tables are not replicated among nodes, which can cause problems. If you configure Cacti to connect to only one node of your cluster and are not load balancing, this does not apply to you.

If you are running multiple nodes in a load-balanced environment where you connect to a VIP, remove all but one node from rotation during Cacti installation or update. After the installation or update, log in to your MySQL server and run the following commands to convert those tables to the InnoDB engine:

MariaDB [(none)]> use cacti;
MariaDB [cacti]> ALTER TABLE `automation_ips` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `automation_processes` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `data_source_stats_hourly_cache` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `data_source_stats_hourly_last` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `poller_output` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `poller_output_boost_local_data_ids` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `poller_output_boost_processes` ENGINE=InnoDB;
MariaDB [cacti]> ALTER TABLE `processes` ENGINE=InnoDB;

On Cacti 1.3 the data_source_stats_hourly_cache table already uses InnoDB, so that one statement is a no-op there. It is still required on 1.2.x.

These changes should replicate to the other nodes in your cluster. Allow Cacti to run at least two or three full polling cycles before placing the other nodes back into rotation.

Install and Configure Cacti

1. Extract the distribution tarball.

   shell> tar xzvf cacti-version.tar.gz
   

2. Create the MySQL database:

   shell> mysqladmin --user=root create cacti
   

3. Import the default cacti database:

   shell> mysql cacti < cacti.sql
   

4. Optional: Create a MySQL username and password for Cacti.

   shell> mysql --user=root mysql
   mysql> CREATE USER 'cactiuser'@'localhost' IDENTIFIED BY 'somepassword';
   mysql> GRANT ALL PRIVILEGES ON cacti.* TO 'cactiuser'@'localhost';
   mysql> GRANT SELECT ON mysql.time_zone_name TO 'cactiuser'@'localhost';
   mysql> FLUSH PRIVILEGES;
   

   Note that if your root (or equivalent) user does not have SUPER permissions, it may still be possible to GRANT SELECT privileges to the Cacti user via an INSERT INTO mysql.tables_priv.

   INSERT INTO mysql.tables_priv (Host, Db, User, Table_name, Grantor, Table_priv)
   VALUES ('localhost', 'mysql', 'cactiuser', 'time_zone_name', 'root@localhost', 'Select');
   

5. Edit include/config.php and specify the database type, name, host, user and password for your Cacti configuration.

   $database_type = "mysql";
   $database_default = "cacti";
   $database_hostname = "localhost";
   $database_username = "cactiuser";
   $database_password = "cacti";
   

6. Set the appropriate permissions on Cacti's directories for graph/log generation. You should execute these commands from inside Cacti's directory to change the permissions.

   shell> chown -R cactiuser rra/ log/ cache/
   

   (Enter a valid username for cactiuser, this user will also be used in the next step for data gathering.)

7. Create your cron task file or systemd units file

   Starting with Cacti 1.2.16, you have the option to use either the legacy Crontab entry, or an optional cactid units file and server to run your Cacti pollers.

   For Crontab use, follow the instructions below:

   Create and edit /etc/cron.d/cacti file. Make sure to setup the correct path to poller.php

   */5 * * * * apache php <path_cacti>/poller.php >/dev/null 2>&1
   

   To install the systemd unit file, first edit the included unit file to match your install location and the user and group the Cacti poller should run as. Then follow the procedure below:

   vim <path_cacti>/service/cactid.service (edit the path)
   touch /etc/sysconfig/cactid
   cp -p <path_cacti>/service/cactid.service /etc/systemd/system
   systemctl daemon-reload
   systemctl enable cactid
   systemctl start cactid
   systemctl status cactid
   

   The systemd units file makes managing a highly available Cacti setup a bit more convenient.

8. During install, you will need to provide write access to the following files and directories:

   shell> chown -R apache:apache resource scripts include/config.php
   

   Use the account your web server runs as. That is apache on Enterprise Linux and www-data on Debian and Ubuntu. Do not use the database account here, because it is a MySQL user rather than a system user.

   Once the installation is complete, you may change the permissions to more restrictive settings.

9. Point your web browser to:

   http://<your-server>/cacti/

   Log in with a username and password of admin. You will be required to change this password immediately. Make sure to fill in all of the path variables carefully and correctly on the following screen.

(Optional) Install and Configure Spine

Spine is a very fast data collection engine, written in C. It is an optional replacement for cmd.php. If you decide to use it, you will have to install it explicitly. It does not come with Cacti itself.

The easiest way is to install Spine using rpm or ports. You will find packages for Spine at the main Cacti site or from your distribution.

To compile Spine, download it to any location of your liking. Then, issue from the downloaded directory following commands

shell> ./bootstrap

If the bootstrap script is successful, you then will follow the instructions it provides to compile and install.

Assuming you installed Spine correctly, you must now configure it. The configuration file may be placed in the same directory as Spine itself or at /etc/spine.conf.

DB_Host     127.0.0.1 or hostname (not localhost)
DB_Database cacti
DB_User     cactiuser
DB_Pass     cactiuser
DB_Port     3306

Considerations when using Proxies in front of Cacti (Cacti 1.2.23+)

For optimal security, specify only the HTTP headers that your proxy software sets. This prevents unauthorized access through header spoofing. Set them by editing the following section of config.php:

/*
 * Allow the use of Proxy IPs when searching for client
 * IP to be used
 *
 * This can be set to one of the following:
 *   - false: to use only REMOTE_ADDR
 *   - true: to use all allowed headers (not advised)
 *   - array of one or more the following:
 *		'X-Forwarded-For',
 *		'X-Client-IP',
 *		'X-Real-IP',
 *		'X-ProxyUser-Ip',
 *		'CF-Connecting-IP',
 *		'True-Client-IP',
 *		'HTTP_X_FORWARDED',
 *		'HTTP_X_FORWARDED_FOR',
 *		'HTTP_X_CLUSTER_CLIENT_IP',
 *		'HTTP_FORWARDED_FOR',
 *		'HTTP_FORWARDED',
 *		'HTTP_CLIENT_IP',
 *
 * NOTE: The following will always be checked:
 *		'REMOTE_ADDR',
 */
$proxy_headers = null;

---

Copyright (c) 2004-2026 The Cacti Group