spine/INSTALL

Spine is a high speed poller replacement for cmd.php. It is almost 100%
compatible with the legacy cmd.php processor and provides much more
flexibility, speed and concurrency than cmd.php.

Make sure that you have the proper development environment to compile Spine.
This includes compilers, header files and things such as libtool. If you
have questions please consult the forums and/or online documentation.

Development
===========

DEVELOP branch should generally be considered UNSTABLE, use with caution!

-----------------------------------------------------------------------------

Unix Installation
=================

These instructions assume the default install location for spine
of /usr/local/spine. If you choose to use another prefix, make
sure you update the commands as required for that new path.

To compile and install Spine using MySQL versions 5.5 or higher
please do the following:

1. Run the bootstrap process to automatically create the configure script

   ./bootstrap

2. Run the configure process to detect what is available on the system

   ./configure

3. Build spine

   make

4. Optionally, install spine to the default location (/usr/local/spine/bin/)
   but do note that if you manually copy to another folder, change the paths
   below to reflect the correct folder you want spine to run from:

   make install
   chown root:root /usr/local/spine/bin/spine
   chmod u+s /usr/local/spine/bin/spine

   Spine is setuid root only so that it can send ICMP pings.  Before it
   reads any option or file it opens its raw ICMP sockets, or with
   --enable-lcap keeps only CAP_NET_RAW, and then drops root for good.  If
   it cannot get ICMP that way it still drops root and keeps polling: ICMP
   pings use datagram sockets where net.ipv4.ping_group_range allows them,
   and otherwise fall back to UDP with a warning.  Spine exits only if it
   cannot confirm that root is gone.  When root itself runs spine, for
   example from root's crontab, it keeps root as before.  Without the
   setuid bit, ICMP works where net.ipv4.ping_group_range covers the poller
   user, or where the binary has CAP_NET_RAW (setcap cap_net_raw+ep).

To compile and install Spine using MySQL versions previous to 5.5 please add
the additional --with-reentrant option to the ./configure command above but
please be aware that Cacti no longer officially supports MySQL prior to 5.5.

Windows Installation
====================

CYGWIN Prerequisite
-------------------

1. Download Cygwin for Window from https://www.cygwin.com/

2. Install Cygwin by executing the downloaded setup program

3. Select _Install from Internet_

4. Select Root Directory:  _C:\cygwin_

5. Select a mirror which is close to your location

6. Once on the package selection section make sure to select the following (TIP: use the search!):

      * autoconf
      * automake
      * dos2unix
      * gcc-core
      * gcc-debuginfo
      * gzip
      * help2man
      * libmariadb-devel (preferred) or libmysqlclient
      * libtool
      * m4
      * make
      * net-snmp-devel
      * libssl-devel
      * wget

7. Wait for installation to complete, coffee time!

8. Move the cygwin setup to the C:\cygwin\ folder for future usage.

Compile Spine
-------------

1. Open Cygwin shell prompt (C:\Cygwin\cygwin.bat) and brace yourself to use unix commands on Windows.

2. Download the Spine source to the current directory:
	http://www.cacti.net/spine_download.php

3. Extract Spine into C:\Cygwin\usr\src\<spineversion>:
	tar xzvf cacti-spine-*.tar.gz

4. Change into the Spine directory:
	cd /usr/src/cacti-spine-*

5. Run bootstrap to prepare Spine for compilation:
	./bootstrap

6. Follow the instruction which bootstrap outputs.

7. Update the spine.conf file for your installation of Cacti. You can optionally
   move it to a better location if you choose to do so, make sure to copy the
   spine.conf as well.

8. Ensure that Spine runs well by running with:
	/usr/local/spine/spine -R -S -V 3

9. Update Cacti 'Paths' Setting to point to the Spine binary and update the
   'Poller Type' to Spine. For the spine binary on Windows x64, and using default
   locations, that would be:
	C:\cygwin64\usr\local\spine\bin\spine.exe

10. If all is good Spine will be run from the poller in place of cmd.php.

--------------------------------------------------------------------------------------

Known Issues
============
1. On Windows, Microsoft does not support a TCP Socket send timeout. Therefore,
   if you are using TCP ping on Windows, spine will not perform a second or subsequent
   retries to connect and the host will be assumed down on the first failure.

   If this is a problem it is suggested to use another Availability/Reachability
   method, or moving to Linux/UNIX.

2. Spine takes quite a few MySQL connections. The number of connections is calculated
   as follows:

   * main poller take one connection
   * all threads take one connection each
   * all script servers take one connection each

   Therefore, if you have 4 processes, with 10 threads each, and 5 script servers each
   your spine will take approximately:

   total connections = 4 * ( 1 + 10 + 5 ) = 64

3. On older MySQL versions, different libraries had to be used to make MySQL thread
   safe. MySQL versions 5.0 and 5.1 require this flag. If you are using these version
   of MySQL, you must use the --with-reentrant configure flag.


-----------------------------------------------
Copyright (c) 2004-2026 - The Cacti Group, Inc.