pax_global_header 0000666 0000000 0000000 00000000064 14124124457 0014516 g ustar 00root root 0000000 0000000 52 comment=94ddb5569221b2f86e0dd3fabc15dea245d51a27
documentation-release-1.2.19/ 0000775 0000000 0000000 00000000000 14124124457 0016077 5 ustar 00root root 0000000 0000000 documentation-release-1.2.19/.github/ 0000775 0000000 0000000 00000000000 14124124457 0017437 5 ustar 00root root 0000000 0000000 documentation-release-1.2.19/.github/ISSUE_TEMPLATE/ 0000775 0000000 0000000 00000000000 14124124457 0021622 5 ustar 00root root 0000000 0000000 documentation-release-1.2.19/.github/ISSUE_TEMPLATE/bad_link.md 0000664 0000000 0000000 00000000701 14124124457 0023705 0 ustar 00root root 0000000 0000000 ---
name: Bad Link
about: Create a report to help us improve old links
title: ''
labels: 'old link,unverified'
assignees: ''
---
# Describe the link
Please describe what the old link was for use for and if possible what the new link should be.
## Old Link
[ OLD LINK ]
## New Link
[ NEW LINK ]
## Screenshots
If applicable, add screenshots to help explain your problem.
## Additional context
Add any other context about the problem here.
documentation-release-1.2.19/.github/ISSUE_TEMPLATE/bug_report.md 0000664 0000000 0000000 00000001517 14124124457 0024320 0 ustar 00root root 0000000 0000000 ---
name: Bug report
about: Create a report to help us improve
title: ''
labels: 'bug,unverified'
assignees: ''
---
# Describe the bug
A clear and concise description of what the bug is.
## To Reproduce
Steps to reproduce the behavior:
1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error
## Expected behavior
A clear and concise description of what you expected to happen.
## Screenshots
If applicable, add screenshots to help explain your problem.
## Desktop (please complete the following information)
- OS: [e.g. iOS]
- Browser [e.g. chrome, safari]
- Version [e.g. 22]
## Smartphone (please complete the following information)
- Device: [e.g. iPhone6]
- OS: [e.g. iOS8.1]
- Browser [e.g. stock browser, safari]
- Version [e.g. 22]
## Additional context
Add any other context about the problem here.
documentation-release-1.2.19/.github/ISSUE_TEMPLATE/config.yml 0000664 0000000 0000000 00000000435 14124124457 0023614 0 ustar 00root root 0000000 0000000 blank_issues_enabled: false
contact_links:
- name: Cacti Forums
url: https://forums.cacti.net/
about: Please ask and answer questions here.
- name: Confidential issues / Security notices
url: developers@cacti.net
about: Please report security vulnerabilities here.
documentation-release-1.2.19/.github/ISSUE_TEMPLATE/feature_request.md 0000664 0000000 0000000 00000001160 14124124457 0025345 0 ustar 00root root 0000000 0000000 ---
name: Feature request
about: Suggest an idea for this project
title: ''
labels: 'enhancement'
assignees: ''
---
# Feature Request
## Is your feature request related to a problem? Please describe
A clear and concise description of what the problem is. Ex. I'm always
frustrated when [...]
## Describe the solution you'd like
A clear and concise description of what you want to happen.
## Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've
considered.
## Additional context
Add any other context or screenshots about the feature request here.
documentation-release-1.2.19/.github/lock.yml 0000664 0000000 0000000 00000002204 14124124457 0021110 0 ustar 00root root 0000000 0000000 # Configuration for Lock Threads - https://github.com/dessant/lock-threads-app
# Number of days of inactivity before a closed issue or pull request is locked
daysUntilLock: 365
# Skip issues and pull requests created before a given timestamp. Timestamp must
# follow ISO 8601 (`YYYY-MM-DD`). Set to `false` to disable
skipCreatedBefore: false
# Issues and pull requests with these labels will be ignored. Set to `[]` to disable
exemptLabels: []
# Label to add before locking, such as `outdated`. Set to `false` to disable
lockLabel: false
# Comment to post before locking. Set to `false` to disable
lockComment: >
This thread has been automatically locked since there has not been
any recent activity after it was closed. Please open a new issue for
related bugs.
# Assign `resolved` as the reason for locking. Set to `false` to disable
setLockReason: false
# Limit to only `issues` or `pulls`
# only: issues
# Optionally, specify configuration settings just for `issues` or `pulls`
# issues:
# exemptLabels:
# - help-wanted
# lockLabel: outdated
# pulls:
# daysUntilLock: 30
# Repository to extend settings from
# _extends: repo
documentation-release-1.2.19/.github/stale.yml 0000664 0000000 0000000 00000001273 14124124457 0021275 0 ustar 00root root 0000000 0000000 # Number of days of inactivity before an issue becomes stale
daysUntilStale: 120
# Number of days of inactivity before a stale issue is closed
daysUntilClose: 7
# Issues with these labels will never be considered stale
exemptLabels:
- pinned
- security
- enhancement
# Label to use when marking an issue as stale
staleLabel: stale
# Comment to post when marking an issue as stale. Set to `false` to disable
markComment: >
This issue has been automatically marked as stale because it has not had
recent activity. It will be closed if no further activity occurs. Thank you
for your contributions.
# Comment to post when closing a stale issue. Set to `false` to disable
closeComment: false
documentation-release-1.2.19/.gitignore 0000664 0000000 0000000 00000000374 14124124457 0020073 0 ustar 00root root 0000000 0000000 # Ignore vim swap files
*.swp
# Ignore any mac DS_Store files
.DS_Store
# Ignore build HTML output
html/*
# Ignore local test filese
footer.html
include/*
manual/*
# Ignore any CertBot files
.well-known
.well-known/*
# Ignore any Git/GitHub files
.git* documentation-release-1.2.19/.mdl_style.rb 0000664 0000000 0000000 00000000774 14124124457 0020506 0 ustar 00root root 0000000 0000000 # customize style guide
all
rule "MD010", code_blocks: false
rule "MD013", code_blocks: false, tables: false
rule "MD029", style: "ordered"
rule "MD046", style: "fenced"
# Lesser rules
exclude_rule "MD010" # hard tabs
#exclude_rule "MD013" # line length
# Rule Exclusions
exclude_rule "MD001" # Headers are useful in other ways
exclude_rule "MD024" # Headers with same name are useful, but break link labeling (Rework needed on affected files before enabling this rule)
exclude_rule "MD046" # seems broken
documentation-release-1.2.19/.mdlrc 0000664 0000000 0000000 00000000074 14124124457 0017202 0 ustar 00root root 0000000 0000000 # mdl cli configuration
style ".mdl_style.rb"
verbose false
documentation-release-1.2.19/.travis.yml 0000664 0000000 0000000 00000002010 14124124457 0020201 0 ustar 00root root 0000000 0000000 before_install:
- gem install chef-utils -v 16.6.14
- gem install mdl
script:
- ./bin/check_missing_link.sh
- ./bin/check_markdown_style.sh
notifications:
email:
on_success: change
on_failure: always
recipients:
- developers@cacti.net
slack:
on_success: change
on_failure: always
rooms:
- secure: VjWdzdjUSMGwKCObjuyCOwyzCUV+LDwPsUxdmgPojTLGgZS12QOQxD0QNRUkvvtaus2SgbFP/B49NYsqOGrRCFy21aa2goNcqCXUlty8Pcs4L1NIT3L4rmC5DjwKtlL6sO9/HwbS1woFE7fhZ1KA2nIoTHYeGCZFpW1gGpm9VUEbab9m9gP3HagtULInzx02M7vVHA6WwgumWpYqX62St6Tb11YK0SjkUYRKuZN8Ezf8euChEN6OwFwmJnDbKc37kYPHy7SLCKJ3Vy9wbw8O+tYLf8sNauHu0XJGaTg1cvDMbNwLdVBcV6CeaVZTkLyPY46UJ0wprIieKu+HxCQT6CNX4UT3qd27OFtlNDnsJ1o/9f6OKjnRTqPcF6ynLZuzWVIvnPo45bsafvDl/AcfYnm0c4UG+gCZnyMfr432WJ+RJxYZvPgqCEwiweQQMvBSSD3GP2/lbYNRCgI/NU9JDEEWWrYMj/cJxDn1qvKJmdNj4W9nFnF1BqAldzVAQQgLO04K215t1skENChyvEi4+ocZ2A2EwGx582d2PrIK0CpQHcQKxAZl5TwKiuIFQlIOCqh8vt45KG1mY/t9FmVbyhxtrlMdjAAd/6Rxh7aICJQ0PQc0Lw9LX1f2a9/JBNrQ4QxRo/xco4ZI9AfonG5PbMxHEusnfeTC3ZnFU6y+P3I=
documentation-release-1.2.19/Aggregate-Templates.md 0000664 0000000 0000000 00000014026 14124124457 0022246 0 ustar 00root root 0000000 0000000 # Aggregate Templates
## Aggregate Overview
**Aggregate Templates** are a special form of a **Graph Template**. They
allow you to easily create **Graphs** that combine data from multiple common
**Graphs** from multiple **Devices**, and allow you to easily manage the
resulting **Aggregate Graphs** to add and remove elements from other
common **Graphs**.
To create **Aggregate Graphs** that are managed through a Template, you first
must create the **Aggregate Template**. Then from the Cacti
**Graphs** page, you can select the **Graphs** that you want used as part of
the **Aggregate**. You then select `Create Aggregate from Template` from the
Cacti Actions drop-down.
Once you have created your **Aggregate Graphs**, they behave like any other
Cacti Graph. They can be a part of a Tree, zoomed, etc. They have an added
bonus - you can add and remove **Graphs** from aggregate in a very controlled
way, reducing the effort to maintain them during their life-cycle.
If you wish to change settings for **Graphs** managed by the
**Aggregate Template**, simply make the changes in the **Aggregate Template**,
and they will cascade to **Aggregate Graphs** managed by the Template.
## Aggregate Template Interface
The images below shows an Aggregate Template for Traffic.
When you edit the **Aggregate Template**, you are presented with an interface
that allows you to define the Graph Canvas as well as it's formatting.
You should experiment until you find the mechanism that works best to suite
your needs.
The `Aggregate Template` `Prefix` setting allows you to provide a pattern to
be applied to the **Aggregate Graph** legend items. Any `host`, `query` or `input`
references can be used in the `Prefix` section in order to uniquely identify
the **Graph Item**.
There are several `Graph Types` transformations that deal with how `AREA`, `LINEX`
and `STACK` items are handled in the resulting **Aggeregate Graph**, they include:
- **Keep Graph Types** - No transformation will occur. All `AREA`, `LINE`, and `STACKS`
will be unchanged.
- **Keep Type and Stack** - Which means the types will be preserved, but all data
will be stacked instead of simply LINEX it will be transformed to LINEX:STACK
- **Convert to Area/STACK Graph** - All `LINEX` will be converted to `AREA` and
stacked.
- **Convert to LINE1** - All **Graph Items** will be converted to `LINE1`
- **Convert to LINE2** - All **Graph Items** will be converted to `LINE2`
- **Convert to LINE3** - All **Graph Items** will be converted to `LINE3`
- **Convert to LINE1/Stack** - All **Graph Items** will be converted to `LINE1`
and stacked.
- **Convert to LINE2/Stack** - All **Graph Items** will be converted to `LINE2`
and stacked.
- **Convert to LINE3/Stack** - All **Graph Items** will be converted to `LINE3`
and stacked.
The `Totaling` setting has multiple values. They include:
- **No Totals** - There will be no Summation of Data in the Legend
- **Print All Legend Items** - Means that all Legend Items selected will be
included with a Total
- **Print Totaling Legend Items Only** - This option means that the Legend will
total all the Legend items into a single Legend.
The `Total Type` - Will create groupings of common elements on the **Graph**,
and reset stacking rules when a change in the common element occurs. The
options include:
- **Total Similar Data Sources** - Means that you will Total legend items and
**Data Sources** through similar **Data Source** names, for example `traffic_out`
and `traffic_in`.
- **Total All Data Sources** - It means that you will sum the values for all
**Data Sources** regardless of their **Data Source** name.
When using `Total Type`, you are provided an option to additionally prefix your
legends using the `Prefix for GPRINT Totals` with a text value. The default
works in most cases.
The `Reorder Type` will re-order the **Data Sources** within their respective
grouping on the Graph so that they are ordered in a common way, in alphabetic
order. The options include:
- **No Reordering** - Don't make any changes in ordering.
- **Data Source, Graph** - Order by **Data Source** name and then by **Graph** name
- **Graph, Data Source** - Order by **Graph** name and then by **Data Source** name
- **Base Graph Order** - Focus on the **Graph** name only
The `Graph Template Items` section allows you to either Skip or Total (aka include)
the **Graph Items** in the resulting **Aggregate Graphs**. When you think about
how a resulting **Aggregate** graph will look, there are some elements that simply
will not result in a good looking **Graph**. In those cases you will
want to remove them from the resulting **Aggregate Graphs**.
The `Color Template` option allows you to use differing Color rotations when
displaying elements on the resulting **Aggregate Graphs**. **Color Templates**
can be added and removed from the **Color Templates** menu pick
under `Console > Templates`.
The several sections allow you to override any of the common **Graph Template**
elements from the resulting **Aggregate Graph**. We will not explain those options
here, only let you know that you can override them in your resulting
**Aggregate Graph**.
## Summary
There are several combinations of options that you
can use when working with an **Aggregate Template**. Some of these options will
results in horrible and unexpected outcomes, so you will have to experiment
until you come up with a desirable **Aggregate Template**.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Aggregates.md 0000664 0000000 0000000 00000000210 14124124457 0020463 0 ustar 00root root 0000000 0000000 # Aggregate Graphs
This section will describe **Aggregate Graphs** in Cacti.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Automation-Networks.md 0000664 0000000 0000000 00000003070 14124124457 0022353 0 ustar 00root root 0000000 0000000 # Automation Networks
This section will describe **Automation Networks** in Cacti.
Adding a network to scan in the automation plugin is easy. On the main console
click Automation. Once on the below page click the + on the top right of the page.
You will now see the below page. If you want to scan 192.168.1.0/24, you would
enter that in the subnet range textbox then enter the subnet in CIDR format.
Other important options are
Optiom | Descriptiom
--- | ---
Schedule type | How often you want to scan this subnet for devices
Discovery threads | How many proccessess to spawn during the scan
Max Runtime | to prevent the scan from running indefinetly
Automatically add to Cacti | If a device is SNMP reachable and matches a rule from this subnet the device will be added
Netbios | Attempt to resolve the hostname by netbios
After you are done adding your network details, ensure you enable the rule and
save.
Ensure that if you have a SNMP rule for this part of the network to select the
SNMP option set this will tie the network to the SNMP rules
To begin the scanner click on the bottom right drop down and select "Discover
Now" this will start the discovery
Here is the flow of the automation scan
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Boost.md 0000664 0000000 0000000 00000021117 14124124457 0017511 0 ustar 00root root 0000000 0000000 # Performance Boosting Settings
## Summary
Cacti Performance Settings, formally known as `boost` are available to support
very large Cacti installations, and are required for supporting the multiple
**Data Collector** architecture that Cacti affords. Designed years ago,
Boosts intent was to reduce the the main data collectors cycle time by caching
writes to disk, and those writes would be handled by an out of band process
currently known as `poller_boost.php`. Since these Large Sites had
potentially well over one million **Data Sources**, there was previously
no way to write all that data every 5 minutes. So, the buffering helped
with maintaining a consistent run-time, and minimizing the user experience
disruption from all that blocking Disk I/O.
In the modern Data Center, where we find an abundance of NVMe, Flash,
and SSD's, the impact of all that I/O has been reduced. However, Boost now
serves as a way to extend the life of your Flash media and therefore increase
the availability of your Cacti server over its lifetime.
The Boost function in Cacti has several features that can be enabled or
disabled on demand by the Cacti Administrator. They include:
- **On Demand RRD Updates** - Required in ALL multiple **Data Collector**
installs and control the mass update of RRDfiles through periodic dumping
of Cacti's Boost cache.
- **Image Caching** - caches PNG and SVG representations of the
Cacti **Graphs** to reduce the overall CPU utilization of the Cacti server
infrastructure.
## Prerequisites
In its initial design the Boost process leveraged MySQL Memory Tables to
increase overall performance, and to reduce writing data to disk. This is
still a valid case however, with improvements in InnoDB performance over the
years combined with Flash storage, the need for using MySQL Memory Tables
has diminshed. In some cases, for example when using MariaDB Galera, or
MySQL Master/Slave replication, it can not be used.
If you do wish to use Memory you have to pay close attention to the
amount of data that will be cached in your design. You should periodically
check that you have sufficient memory available to cache all the data in the
Boost cache. The MySQL/MariaDB setting that controls the maximum size of a
memory table is the `max_heap_table_size` setting in your
`/etc/my.cnf.d/server.cnf` file.
To change the `max_heap_table_size` setting you require a restart of
MySQL/MariaDB. So you won't want to make these changes often,
as some systems have little time between mass updates to perform a restart.
If you restart MySQL/MariaDB when the cache is full, you will lose those
updates upon restart unless you first change the ENGINE of the Boost cache
table to InnoDB or MyISAM before restarting.
When using Memory Tables you have to be cognizant of the maximum output
width of the Cache table called `poller_output_boost`. By default, it's set
to 512 bytes, which allows for very wide output from your **Data Collectors**.
MySQL Memory Tables do not allow for variable sized columns in memory -
which means if you write one byte to it, it will take 512 bytes. So, tuning
this width is very important. That will be explained in more detail later on
in this chapter.
To see how your system is configured, you can goto
`Console > Utilityes > System Utilities > View Boost Status` option, when you
go there, you will see an image similar to that below.
From this image, we can tell a few things:
- Boost is Idle, or flushing the Cache
- The system has 1,120 Data Sources in total
- There are currently 58,710 Boost records cached in all tables
Additionally, you can tell
- Our Current Database Engine is InnoDB
- The size of the current table is 3.52 MBytes
- The average 'Bytes/Record' is 62
- We have unlimited Records that can be stored there
From that Data, we know if we were to use a Memory Table, at present
it's width could be say 100 Bytes and we could cut memory use by 80%.
We can also estimate from this interface, how large our `max_heap_table_size`
would ultimately have to be, keeping in mind that the
`Current Boost Table Size` is misleading since even though each record
can be in excess of 512 bytes, it's presently only using 62 bytes of
total storage per record.
In the image below, you can see runtime statistics, update frequencies, and
Image Caching settings, which are currently disabled.
From this setup, you can see that mass RRDfile updates are only
happening roughly every 6 hours to minimize wear and tear on the SSD
storage in use.
## Enabling Boost
To find and Enable the Boost settings, you first go to
`Console > Configuration > Settings > Performance`.
From this interface, in the image below, you can setup Boost.
As an exercise, lets look at a fictitious setup and determine what
the `max_heap_table_size` should be. Let's say, for example, that your
Cacti systems **Poller Cache** contains 200k rows, and the maximum length
of any rows output is 20 bytes, about the size of a 64bit counter value.
If you are running scripts, ones that return very long results,
like the MySQL statistics plugin, you should consider carefully the
next step.
In this case, we will assume that even though the largest value returned
is 20 bytes, we will elect to maintain a maximum output column
width of 50 bytes.
The important thing here is that memory tables store the full size of
the column, even though the column type is `varchar()`. By default it's
`varchar(512)`. Therefore, if your system only needs 50 bytes, you will
have 90% waste in your `poller_output_boost` table.
The next step would me to modify the structure of your `poller_output`
and `poller_output_boost` tables. You would do this by doing the following:
```sql
ALTER TABLE poller_output,
MODIFY column output varchar(50) NOT NULL default ""
ENGINE=memory;
ALTER TABLE poller_output_boost,
MODIFY column output varchar(50) NOT NULL default ""
ENGINE=memory;
```
As previously mentioned, its also important that the `poller_output` table
is converted to memory, eliminate any disk I/O related to poller updates.
Now, you need to determine how many polling cycles will fit into your
`poller_output_boost` table. In this case, when sizing the `poller_output_boost`
table, you take the output column width and add 34 bytes per record.
So, in this case, each data source result to be stored in the
`poller_output_boost` table would take 84bytes.
Then, with the Maximum Heap Table size in hand, and let's say the
default is 16MBytes for the largest table (the MySQL default), you can
calculate the number of poller intervals that you can store without
running out of MySQL memory. So, let's take our example:
```console
200k Cache Entries x 84 Bytes Per Poller Cache Row = 1,680,000 Bytes per Poll
```
This means that your `poller_output_boost` can handle 10 Cacti polling cycles,
or roughly 4/5 of an hour of poller data before it must be cleared by the system.
As all things go, you should not want to take your system to the edge.
So, it is best to increase the `max_heap_table_size` of your system to ensure
you have buffer in cases where say for example, your disks become degraded over
time and the Boost cycle is extended as a result.
But let's look at the problem a different way. Let's say that you wish to
perform major updates every 4 hours. With a 50% memory reserve, we should
plan for 6 hours of updates. This way, we need to have size for 72 poller
cycles in your `poller_output_boost` table. This means that the
`max_heap_table_size` must be at least 131,040,000 Bytes.
So, let's call it a deal. Provided you have enough memory, and I expect
that you do, you would edit the /etc/my.cnf.d/server.cnf and add/modify
the following line:
```console
max_heap_table_size=132M
```
Then, save the file, and restart MySQL. Once this is done, you are ready
to “enable” Boost as described above.
## Flushing the Boost Cache
If you are planning on system maintenance if you are using MEMORY storage
in MySQL or MariaDB, you should flush your Boost Cache before your system
is taken offline for maintenance. To do this, you simply login to the
Cacti system as root, and flush the Cache using the commands below
```console
cd /var/www/html/cacti
php -q poller_boost.php --force
```
This operation will take several minutes to complete, at which time there
will be additional records in the `poller_output_boost` table. So, it
might be better that after the `poller_boost.php` process is complete,
to modify the `poller_output_boost` table to InnoDB before reboot,
and then convert it back to memory after they system maintenance is
complete.
documentation-release-1.2.19/CDEFs.md 0000664 0000000 0000000 00000011503 14124124457 0017305 0 ustar 00root root 0000000 0000000 # CDEFs
## Background
CDEF's in Cacti are a one to one analog to CDEF's in RRDtool. Cacti
simply provides and interface to create and manage them. Once the
CDEF's are created in Cacti they can be imported and exported globally.
CDEF's are mathematical formulas that either modify the numeric data from
one to many data sources or VNAMES that you have in your **Graph Template**.
The format of the mathematical formulas is called Reverse Polish Notation (RPN).
RPN was and is an early form of how Engineers entered equations into early
HP and other Calculators to solve Engineering problems. The reason we still
use it today, is that it follows a simple Stack principle. In other words,
it's not broken.
CDEF's can get very complex as there are several mathematical functions
available in the RRDtool command set.
## CDEF Interface
In the image below, you can see all the CDEF's that are included in Cacti by
default. There are quite a few of them. Many of the forulas in use are quite
simple. If you want to view Tutorials on how to work with CDEF's you should
go to the [RRDtool Tutorial](https://oss.oetiker.ch/rrdtool/tut/cdeftutorial.en.html).
There is also documentation at the [RRDtool Website](https://oss.oetiker.ch/rrdtool/doc/rrdgraph_data.en.html#CDEF).
In this image you can see that you have the ability to Delete or Duplicate a CDEF,
but note you will not be able to Delete any CDEF that is associated with a Cacti
**Graph** or **Graph Template**.
When you Click on the CDEF's name, you will enter into an Edit screen. From there
you will see an ordered list of your Stack. It normally will begin with something
like the CURRENT_DATA_SOURCE which means that when you Add a **Graph Item** to
either a **Graph Template** or **Graph**, you can select a CDEF. The
**Data Source** associated with that **Graph Items** is the CURRENT_DATA_SOURCE.
After that, you may see a numeric number, followed by a math operator. That the
simplest form of a CDEF. If you have drag & drop enabled, you can re-order the
CDEF items using drag & drop. Otherwise you will see arrows that allow you
to move the CDEF Items up and down.
When editing a CDEF, the first decision is what Type of Data you want to put on
the Stack, you options as shown in the image below. They include:
Name | Description
--- | ---
Function | A mathmatical function that we will describe below
Operator | Common mathematical operators including (+, -, *, /, and %)
Another CDEF | Another Cacti CDEF. That could be confusing
Custom String | Something like a number, a 'U' or 'Nan' for example
## Special Data Sources
In this next Image, you will find a CDEF Item in the process of being added. Note
that when you pick `Special Data Source` you have a drop-down that appears with
the flavor of `Special Data Source`. There are many. They include:
Name | Description
--- | ---
Current Graph Item Data Source | The value of the Data Source associated with the Graph Item
Current Graph Item Polling Interval | This value is otherwise known as the Step in RRDtool terminology
All Data Sources (No Dupes) | The total of all Data Sources removing any duplicate DEF's
All Data Sources (With Dupes) | Add the values from all the Data Sources whether or not they are duplicated
All Similar Data Sources (No Dupes) | Means all Data Sources with the same RRDtool Data Source name like traffic_in, and traffic_out
All Similar Data Sources (No Dupes) Poller Interval | The max of the poller intervals returned from all similar Data Sources
Current Data Source Item: Minimum Value | The RRDtool minimum value of the Current Data Source
Current Data Source Item: Maximum Value | The RRDtool maximum value of the Current Data Source
Graph: Lower Limit | The lower Limit of the Graph
Graph: Upper Limit | The upper Limit of the Graph
Count of All Data Sources (No Dupes) | The total count of all Data Sources without Duplication
Count of All Data Sources (With Dupes) | The total count of all Data Sources including Duplicates
Count of Similar Data Sources (No Dupes) | The total count of Data Sources with the same RRDtool Data Source Name
Count of Similar Data Sources (With Dupes) | The total count of Data Sources with the same RRDtool Data Source Name
As you can see there is quite a bit of information that can be pulled from
RRDtool for performing Graphical manipulation of Data.
## CDEF Functions
This list of CDEF functions is long and it's best to refer directly to the
[RRDtool Manual](https://oss.oetiker.ch/rrdtool/doc/rrdgraph_rpn.en.html) for meanings
and examples of their use. Cacti supports all of them, if you find one that is not
supported, open an [Issue on Github](https://github.com/Cacti/cacti/issues).
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Color-Templates.md 0000664 0000000 0000000 00000002637 14124124457 0021443 0 ustar 00root root 0000000 0000000 # Color Templates
**Color Templates** define a list of Colors to be used for **Aggregate Graphs**
in Cacti. As you add **Graphs** to an **Aggregate Graph**, you need to
distinguish one **Graph** from the next within the **Aggregate Graph**. These
**Color Templates** are a list of colors that will be looped through in Round
Robin fashion to render the **Aggregate Graph**.
So, for example, if your **Color Template** uses 8 differing **Colors**, and
your **Aggregate Graph** includes 16 *Graph Items*, then each color will be used
twice in the **Aggregate Graph**.
Below, you can see the four standard **Color Templates**, you can see that you
have the ability to either *Delete* or *Duplicate* the **Color Templates**. As
with other Cacti objects, you will not be allowed to *Delete* a **Color
Template** in use.
In the image below, you can see the **Color Template** edit screen. This simply
screen allows you to add, remove and re-order colors in the list.
Shown in the image below, only Cacti **Colors** are allowed to be selected for
Aggregate **Color Templates**. The **Color** drop down can by typed into if you
wish to search through the list of approximately 340 legacy and *Named Colors*.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Colors.md 0000664 0000000 0000000 00000002675 14124124457 0017674 0 ustar 00root root 0000000 0000000 # Colors
Colors in Cacti come in two types and used to maintain a list of colors that can
be used in Cacti for **Graph Templates** and **Graphs**.
The first type are the legacy Cacti colors imported from earlier versions of
Cacti. Starting with Cacti 1.0, Cacti started to support the concept of *Named
Colors* which come from a well known dictionary of well defined colors. *Named
Colors* are read only in Cacti. While the legacy Cacti colors can be named as
the Cacti administrator desires.
The image below shows a list of Cacti *Named Colors*. You can see that there is
a search bar and check boxes for showing just *Named Colors* or all colors, and
another check box for showing Colors that are used in **Graph Templates** and
*Graphs*. You can not remove either the *Named Colors* or Colors that are in
use by either a **Graph Template** or **Graph**.
The image below is the Color edit screen. If the color is read only, you can
open this page, but not change any of the details. For legacy Cacti colors, or
for Colors added by the Cacti Administrator, you can change the name and the
Color hex value.
Below, you can see the color picker that allows you to visually find the
appealing color. You can also use hex values that were previously supported in
earlier Cacti version.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Command-Line-Scripts.md 0000664 0000000 0000000 00000135654 14124124457 0022327 0 ustar 00root root 0000000 0000000 # 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.
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 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.
> **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.
In the sub-sections below, we will demonstrate the use of a few of these CLI scripts.
## 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-2018 - 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-2018 - 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-2018 - 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-2018 - 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-2018 The Cacti Group
usage: copy_cacti_user.php
A utility to copy on local Cacti user and their settings to a new one.
NOTE: It is highly recommended that you use the web interface to copy users as
this script will only copy Local Cacti users.
```
Now let's create a new user Harry Potter as follows
```console
shell>php -q copy_user.php guest "Harry Potter"
Template User: guest
New User: Harry Potter
Copying User...
User copied...
```
Find the results of this program call at User Management
User Name\*\* | Full Name | Enabled | Realm | Default Graph Policy | Last Login
--- | --- | --- | --- | --- | ---
admin | Administrator | Yes | Local | ALLOW | Sunday, October 07, 2007 14:59:32
guest | Guest Account | Yes | Local | ALLOW | N/A
Harry Potter | Guest Account | Yes | Local | ALLOW | N/A
## Add a New Device
While it is an easy task to add a new device from the panels, this would be a
tedious task for creating dozens of hundreds of devices in one turn. This is,
where the script `add_device.php` comes in. First, let's have a look at the
whole list of features it provides. Calling the script with the parameter
`--help` yields
```console
shell>php -q add_device.php --help
Add Device Script 1.0, Copyright 2004-2018 - The Cacti Group
A simple command line utility to add a device in Cacti
usage: add_device.php --description=[description] --ip=[IP] --template=[ID] [--notes="[]"] [--disable]
[--avail=[ping]] --ping_method=[icmp] --ping_port=[N/A, 1-65534] --ping_retries=[2]
[--version=[1|2|3]] [--community=] [--port=161] [--timeout=500]
[--username= --password=] [--authproto=] [--privpass= --privproto=] [--context=]
[--quiet]
Required:
--description the name that will be displayed by Cacti in the graphs
--ip self explanatory (can also be a FQDN)
Optional:
--template 0, is a number (read below to get a list of templates)
--notes '', General information about this host. Must be enclosed using double quotes.
--disable 0, 1 to add this host but to disable checks and 0 to enable it
--avail pingsnmp, [ping][none, snmp, pingsnmp]
--ping_method tcp, icmp|tcp|udp
--ping_port '', 1-65534
--ping_retries 2, the number of time to attempt to communicate with a host
--version 1, 1|2|3, snmp version
--community '', snmp community string for snmpv1 and snmpv2. Leave blank for no community
--port 161
--timeout 500
--username '', snmp username for snmpv3
--password '', snmp password for snmpv3
--authproto '', snmp authentication protocol for snmpv3
--privpass '', snmp privacy passphrase for snmpv3
--privproto '', snmp privacy protocol for snmpv3
--context '', snmp context for snmpv3
List Options:
--list-host-templates
--list-communities
--quiet - batch mode value return
```
Wow, that's quite a lot of options. To better understand it's use, let's first
stick to the listing options
### List all Host Templates
```console
shell>php -q add_device.php --list-host-templates
Valid Host Templates: (id, name)
1 Generic SNMP-enabled Host
3 ucd/net SNMP Host
4 Karlnet Wireless Bridge
5 Cisco Router
6 Netware 4/5 Server
7 Windows 2000/XP Host
8 Local Linux Machine
```
Why are those `Host Templates` of such importance for this script? Well, when
using this script to add a new device, there are 3 required parameters. The
`description` and the `device ip address` are of course left to you. But for
assigning the correct `Host Template Id`, you should first know the correct id
of that very parameter. For the purpose of this chapter we assume to add a
device that will be associated to a `ucd/net SNMP Host`, so the id of `3` is
required.
If you do not want to associate the host to any `Host Template Id`, known as
host template None, either provide the parameter `--template=0` or omit this
parameter.
### List all Community Strings
```console
shell>php -q add_device.php --list-communities
Known communities are: (community)
public
snmp-get
```
Of course, your list will vary
### Create a New Device
Now, let's set up the most basic command to add a new device. The description
shall be `"Device Add Test"`, the ip will be given as a FQDN,
`router.mydomain.com`. As a SNMP enabled device, surely a community string has
to be provided; in this case given as `public`. In total, this makes the
following command
```console
shell>php -q add_device.php --description="Device Add Test" --ip="router.mydomain.com" --template=3 --community="public"
Adding Device Add Test (router.mydomain.com) as "ucd/net SNMP Host" using SNMP v1 with community "public"
Success - new device-id: (11)
```
Go to Devices to see the result:
Description** | Graphs | Data Sources | Status | Hostname | Current (ms) | Average (ms) | Availability
--- | ---| --- | --- | --- | --- | --- | ---
Device Add Test | 0 | 0 | Unknown | router.mydomain.com | 0 | 0 | 100
Use any other combination of parameters in the same way as via the web browser
console. You may want to remember the new device id, `11` in this case, for the
next steps.
## Associate a Data Query to an existing Host
It is recommended to maintain data query associations by maintaining host
templates. Each time, a data query is added to a host template, it will
automatically associated with all hosts related to that very host
template. The data query will be executed as well; this way the snmp
cache will be filled with all values related to that query.
Nevertheless, it is sometimes suitable to manually associate a certain
data query with a single host only without changing any host template.
This is, where the script `add_data_query.php` comes in. First, let's
have a look at the whole list of features it provides. Calling the script
with the parameter `--help` yields
```console
shell>php -q add_data_query.php --help
Add Data Query Script 1.0, Copyright 2004-2018 - The Cacti Group
A simple command line utility to add a data query to an existing device in Cacti
usage: add_data_query.php --host-id=[ID] --data-query-id=[dq_id] --reindex-method=[method] [--quiet]
Required:
--host-id the numerical ID of the host
--data-query-id the numerical ID of the data_query to be added
--reindex-method the reindex method to be used for that data query
0|None = no reindexing
1|Uptime = Uptime goes Backwards
2|Index = Index Count Changed
3|Fields = Verify all Fields
List Options:
--list-hosts
--list-data-queries
--quiet - batch mode value return
If the data query was already associated, it will be reindexed.
```
Let's first stick to the listing options
### List all Hosts
```console
shell>php -q add_data_query.php --list-hosts
Known Hosts: (id, hostname, template, description)
1 127.0.0.1 8 Localhost
11 router 3 router.mydomain.com
```
### List all Data Queries
```console
shell>php -q add_data_query.php --list-data-queries
Known SNMP Queries:(id, name)
1 SNMP - Interface Statistics
2 ucd/net - Get Monitored Partitions
3 Karlnet - Wireless Bridge Statistics
4 Netware - Get Available Volumes
6 Unix - Get Mounted Partitions
7 Netware - Get Processor Information
8 SNMP - Get Mounted Partitions
9 SNMP - Get Processor Information
```
### Add a Data Query
```console
shell>php -q add_data_query.php --host-id=11 --data-query-id=1 --reindex-method=fields
Success - Host (11: router.mydomain.com) data query (1: SNMP - Interface Statistics) reindex method (3: Verify All Fields)
```
This example shows the use of a string `"fields"` for specifying the reindex
method. As given by the help text, the use of the numeric value of `"3"` would
have given the exact same result. When visiting the device edit panel, you will
find non-zero values for the data query status column, e.g. *Success [41 Items,
5 Rows]*.
## Associate a Graph Template to an existing Host
It is recommended to maintain graph template associations by maintaining host
templates. Each time, a graph template is added to a host template, it will
automatically associated with all hosts related to that very host template.
Nevertheless, it is sometimes suitable to manually associate a certain graph
template with a single host only without changing any host template. This is,
where the script `add_graph_template.php` comes in. First, let's have a look at
the whole list of features it provides. Calling the script with the parameter
`--help` yields
```console
shell>php -q add_graph_template.php --help
Add Graph Template Script 1.0, Copyright 2004-2018 - The Cacti Group
A simple command line utility to associate a graph template with a host in Cacti
usage: add_graph_template.php --host-id=[ID] --graph-template-id=[ID]
[--quiet]
Required:
--host-id the numerical ID of the host
--graph_template-id the numerical ID of the graph template to be added
List Options:
--list-hosts
--list-graph-templates
--quiet - batch mode value return
```
Let's first stick to the listing options
### List all Hosts for a graph template
```console
shell>php -q add_graph_template.php --list-hosts
Known Hosts: (id, hostname, template, description)
1 127.0.0.1 8 Localhost
11 router 3 router.mydomain.com
```
### List all Graph Template
```console
shell>php -q add_graph_template.php --list-graph-templates
Known Graph Templates:(id, name)
2 Interface - Traffic (bits/sec)
3 ucd/net - Available Disk Space
4 ucd/net - CPU Usage
5 Karlnet - Wireless Levels
6 Karlnet - Wireless Transmissions
7 Unix - Ping Latency
8 Unix - Processes
9 Unix - Load Average
10 Unix - Logged in Users
11 ucd/net - Load Average
...
```
### Add a Graph Template
```console
shell>php -q add_graph_template.php --host-id=11 --graph-template-id=7
Success: Graph Template associated for host: (11: router) - graph-template: (7: Unix - Ping Latency)
```
## Add a New Graph
You won't stop now as you've just created a device from cli. Surely, the
task of setting up graphs is the next step. This is done using
`add_graphs.php`. Calling the script with the parameter `--help` yields
```console
shell>php -q add_graphs.php
Add Graphs Script 1.2, Copyright 2008 - The Cacti Group
A simple command line utility to add graphs in Cacti
usage: add_graphs.php --graph-type=[cg|ds] --graph-template-id=[ID]
--host-id=[ID] [--graph-title=title] [graph options] [--force] [--quiet]
For cg graphs:
[--input-fields="[data-template-id:]field-name=value ..."] [--force]
--input-fields If your data template allows for custom input data, you may specify that
here. The data template id is optional and applies where two input fields
have the same name.
--force If you set this flag, then new cg graphs will be created, even though they
may already exist
For ds graphs:
--snmp-query-id=[ID] --snmp-query-type-id=[ID] --snmp-field=[SNMP Field] --snmp-value=[SNMP Value]
[--graph-title=] Defaults to what ever is in the graph template/data-source template.
[--reindex-method=] the reindex method to be used for that data query
if data query already exists, the reindex method will not be changed
0|None = no reindexing
1|Uptime = Uptime goes Backwards (Default)
2|Index = Index Count Changed
3|Fields = Verify all Fields
List Options:
--list-hosts
--list-graph-templates [--host_template=[ID]]
--list-input-fields --graph-template-id=[ID]
--list-snmp-queries
--list-query-types --snmp-query-id [ID]
--list-snmp-fields --host-id=[ID] [--snmp-query-id=[ID]]
--list-snmp-values --host-id=[ID] [--snmp-query-id=[ID]] --snmp-field=[Field]
'cg' graphs are for things like CPU temp/fan speed, while
'ds' graphs are for data-source based graphs (interface stats etc.)
```
Like the graph creation from the console, this task is split into two different
ones:
- **Associated Graph Templates:**
These are named `cg` graph_type for this script.
- **Associated Data Queries:**
These are named `ds` graph_type for this script. Additional SNMP parameters
are required to define those graphs.
> **Caution**
>
> When running this cli script, caution must be taken to avoid typos.
> Sometimes, list options take an ending “s”, where the option for graph
> creation comes without “s”. Error messages are not issued to indicate
> this typo; instead you will see the general help screen.
### List Options for Associated Graph Templates
The first list option, `--list-hosts`, is required only if you do not know the
`id` of the device you want to add graphs for. It will produce output as follows
```console
shell>php -q add_graphs.php --list-hosts
Known Hosts: (id, hostname, template, description)
...
11 router.mydomain.com 3 Device Add Test
```
You surely recognize the device we've just added?
The next list option, `--list-graph-templates`, is required to identify the
number of an `Associated Graph Templates`.
```console
shell>php -q add_graphs.php --list-graph-templates
Known Graph Templates:(id, name)
2 Interface - Traffic (bits/sec)
3 ucd/net - Available Disk Space
4 ucd/net - CPU Usage
5 Karlnet - Wireless Levels
6 Karlnet - Wireless Transmissions
7 Unix - Ping Latency
8 Unix - Processes
9 Unix - Load Average
...
```
We will need the graph template id of the `ucd/net - CPU Usage` template later.
So note the number `4` for it.
It is possible to reduce the listing to the graph templates associated with a
specific host template by using `--list-graph-templates
--host-template-id=[id]`. For a "ucd/net SNMP Host" this yields
```console
shell>php -q add_graphs.php --list-graph-templates --host-template-id=3
Known Graph Templates:(id, name)
4 ucd/net - CPU Usage
11 ucd/net - Load Average
13 ucd/net - Memory Usage...
```
### List Options for Associated Data Queries
First task is to find all id's for available data queries.
```console
shell>php -q add_graphs.php --host-id=2 --list-snmp-queries
Known SNMP Queries:(id, name)
1 SNMP - Interface Statistics
2 ucd/net - Get Monitored Partitions
3 Karlnet - Wireless Bridge Statistics
4 Netware - Get Available Volumes
6 Unix - Get Mounted Partitions
7 Netware - Get Processor Information
8 SNMP - Get Mounted Partitions
9 SNMP - Get Processor Information
```
For standard interface statistics, we note the id of `1`
Next task is to find the query_type as done by issuing
```console
shell>php -q add_graphs.php --snmp-query-id=1 --list-query-types
Known SNMP Query Types: (id, name)
2 In/Out Errors/Discarded Packets
3 In/Out Non-Unicast Packets
4 In/Out Unicast Packets
9 In/Out Bytes (64-bit Counters)
13 In/Out Bits
14 In/Out Bits (64-bit Counters)
16 In/Out Bytes
20 In/Out Bits with 95th Percentile
21 In/Out Bits with Total Bandwidth
22 In/Out Bytes with Total Bandwidth
23 In/Out Bits 1 min
24 In/Out Bits 1 min (64-bit Counters)
```
For a standard `In/Out Bits` type, we note the id of `13`
Next issue is to select the `SNMP Field` that shall be used for a new graph.
```console
shell>php -q add_graphs.php --host-id=11 --list-snmp-fields
Known SNMP Fields for host-id 11: (name)
ifAlias
ifDescr
ifHwAddr
ifIndex
ifIP
ifName
ifOperStatus
ifSpeed
ifType
```
For our graph, we will use the field `ifOperStatus` to select the correct
interfaces.
In general, you will next determine the values available for the `SNMP Field`,
in our case `ifOperStatus`. This is done by
```console
shell>php -q add_graphs.php --host-id=11 --snmp-field=ifOperStatus --list-snmp-values
Known values for ifOperStatus for host 11: (name)
Down
Up
```
This is no surprise, of course. Now, all parameters required for creating a new
graph are determined.
### Add Non-Indexed Graphs
We will create a graph for `ucd/net - CPU Usage`. Above, we've identified the
graph template it to be `4`. In total, that makes up for the following command
```console
shell>php -q add_graphs.php --host-id=11 --graph-type=cg --graph-template-id=4
Graph Added - graph-id: (39) - data-source-id: (63)
```
Find the result when visiting Graph Management
Graph Title** | Template Name | Size
--- | --- | ---
Device Add Test - CPU Usage | ucd/net - CPU Usage | 120x500
If the graph template was not associated with that host before, it is now added
to the list of Associated Graph Templates.
### Add Indexed Graphs
First, let's sum up the id's of all resources required for this task:
###### Table 20-2. Parameters required for an Interface Traffic Graph
Object | Value | Description
--- | --- | ---
Graph Template Id | 2 | Interface - Traffic (bits/sec)
SNMP Query Id | 1 | SNMP - Interface Statistics
SNMP Query Type Id | 13 | In/Out Bits
SNMP Field | ifOperStatus | Field name
SNMP Value | Up | Field value
This will make up for the following command
```console
shell>php -q add_graphs.php --host-id=11 --graph-type=ds --graph-template-id=2 --snmp-query-id=1 --snmp-query-type-id=13 --snmp-field=ifOperStatus --snmp-value=Up
Graph Added - graph-id: (40) - data-source-id: (65)
```
Find the result when visiting Graph Management
Graph Title** | Template Name | Size
--- | --- | ---
Device Add Test - CPU Usage | ucd/net - CPU Usage | 120x500
Device Add Test - Traffic - lo | Interface - Traffic (bits/sec) | 120x500
If the data query was not associated with that host before, it is now added to
the list of Associated Graph Templates. In this case, the Re-Index Method of
`Uptime Goes Backwards` is defaulted if not given otherwise. You may provide a
different Re-Index Method by entering the optional parameter `--reindex-method`.
## Add Items to a Tree
Now, that we've created some nice graphs, they should be put the graph trees.
This is done using `add_tree.php`. As you will notice soon, it is possible to
even add header items, hosts and graphs to a tree as well as adding a new tree
itself. But let us first see the help output. Calling the script with the
parameter `--help` yields
```console
shell>php -q add_tree.php --help
Add Tree Script 1.0, Copyright 2004-2018 - The Cacti Group
A simple command line utility to add objects to a tree in Cacti
usage: add_tree.php --type=[tree|node] [type-options] [--quiet]
Tree options:
--name=[Tree Name]
--sort-method=[manual|alpha|natural|numeric]
Node options:
--node-type=[header|host|graph]
--tree-id=[ID]
[--parent-node=[ID] [Node Type Options]]
Header node options:
--name=[Name]
Host node options:
--host-id=[ID]
[--host-group-style=[1|2]]
(host group styles:
1 = Graph Template,
2 = Data Query Index)
Graph node options:
--graph-id=[ID]
[--rra-id=[ID]]
List Options:
--list-hosts
--list-trees
--list-nodes --tree-id=[ID]
--list-rras
--list-graphs --host-id=[ID]
```
### List Hosts
The first try is dedicated to the list option `--list-hosts`. It goes like
```console
shell>php -q add_tree.php --list-hosts
Known Hosts: (id, hostname, template, description)
1 127.0.0.1 8 Localhost
2 gandalf 3 gandalf
...
11 router.mydomain.com 3 Device Add Test
```
### List Trees
Now, let us `--list-trees`. It goes like
```console
shell>php -q add_tree.php --list-trees
Known Trees:
id sort method name
1 Manual Ordering (No Sorting) Default Tree
```
### List Nodes
Listing all existend node of a given tree is done by
```console
shell>php -q add_tree.php --list-nodes --tree-id=1
Known Tree Nodes:
type id text
Host 7 127.0.0.1 Graph Template
Host 9 gandalf Graph Template
Host 12 gandalf Graph Template
```
### List RRAs
For special tree add options, you will require the id of the RRA definition to
completely specify the add request. That's why the corresponding `--list-rras`
option is implemented. It goes this way
```console
shell>php -q add_tree.php --list-rras
Known RRAs:
id steps rows timespan name
1 1 600 86400 Daily (5 Minute Average)
2 6 700 604800 Weekly (30 Minute Average)
3 24 775 2678400 Monthly (2 Hour Average)
4 288 797 33053184 Yearly (1 Day Average)
```
### List Graphs for given Hosts
To be able to add a Graph, the id of that very graph is required. Thus, a
`--list-graphs --host-id=[id]` option was implemented
```console
shell>php -q add_tree.php --list-graphs --host-id=1
Known Host Graphs: (id, name, template)
1 Localhost - Memory Usage Linux - Memory Usage
2 Localhost - Load Average Unix - Load Average
3 Localhost - Logged in Users Unix - Logged in Users
4 Localhost - Processes Unix - Processes
5 Localhost - Traffic - eth0 Interface - Traffic (bits/sec, 95th Percentile)
33 Localhost - Used Space - Memory Buffers Host MIB - Available Disk Space
34 Localhost - Used Space - Real Memory Host MIB - Available Disk Space
35 Localhost - Used Space - Swap Space Host MIB - Available Disk Space
36 Localhost - Used Space - / Host MIB - Available Disk Space
37 Localhost - Used Space - /sys Host MIB - Available Disk Space
38 Localhost - Used Space - /boot Host MIB - Available Disk Space
```
### Add a new Tree
Cacti comes with a single tree, named Default Tree. Console entry Graph
Trees is used to add more trees. With `add_tree.php`, you may now do so
from command line as well:
```console
shell>php -q add_tree.php --type=tree --name="Test Tree Add" --sort-method=manual
Tree Created - tree-id: (6)
```
Verify this from console, Graph Trees to find
```console
Default Tree
Test Tree Add
```
as expected.
### Add a new Header Node to a Tree
Now, that a new tree has been created, you may want to add a new header to that
very tree. Use
```console
shell>php -q add_tree.php --type=node --node-type=header --tree-id=6 --name="Header Test"
Added Node node-id: (21)
```
You will want to save the id returned if willing to add further nodes to
exactly this new Header Node
Please note that it is currently not possible to add another header with
the same options even if this is possible from console
But it is possible to add a subheader to an already defined header. Even
in this case, the `name` has to be unique
```console
shell>php -q add_tree.php --type=node --node-type=header --tree-id=6 --parent-node=21 --name="SubHeader Test"
Added Node node-id: (22)
```
### Add a new Host Node to a Tree
We will distinguish several options adding a host to a tree. First, let's
add a Host directly to a tree. For this example, we use the tree id
returned from adding our own `Test Tree Add` known with `id=6`
```console
shell>php -q add_tree.php --type=node --node-type=host --tree-id=6 --host-id=1
Added Node node-id: (23)
```
As no `--parent-node` was given, this host is directly added to the tree
itself. If you wish to add a host to a (sub)header specify as follows
```console
shell>php -q add_tree.php --type=node --node-type=host --tree-id=6 --parent-node=21 --host-id=1
Added Node node-id: (24)
```
Both example come without a `--host-group-style` option. For those cases,
`Graph Template` host group style is default. Here's an example for
providing a host group option of `Data Query Index` instead
```console
shell>php -q add_tree.php --type=node --node-type=host --tree-id=6 --parent-node=22 --host-id=1 --host-group-style=2
Added Node node-id: (25)
```
### Add a new Graph Node to a Tree
Like above, instead of hosts it is possible to add a single graph to a
tree or a (sub)header of any tree. Of course, you again will require the
`id` of the tree and optionally of the `header`. This results in
```console
shell>php -q add_tree.php --type=node --node-type=graph --tree-id=6 --graph-id=5
Added Node node-id: (26)
```
Like above, this graph now was added directly to the tree itself. To add
a graph to a header, proceed as follows
```console
shell>php -q add_tree.php --type=node --node-type=graph --tree-id=6 --parent-node=21 --graph-id=5
Added Node node-id: (27)
```
In both cases, no explicit `--rra-id` was given. This will default to the
Daily (5 Minute Average). Specify any other `--rra-id` as given
```console
shell>php -q add_tree.php --type=node --node-type=graph --tree-id=6 --parent-node=21 --graph-id=1 --rra-id=4
Added Node node-id: (28)
```
to provide the `--rra-id` for a rra of Yearly (1 Day Average).
## Add Graph Permissions
This script is used to specify special graph permissions to users. The
list of parameters is displayed as usual when calling the script with the
parameter `--help`
```console
shell>php -q add_perms.php --help
Add Permissions Script 1.0, Copyright 2004-2018 - The Cacti Group
A simple command line utility to add permissions to tree items in Cacti
usage: add_perms.php [ --user-id=[ID] ]
--item-type=[graph|tree|host|graph_template]
--item-id [--quiet]
Where item-id is the id of the object of type item-type
List Options:
--list-users
--list-trees
--list-graph-templates
--list-graphs --host-id=[ID]
```
### List Users
The list of users is retrieved by calling the script with the parameter
`--list-users`. It goes like
```console
shell>php -q add_perms.php --list-users
Known Users:
id username full_name
1 admin Administrator
3 guest Guest Account
```
### List Trees who accept permissions
The list of trees is retrieved by calling the script with the parameter
`--list-trees`. It goes like
```console
shell>php -q add_perms.php --list-trees
Known Trees:
id sort method name
1 Manual Ordering (No Sorting) Default Tree
```
### List Graph Templates
The list of available graph templates is retrieved by calling the script with
the parameter `--list-graph-templates`. It goes like
```console
shell>php -q add_perms.php --list-graph-templates
Known Graph Templates:(id, name)
2 Interface - Traffic (bits/sec)
3 ucd/net - Available Disk Space
4 ucd/net - CPU Usage
5 Karlnet - Wireless Levels
6 Karlnet - Wireless Transmissions
7 Unix - Ping Latency
8 Unix - Processes
9 Unix - Load Average
...
```
### List Graphs for given Hosts where permissions can be set
To be able to add a permissions to a specific Graph, the id of that very graph
is required. Thus, a `--list-graphs --host-id=[id]` option was implemented
```console
shell>php -q add_perms.php --list-graphs --host-id=1
Known Host Graphs: (id, name, template)
1 Localhost - Memory Usage Linux - Memory Usage
2 Localhost - Load Average Unix - Load Average
3 Localhost - Logged in Users Unix - Logged in Users
4 Localhost - Processes Unix - Processes
5 Localhost - Traffic - eth0 Interface - Traffic (bits/sec, 95th Percentile)
33 Localhost - Used Space - Memory Buffers Host MIB - Available Disk Space
34 Localhost - Used Space - Real Memory Host MIB - Available Disk Space
35 Localhost - Used Space - Swap Space Host MIB - Available Disk Space
36 Localhost - Used Space - / Host MIB - Available Disk Space
37 Localhost - Used Space - /sys Host MIB - Available Disk Space
38 Localhost - Used Space - /boot Host MIB - Available Disk Space
```
### Add Graph Permissions to specific Users
There are various ways to define graph permissions to specific users.
First, we will add graph permissions for a given host. This is done using
the parameter `--item-type=host` as follows
```console
shell>php -q add_perms.php --user-id=4 --item-type=host --item-id=1
```
`--user-id=4` must specify an existing users. Else, an error message will
be printed. As `--item-type=host` is given, `--item-id=1` must specify a
valid host. Again, if no host with this specific id exists, an error
message will be printed. No output is produced on successful operations.
Next, we will add graph permissions for a given tree. This is done using
the parameter `--item-type=tree` as follows
```console
shell>php -q add_perms.php --user-id=4 --item-type=tree --item-id=1
```
`--user-id=4` must specify an existing users. Else, an error message will
be printed. As `--item-type=tree` is given, `--item-id=1` must specify a
valid tree (the Default Tree in this case). Again, if no tree with this
specific id exists, an error message will be printed. No output is
produced on successful operations.
Adding graph permissions for a given graph template is done using the
parameter `--item-type=graph_template` as follows
```console
shell>php -q add_perms.php --user-id=4 --item-type=graph_template --item-id=25
```
`--user-id=4` must specify an existing users. Else, an error message will
be printed. As `--item-type=graph_template` is given, `--item-id=1` must
specify a valid graph_template (the Interface - Traffic (bytes/sec) in
this case). Again, if no graph template with this specific id exists, an
error message will be printed. No output is produced on successful
operations.
Last but not least we add graph permissions for a given graph by using
the parameter `--item-type=graph` as follows
```console
shell>php -q add_perms.php --user-id=4 --item-type=graph --item-id=8
```
`--user-id=4` must specify an existing users. Else, an error message will
be printed. As `--item-type=graph` is given, `--item-id=1` must specify a
valid graph. Again, if no graph template with this specific id exists, an
error message will be printed. No output is produced on successful
operations.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Contributing-Translations.md 0000664 0000000 0000000 00000007331 14124124457 0023553 0 ustar 00root root 0000000 0000000 # Creating Translations
## Internationalization of Cacti and its Plugins
If you wish to help with the development of translations of Cacti from English
to other languages, the Cacti Group has simplified the process for you.
You simply have to goto the following Web Site and create an account.
[Cacti Translation Site](https://translate.cacti.net). From there, you
can simply select what you want translated, and the push the "translate"
button on your language of choice, and the beauty of the translation is
that if the string that you tranlate is in another plugin, it can also
be automatically translated at the same time.
If you make a change to the translations, they are automatically committed
back to GitHub programatically. To install the new language strings,
you simply have to update the `locales` directory from the latest
GitHub branch that you were translating.
The `locales` directory has two separate subdirectories. They are:
```console
# ls -1 locales/
LC_MESSAGES
po
```
The LC_MESSAGES includes the compiled language files, and the po
directory includes not only the base Cacti translation file
`cacti.pot`, but all currently supported languages as well.
## Pull Requests
If you are making changes to the core Cacti code that involve new
strings to be translated, you have to ensure that your Pull Request
includes an updated `cacti.pot` file. To update the `cacti.pot`
file, you simply open a shell and change to the `locales`
directory and run the script `build_gettext.sh`. It will scan
the Cacti source code for all strings to be internationalized
and update the `cacti.pot` file.
If you include the updated file in your pull request, it will
keep the development engine running smooth.
## Translating using other tools
You may use other tools to Translate Cacti as well. One popular
tool is PO Editor, you can download it here:
[Poedit Pro](https://poedit.net/pro). The tool does work well and also run
machine translations for you at an added cost.
If you choose to use that route, you will need to still have a Cacti Translation
account. From there, you can upload your modified `language.po` files into
the interface directly. See the Weblate documentation on how to upload your
modified `language.po` files.
4. Once Poedit is installed, open it, and select File -> New from POT/PO file,
and select the cacti.pot file. When you click 'Open', it will ask you for
what language you are translating to. Cacti uses the dual syntax of
Language (Country). So, for French, you would select 'French (France)'.
5. Once you have done that, you can start your translation. You will select
each phrase one at a time, and enter in the translation in your language.
6. You should save your work often.
7. You can test your work on a test installation. Upload both .mo and .po files
to your test installation and change your user profile to use the language
you have just updated.
8. Cacti and its plugins get updates very often. To make sure the translations
are up to date, the translator should download the latest version and run
`build_gettext.sh` to create an up-to-date version of cacti.pot.
## Editing PO Files
The PO Editor will create both a PO and MO file every time you save the file.
The final name of the file will have to be changed to Cacti's standard naming.
For example, Poedit saves the file from the example above as `fr_FR.po`, but
Cacti will need these files name in hyphenated format, so: `fr_FR.po`, becomes
`fr-FR.po`. Make that note especially if you are starting a new language.
## Considerations
As Cacti is GPL2.0+, you acknowledge, by sigining up to the Cacti Weblate
site, that your contributions will be GPL2.0+ as well.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Contributing.md 0000664 0000000 0000000 00000004431 14124124457 0021072 0 ustar 00root root 0000000 0000000 # Contributing
If you wish to contribute to Cacti, the process is very easy. The first step
is to register for a GitHub account. Once you have a GitHub account, you then
need to learn about their community guidelines and familiarize yourself with
how to create a pull request. Pull requests are how we accept submissions from
the community for Code and Documentation.
Pull requests are always created against the **develop** branch, unless
otherwise instructed. Detailed guide on how to create Pull Requests on GitHub
under [Standards-Patch-Creation](Standards-Patch-Creation.md) section.
## Code Contributions
There are a few key points. First, if you want a feature, or find an issue,
and the forums are leading you to GitHub, create an Issue, this issue can be
tagged either an enhancement or a bug. Regardless of what it is, if you think
you can create a fix for that, prepare a pull request with your changes.
When your code is submitted, basic checks are performed to ensure that the code
is runnable but this does not guarantee that it will work. Please ensure that
you have been able to test your code before submitting a fix.
In addition to testing, please try to keep your code to Cacti's standards:
- [Code](Standards-Code-Formatting.md)
- [File System Layout](Standards-FileSystem-Layout.md)
- [SQL styling](Standards-SQL.md)
and
- [Security](Standards-Security.md)
You can view all the repositories of code that Cacti publicly shares on GitHub
at this [link](https://github.com/Cacti), or to go specifically to the [Cacti
source code](https://github.com/Cacti/cacti), [issue
tracker](https://github.com/Cacti/cacti/issues), and [internal
Wiki](https://github.com/Cacti/cacti/wiki)
## Documentation Contributions
As with Code contributions, if you wish to enhance or correct an issue with the
current documentation, create an issue with the details and then link the Pull
Request to it.
Unlike the various standards for coding depending on the type of code you are
attempting to contribute, there is only one set of [Documentation
Standards](Standards-Documentation.md) at this time. Please try to ensure that
your code confirms to this, as there are strict checks in place which will fail
your submission if it fails these standards.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Collectors.md 0000664 0000000 0000000 00000014127 14124124457 0021406 0 ustar 00root root 0000000 0000000 # Data Collectors
## Data Collector Background
Cacti can support from one to many **Data Collectors**. There are two types
of **Data Collectors** they are:
- **Main Data Collector** - This is essentially your core Cacti server
and database. The **Main Data Collector** is also referred to as
the **Primary Server**.
- **Remote Data Collector** - These Data Collectors are located in
distant locations, or where reaching devices is blocked due to
firewall or security policies. The **Remote Data Collectors** are
also referred to as **Remote Pollers**.
Due to the design of the Cacti **Remote Data Collector**, somone at the
remote site, can actually login to that **Data Collector** and interact
with it as if their **Data Collector** was the **Main Data Collector**.
Additionally, if for some reason the **Main Data Collector** becomes
unavailable due to a WAN outage for example, the data for the **Devices**
it manages will be cached locally until such time as the
**Main Data Collector** is reachable again.
Once the **Main Data Collector** becomes reachable, the **Remote Data Collector**
will flush it cache back to the **Main Data Collector** and the system
will normalize. Therefore, this is generally considered to be a more
Highly Available (HA) design.
A good Enterprise Architecture for Cacti would include three **Main Data Collectors**
which cactid systemd service was managed by keepalived, using GlusterFS as
fully replicated File system for the Web Server, the logs, and the RRDfiles
using MariaDB Galera as the fully fault tolerant database server.
Then, either using keepalived to a load balancer, you could load balance
the connections accross all three **Main Data Collectors**, using the
MariaDB Galera database to maintain login session data. There are many
good articles on setting up and using MariaDB Galera along with HAProxy
or load balancers from Citrix and others to direct read and write traffic
to the correct Galera instance server. The bottom line is that Cacti
provides the opportunity to have a Highly Available (HA) setup today.
That HA setup will not be covered in this chapter, but may be included
at a later date.
When using multiple **Data Collectors**, Cacti requires the use of the
`boost` module, which is now included in the main Cacti package. Therefore if
you are planning on deploying multiple **Data Collectors**, you should become
familiar with its use and why it is critical to a HA design.
In order for a **Remote Data Collector** to work with a **Main Data Collector**
the **Remote Data Collector** must be able to talk to the **Main Data Collector**
over both https and the MySQL protocol in a bidirectional fashion. Therefore,
there are only two ports that are required to be open in order to fully
leverage the multiple **Data Collector** architecture in Cacti.
## Data Collector User Interface
The image below shows the current online collector (aka pollers). On this page,
we can see the current, average, and max data collection times, the
**Data Collector** processes and threads used, the number of **Devices** as well
as what those **Devices** are polling. The Actions drop-down allows your to
Enable, Disable, and Delete **Remote Data Collectors**. There is also a
`Full Sync` option there. The `Full Sync` option will replicate key Cacti
tables to the selected **Remote Data Collectors** for things like authentication,
global settings, etc.
In the current Cacti design, you should not have to perform a `Full Sync`
very often. It would mainly be used to push the user database and global
settings to the remotes, after an outage if there were database changes
during that outage.
The **Main Data Collector** resides on the central Cacti server. It also
serves as the master **Data Collector** performing key maintenance operations
for the entire system.
In the edit page below, you can see what options are available when editing the
**Main Data Collector**. It is important the the hostname used is resolvable
by the **Remote Data Collectors**.
When editing the **Remote Data Collector** in the images below, you can see that
it shares many of the settings of the **Main Data Collector** with the addition
of a `TimeZone` setting and MySQL/MariaDB credentials and a `Test Connection`
button. Generally, these setting are only use during the initial setup
of Cacti, and afterwards for diagnostics only.
## Setup Main Data Collector to accept connections Remotes
We will need to make some config changes to the MySQL configuration to allow
the **Remote Data Collector** to talk to the **Main Data Collector**.
```console
mysql -u root mysql -e "GRANT ALL ON cacti.* TO cactidb@ IDENTIFIED BY 'password';"
mysql -u root mysql -e "GRANT SELECT ON mysql.time_zone_name TO cacti@ IDENTIFIED BY 'password';"
```
Next setup the **Remote Data Collectors** config.php located in
`/include/config.php` with the remote database details and credentials.
Generally, you will not have to do this as part of the direct maintenance of the
**Remote Data Collector**, the **Remote Data Collector** install process will force
you to take these steps to complete the install. However, it's provided here for
reference so that you understand the process.
```console
#$rdatabase_type = 'mysql';
#$rdatabase_default = 'cacti';
#$rdatabase_hostname = 'localhost'; <<< IP/Hostname of main server
#$rdatabase_username = 'cactiuser';
#$rdatabase_password = 'cactiuser';
#$rdatabase_port = '3306';
#$rdatabase_retries = 5;
#$rdatabase_ssl = false;
#$rdatabase_ssl_key = '';
#$rdatabase_ssl_cert = '';
#$rdatabase_ssl_ca = '';
```
You will now need to install Cacti on the remote server selecting the
**New Remote Poller** install option as shown below.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Debug.md 0000664 0000000 0000000 00000003336 14124124457 0020323 0 ustar 00root root 0000000 0000000 # Data Source Debugging
If you are having issues with blank graphs and have done the basic checks such
as permissions the Data source debug tool can help troubleshoot what
information is coming into Cacti.
The debug tool will check the data source, graphs and permissions along incoming
data and graph settings, such as step count, to ensure the definition matches
the profile of the data source amongst other things.
The tool allows you to run a debug on one or many data source. To request debug
information, tick all applicable data sources you require information on, then
select 'Run Check' in the actions drop down list. This will put all of the
selected data sources into debug mode.
For a single data source, you can click the data source name which will also
put it into debug mode.
You can see the status of each data source along with all of the checks run
against it. Successful checks show a green checkmark, whilst failed checks shows
a red X. Depending on the issue a recommendation will be provided for a failed
check.
A summary of the checks as well as the properties of the data source
can be displayed by clicking on the data source name. This is useful
for a single page view of the data source and graph details.
This page also shows what the last values where when last polled. This is also
useful for troubleshooting as if the data comes in out of range of your Data
Source template, or Graph template, this could point you into the right direction.
--- Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Input-Methods.md 0000664 0000000 0000000 00000020400 14124124457 0021764 0 ustar 00root root 0000000 0000000 # Data Input Methods
Data Input Methods allow Cacti to retrieve data to insert into RRDfiles based
upon a mapping controlled by **Data Templates** and their corresponding **Data
Sources**. These resulting **Data Templates** and **Data Sources** can then be
used to create **Graph Templates** and **Graphs**.
Cacti includes a number of build in **Data Input Methods** for **SNMP** data and
for **Script**, **Script Server** and **SNMP Data Queries**.
Outside of the built in **Data Input Methods**, the Cacti Administrator can
create virtually any **Data Input Method** based upon a **Script**, or a PHP
**Script Server** script. The **Script** based **Data Input Method** allows
Cacti to virtually collect data from anywhere, though the built in **SNMP** and
**Script Server** methods provide the greatest scalability in Cacti. Both
**Data Queries**, and PHP **Script Server** topics will be covered in later
sections of the documentation.
## Creating a Data Input Method
To create a new **Data Input Method**, from the Cacti Console, select **Data
Collection > Data Input Methods**. Once on that screen, click the plus (+) glyph
on the right which will allow you to add a new **Data Input Method**. You will
be presented with a few fields to populate on the following screen.
###### Table 11-1. Field Description: Data Input Methods
Name | Description
--- | ---
Name | Give the data query a name that you will use to identify it
Input Type | Select the type of **Data Input Method** you are trying to create
Input String | This field is only used when the Input Type is set to **Script/Command**
The `Name` specified will be used throughout Cacti to identify the human
readable name given to the **Data Input Method**. Careful consideration should
be made to help uniquely identify the **Data Source**. Having very similar
names can lead to confusion when utilizing them as your Cacti system grows.
Valid options for `Input Type` are **Script/Command**, and **Script Server**.
As mentioned previously, Cacti provides built in **Data Input Methods** for SNMP
data gathering and for SNMP, **Script**, and **Script Server** based **Data
Queries**. Though present in the Cacti database, they are hidden from user
view.
When the type is set to `Script/Command`, the `Input String` specifies the full
path to the script including any per **Data Source** input variables. **Data
Source** input variables must be enclosed in greater than and less than
characters. For instance, if you are passing an IP address to a script, your
input string might look something like: `/path/to/script.pl ` When the user
creates a **Data Source** based on this **Data Input Method**, they will be
prompted for an IP address to pass onto the script.
When you are finished filling in all necessary fields, click the Create button
to continue. Upon saving the new **Data Input Method**, you will be presented
with two new sections to complete. Those sections will instruct Cacti what to
pass to the Script, known as `Input Fields` otherwise known as `Input
Parameters` and how to handle the output data, which we refer to as `Output
Fields`.
The `Input Fields` box is used to define any fields that require information
from the user or from various data within the Cacti Database such as the
hostname, ip address, host id, etc. Any input fields referenced to in the input
string must be defined here.
The `Output Fields` box is used to define each field that you expect back from
the script and will be eventually stored in both the database and RRDfiles.
*All **Data Input Methods** must have at least one output field defined*, but
may have more than one depending on the type.
### Data Input Fields
To define a new field, click the plus sign (+) next to the input or output field
boxes. You will be presented with some or all of the fields below depending on
whether you are adding an input or output field.
###### Table 11-2. Field Description: Data Input Fields
Name | Description
--- | ---
Field/Field Name | You will be presented a drop down list of the unused braced input fields from the command
Friendly Name | Enter a more descriptive name for this field
Regular Expression Match (Input Only) | Enter a valid regular expression as to how to modify the output
Allow Empty Input (Input Only) | Can the input value of this field blank or not
Special Type Code (Input Only) | Pull the input data from the Cacti database and don't prompt the user for this input value
Update RRDfile (Output Only) | Checked if you intend this output data to be stored in an RRDfile
The `Field Name` must contain no spaces or other non-alphanumeric characters
(except '-' or '_').
If you want to enforce a certain regular expression pattern when the user enters
a value into `Regular Expression Match (Input Only)` for this Data Input Field,
it must follow POSIX syntax as it will be passed to PHP's preg() functions.
If the Data Input Field needs to reference another field internally, you can
enter this into the `Special Type Code`. For instance, if your field requires an
IP address from the user, you can enter 'management_ip' here and Cacti will fill
this field in with the current IP address of the selected host.
###### Table 11-3. Special Type Codes
Field Name | Description
--- | ---
hostname | The hostname
management_ip | The ip
snmp_community | The SNMP community
snmp_username | The SNMP username
snmp_password | The SNMP version
If you enable the `Update RRDfile`, Cacti will insert the return value from this
field into the RRDfile. This box needs to be checked for at least one output
field per data input source, but can be left blank to have Cacti store the value
only in the database instead.
When you are finished filling in all necessary fields, click the Create button
to continue. You will be redirected back to the **Data Input Method** edit page.
From here you can continue to add additional fields, or click Save on this
screen when finished.
## Making Your Scripts Work With Cacti
The simplest way to extend Cacti's data gathering functionality is through
external scripts. Cacti comes with a number of scripts out of the box which are
located in the `scripts/` directory. These scripts are used by the **Data Input
Methods** that are present in a new installation of Cacti.
To have Cacti call an external script to gather data you must create a new
**Data Input Method**, making sure to specify Script/Command for the Input Type
field. See the previous section, [Creating a Data Input
Method](data_input_methods.html) for more information about how to create a
**Data Input Method**. To gather data using your **Data Input Method**, Cacti
simply executes the shell command specified in the Input String field. Because
of this, you can have Cacti run any shell command or call any script which can
be written in almost any language.
What Cacti is concerned with is the output of the script. When you define your
**Data Input Method**, you are required to define one or more output fields. The
number of output fields that you define here is important to your script's
output. For a **Data Input Method** with only one output field, your script
should output its value in the following format:
```console
```
So if I wrote a script that outputs the number of running processes, its output
might look like the following:
```console
67
```
Data Input Methods with more than one output field are handled a bit differently
when writing scripts. Scripts that output more than one value should be
formatted like the following:
```console
:: ... :
```
If you wrote a script that outputs the 1, 5, and 10 minute load average of a
Unix machine and in Cacti named the output fields '1min', '5min', and '10min',
the output of the script should look like the following:
`1min:0.40 5min:0.32 10min:0.01`
One last thing to keep in mind when writing scripts for Cacti is that they will
be executed as the user the data gatherer runs as. Sometimes a script may work
correctly when executed as root, but fails due to permissions problems when
executed as a less privileged user.
## Walkthough
You can find a detailed example of how to create a complete Graph from
simple command output in the following example
[How To Create a Data Input Method](How-To-Create-Data-Input-Method.md).
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Profiles.md 0000664 0000000 0000000 00000004500 14124124457 0021052 0 ustar 00root root 0000000 0000000 # Data Source Profiles
This section will describe **Data Source Profiles** in Cacti.
The following values are for the disk usage per Data source for the respective
data profile
### 30 second polling
Daily 48kb
Weekly 43kb
Monthly 46kb
Yearly 140kb
### 1 minute polling
Daily 93kb / data source
Weekly 45kb / data source
Monthly 47kb /datasource
Yearly 140KB/data source
### 5 minute polling
Daily 19kb / data source
Weekly 22kb / data source
Monthly 25kb / data source
Yearly 26kb / data source
### Changing data profile averages
The Cacti GUI allows you to change the averages on a specific Data source
profile some setups require a higher resolution of data and you may want to
change the averaging to keep the most data this will come with a cost of storage
due to the bigger sized RRDfile
To do this follow these steps
#### Method 1 - New system without any hosts
1. Login to Cacti
2. Click on Presets >> Data Profiles
3. Select the profile you want to edit i.e 1 minute collection
4. Select the period which you want to edit i.e weekly
5. If you wish to change the average select the aggregate level for 1 minute
you will be able to go as low as 5 Minutes
6. You will need to edit the Rows amount to match the data retention you want
to set after this period the data will be averaged out to the monthly graph
7. Save config and generate graphs
#### Method 2 - Existing device(s) on system
This is a more data destructive route and it will depend on your situation. If
you have graphs already on cacti you will not be able to use Method 1. An option
if you do not care about the graphs is to either remove the graphs via the gui
or run the following script `/cli/php remove_graphs.php with the --all`
function.
This will REMOVE ALL THE GRAPHS and you can then follow the steps outlined in
Method 1 to change the profile how you like
### Data profile Rows Calculation
The rows calculation take in to account the following
Rows = Aggregate level * hours
Example
1 Minute aggregate level storing for 3 days ( 72 hours)
(Aggregate level)60 * 72 ( 72 hours) = 4,320
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Queries.md 0000664 0000000 0000000 00000065636 14124124457 0020725 0 ustar 00root root 0000000 0000000 # Data Queries
## Overview
Cacti **Data Queries** are not a replacement for **Data Input Methods** in Cacti.
Instead they provide an easy way to extend Data Input methods to interpret
multidimensional objects, or list data based upon an index, making the data
easier to graph. The most common use of a **Data Query within
Cacti is to retrieve a list of network interfaces via SNMP. If you want to
graph the traffic of a network interface, first Cacti must retrieve a list
of interfaces on the host. Second, Cacti can use that information to create
the necessary **Graphs** and **Data Sources**. **Data Queries** are only
concerned with the first step of the process, that is obtaining a list of
network interfaces and not creating the graphs/data sources for them. While
listing network interfaces is a common use for **Data Queries**, they also
have other uses such as listing partitions, processors, or even cards in
a router.
One requirement for any **Data Query** in Cacti, is that it has some unique value
that defines each row in the list. This concept follows that of a 'primary key'
in SQL, and makes sure that each row in the list can be uniquely referenced.
Examples of these index values are 'ifIndex' for SNMP network interfaces or the
device name for partitions.
There are three types of **Data queries** that you will see referred to
throughout Cacti. They are script queries, script server queries, and
SNMP queries. Script, Script Server and SNMP queries are virtually identical
in their functionality and only differ in how they obtain their information.
Script and Script Server queries will call an external command or script
and an SNMP query will make an SNMP call to retrieve a list of data.
## User Interface
Below, you can see Cacti's default **Data Queries** interface. From the
interface, you can see the Name, ID, Data Input Method, and other information
about the Data Query.
When you edit an existing Data Query, you will see an interface like the one
below. In that interface, you will note that there is an XML file path
included. The XML file is a key component of a Cacti **Data Query**. For
Script based **Data Queries**, there will also be a script that must be
called to gather information about the **Data Query**, the script name is
included in the XML file.
In this Interface, you can see the Name, Description, XML Path, and **Data
Input Method**. In the section below that, you have the
`Associated Graph Templates` section which includes all the various
**Graph Templates** that can be used for the **Data Query**.
Once a **Data Query** **Graph Template** is in use, it can not longer be
removed from Cacti. This feature is there to prevent **Graphs** from
becoming unrenderable if someone accidentally were to remove the **Graph
Template** association.
When you click on any of the `Associated Graph Template` name, you will be taken
to the interface below.
From here, you map the various matching **Data Template** RRDfile Data Source
names to Data Source names that exist in the XML file. There can be many
Data Source names in the XML file, but a Graph Template may only require a few
of them, which explains the reason for having the `Associated Data Templates`
section of the **Data Query**. To associate the XML field with the
**Data Templates** RRDfile Data Source, you simply select the correct
one, and then toggle on the checkbox to the right of the XML field
Data Source name.
Below the `Associated Data Templates`, you will find two sections which are
refered to as `Suggested Values` for both the **Data Source** and the
**Graph** names. When creating **Graphs** and their associated **Data Sources**
Cacti will use the first name in the `Suggested Values` pattern that fully
replaces all the tags that are identified by opening and closing vertical
bars. So, in the example above, when creating an Interface Graph, if
that Interface does not have an ifAlias, Cacti will likely use the second
`Suggested Value`, unless the interface does not have an IP Address, in which
case it will use the third `Suggested Value`.
Cacti also allows `Suggested Values`, to replace both **Graph** and **Data Source**
values, as in the case above, the "rrd_maximum" column is replaced by the
Network Interfaces maximum speed, otherwise known as the "ifSpeed" from an SNMP
perspective.
All data queries have two parts, the XML file and the definition within Cacti.
An XML file must be created for each query, that defines where each piece of
information is and how to retrieve it. This could be thought of as the actual
query. The second part is a definition within Cacti, which tells Cacti where to
find the XML file and associates the data query with one or more graph
templates.
## Creating a Data Query
Once you have created the XML file that defines your data query, you must add
the data query within Cacti. To do this you must click on Data Queries under the
Data Gathering heading, and select Add. You will be prompted for some basic
information about the data query, described in more detail below.
###### Table 12-1. Field Description: Data Queries
Name | Description
--- | ---
Name | Give the **Data Query** a name that you will use to identify it. This name will be used throughout Cacti when presented with a list of **Data Queries**.
Description (Optional) | Enter a more detailed description of the data query including the information it queries or additional requirements.
XML Path | Fill in the full path to the XML file that defines this query. You can optionally use the `path_cacti` variable that will be substituted with the full path to Cacti. On the next screen, Cacti will check to make sure that it can find the XML file.
Data Input Method | This is how you tell Cacti to handle the data it receives from the data query. Typically, you will select `Get SNMP Data (Indexed)` for an SNMP query and `Get Script Data (Indexed)` for a script query.
When you are finished filling in all necessary fields, click the Create button
to continue. You will be redirected back to the same page, but this time with
some additional information to fill in. If you receive a red warning that says
'XML File Does Not Exist', correct the value specified in the 'XML Path' field.
### Associated Graph Templates
Every data query must have at least one graph template associated with it, and
possibly more depending on the number of output fields specified in the XML
file. This is where you get to choose what kind of graphs to generate from this
query. For instance, the interface data query has multiple graph template
associations, used to graph traffic, errors, or packets. To add a new graph
template association, simply click Add at the right of the Associated Graph
Templates box. You will be presented with a few fields to fill in:
###### Table 12-2. Field Description: Associated Graph Templates
Name | Description
--- | ---
Name | Give a name describing what kind of data you are trying to represent or graph. When the user creates a graph using this data query, they will see a list of graph template associations that they will have to choose from.
Graph Template | Choose the actual graph template that you want to make the association with.
When you are finished filling in these fields, click the Create button. You
will be redirected back to the same page with some additional information to
fill in. Cacti will make a list of each **Data Template** referenced to in your
selected **Graph Template** and display them under the `Associated Data Templates`
box. As previously mentioned, for each **Data Source** item listed, you
must selected the **Data Query** output field that corresponds with it.
*Do not forget to check the checkbox to the right of each selection, or your
settings will not be saved.*
The `Suggested Values` form provides you a way to control field values of
**Data Sources** and **Graphs** created using the **Data Query**. If you
specify multiple `Suggested Values` for the same field, Cacti will evaluate
them in order which you can control using the up or down arrow icons.
For more information about valid field names and variables, read the
section on `Suggested Values`.
When you are finished filling in all necessary fields on this form, click the
Save button to return to the data queries edit screen. Repeat the steps under
this heading as many times as necessary to represent all data in your XML file.
When you are finished with this, you should be ready to start adding your data
query to hosts.
### SNMP Query XML Syntax
```xml
Get SNMP InterfacesQueries a host for a list of monitorable interfaces.1.3.x.x.x.1.3.6.1.2.1.2.2.1.1OID/REGEXP:.*.([0-9]{1,3}.[0-9]{1,3})$.1.3.6.1.2.1.2.1.0ifDescr:ifName:ifIndexnumeric|chosen_order_field|Indexwalkvalueinput.1.3.6.1.2.1.2.2.1.1
```
###### Table 12-3. SNMP Query XML Settings Reference
Field | Description
--- | ---
name | (Optional) You can enter a "friendly name" for the SNMP Query here. It will not be used by Cacti, and is for identification only.
description | (Optional) You can enter a description for the SNMP Query here. It will not be used by Cacti, and is for identification only.
oid_uptime | If you have another OID that contains ticks (time), say for example a Java VM. Then, you can create a data query that specifies an alternate uptime OID. To implement this for a data query, simply add the oid_uptime XML parameter to your XML file. Then, if you select your re-index method to be Uptime Goes Backward, Cacti will use that OID to detect whether it is time to re-index the host instead of the standard SNMP OID for uptime.
oid_index | Every SNMP Query must have an OID that represents the index values for the query when walked. As described above, any data query in Cacti must contain a field that uniquely identifies each row returned by the query. In the example above, the oid_index points to the OID of ifIndex in the interface MIB. Note: Cacti is able to parse unique indexes from the OID itself. While the regular expression used for parsing the value from the OID is defined below, you must still specify an OID that can be walked by Cacti in order to obtain the list of OID's. Any OID defined for one of your input fields should work in this case. The values returned from the snmpwalk walk will be completely disregarded.
non_unique | If set to true, Cacti will allow the Data Query index to be non-unique, and it will not attempt to change the index_order if for some reason, the chosen index field is not unique.
oid_index_parse | This field should only be used if you are trying to parse the unique index from the OID itself. If this field is defined, to obtain a list of indexes, Cacti walks the OID provided in the oid_index field above. It then applies the regular expression provided in this field to the list of OID's that are returned. The matched substrings that remain become the list of indexes for this SNMP Query.
oid_num_indexes | An OID that can be queried to determine the total number of available indexes. If specified, this will be used to determine when to automatically re-cache this SNMP Query when it is attached to a device.
index_order | Cacti will attempt to find the best field to index off of based on whether each row in the query is unique and non-null. If specified, Cacti will perform this check on the fields listed here in the order specified. Only input fields can be specified and multiple fields should be delimited with a colon.
index_transient | If set to 'true', this field instructs Cacti not to stop attempting to Graph an index if it disappears from the host cache as a result of a re-index. This setting is for indexes that come and go, for example PPPoE statitics or user statistics which appear when a user log's in, but disappear a few hours after the connection is terminated.
index_order_type | For sorting purposes, specify whether the index is numeric or alphanumeric. numeric: The indexes in this SNMP Query are to be sorted numerically (ie. 1,2,3,10,20,31) alphabetic: The indexes in this SNMP Query are to be sorted alphabetically (1,10,2,20,3,31).
index_title_format | Specify the title format to use when representing an index to the user. Any input field name can be used as a variable if enclosed in pipes (|). The variable `|chosen_order_field|` will be substituted with the field chosen by Cacti to index off of (see index_order above).
###### Table 12-4. SNMP Query XML Field Settings Reference
Each field contained within the SNMP Query must be defined under the field tag
as show in the example above. In addition, each defined field in the SNMP Query
must have a unique name given to it. Do not use spaces or any non-alphanumeric
characters, this name must be identifiable within Cacti.
Field | Description
--- | ---
name | Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field.
method | Tell Cacti how you want it to gather SNMP information for this field. get: The `get` method performs an snmpget for the OID specified for this field appended by the index values derived from `/`. walk: The `walk` method does a walk of the OID specified for this field. If all OIDs belong to the same SNMP table, both methods will return the same values, even though the 'walk' method is typically more efficient.
source | When Cacti obtains a list for this field, you need to tell it how to derive its value for each row. value: The 'value' option simply returns the result of the snmpget for each row. **OID/REGEXP** (regexp_match): The **OID/REGEXP** modifier can be used when you need to use a POSIX-based regular expression to derive the value from the OID. The most common example of this is to retrieve the IP address of an interface, and can be seen in the 'interface.xml' file. **VALUE/REGEXP** (regexp_match): The **VALUE/REGEXP** modifier can be used to parse the value based on a regular expression, returning the first match. index: Simply use the value of the index for this row as the value. If the index is being parsed from the OID using the oid_index_parse field, you must specify index here. Omit the `...` field, then. **OID2HEX/REGEXP** (regexp_match): The **OID2HEX/REGEXP** modifier can be used to parse the OID to extract IPv6 addresses. This is useful for input type fields. It also supports the 'oid_index_parse' expression as well.
direction | input: Input values are the "known" values that you will use to derive the output values, this is where the "query" part of SNMP query comes in. When you create a graph based on an SNMP query, Cacti will prompt you to choose the input value to base the graph on. output: Output values are "unknown" values that are returned from the script. An SNMP query may return multiple statistics for a single index. For instance, a single interface could return bytes/sec in, errors, packets/sec, etc. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed.
oid | You must specify the actual OID that corresponds with the field. Each value for this field can be obtained by doing an snmpget on `oid.(each)snmpindex`.
oid_rewrite_pattern | You can specifv and **OID/REGEXP** string which will be replaced by the oid_rewrite_replacement string if found.
oid_rewrite_replacement | You must specify the actual OID that corresponds with the field. Each value for this field can be obtained by doing an snmpget on `oid.(each)snmpindex`.
oid_suffix | The suffix, if specified will be appended to the each oid from the walk or get response, prior to the oid_rewrite_pattern to oid_rewrite_replace regular expression replace. If the method is get, Cacti will issue an snmpget to obtain the resulting data.
rewrite_index | Modifies the snmp values using the rewrite_index expression.
output_format | Determines the output format of the column values. Options are 'ascii', 'hex'. If not specified, Cacti will allow SNMP to 'guess' the output format.
## Script Query XML Syntax
```xml
Get Unix Mounted PartitionsQueries a list of mounted partitions on a unix-based host with the 'df' command.perl |path_cacti|/scripts/query_unix_partitions.plindexquerygetnum_indexes:dskDevice:dskMountalphabetic|chosen_order_field|Device Nameinputdevice
```
###### Table 12-5. Script Query XML Settings
Field | Description
--- | ---
name | (Optional) You can enter a "friendly name" for the script query here. It will not be used by Cacti, and is for identification only.
description | (Optional) You can enter a description for the script query here. It will not be used by Cacti, and is for identification only.
script_path | Enter the complete path to the script or executable that is going to handle your script query. When in doubt, specify the pull path to all binaries referenced in this path, the query may not execute otherwise.
arg_index | Enter the argument that is to be passed to the script to retrieve a list of indexes.
arg_query | Enter the argument that is to be passed to the script to retrieve a list of values given a field name.
arg_get | Enter the argument that is to be passed to the script to retrieve a single value given a field name and index value.
arg_num_indexes | Enter the argument that is to be passed to the script to determine the total number of available indexes. If specified, this will be used to determine when to automatically re-cache this script query when it is attached to a device.
output_delimeter | Enter the one character delimiter that will be used to separate output values. This is only used when you "query" the script in which case it outputs 'index(delimiter)value'.
index_order | Cacti will attempt to find the best field to index off of based on whether each row in the query is unique and non-null. If specified, Cacti will perform this check on the fields listed here in the order specified. Only input fields can be specified and multiple fields should be delimited with a comma.
index_transient | If set to 'true', this field instructs Cacti not to stop attempting to Graph an index if it disappears from the host cache as a result of a re-index. This setting is for indexes that come and go, for example PPPoE statitics or user statistics which appear when a user log's in, but disappear a few hours after the connection is terminated.
index_order_type | For sorting purposes, specify whether the index is numeric or alphanumeric. numeric: The indexes in this script query are to be sorted numerically (ie. 1,2,3,10,20,31) alphabetic: The indexes in this script query are to be sorted alphabetically (1,10,2,20,3,31).
index_title_format | Specify the title format to use when representing an index to the user. Any input field name can be used as a variable if enclosed in pipes (|). The variable |chosen_order_field| will be substituted with the field chosen by Cacti to index off of (see index_order above).
###### Table 12-6. Script Query XML Field Settings
Each field contained within the Script Query must be defined under the field tag
as show in the example above. In addition, each defined field in the Script
Query must have a unique name given to it. Do not use spaces or any
non-alphanumeric characters, this name must be identifiable within Cacti.
Field | Description
--- | ---
name | Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field.
direction | input: Input values are the "known" values that you will use to derive the output values, this is where the "query" part of script query comes in. When you create a graph based on a script query, Cacti will prompt you to choose the input value to base the graph on. output: Output values are "unknown" values that are returned from the script. A script query may return multiple statistics for a single index. For instance, a single partition could return free disk space, total disk space, fragmentation percentage, etc. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed.
query_name | Enter the name that Cacti must use when asking the script for information about this field. For instance, the following should return values: '(script_name) query (query_name)'.
## Script Server XML Syntax
```xml
Get Host MIB CPUs|path_cacti|/scripts/ss_host_cpu.phpss_host_cpuphp|host_hostname| |host_id| |host_snmp_version|:|host_snmp_port|:|host_snmp_timeout|:|host_ping_retries|:|host_max_oids|:|host_snmp_community|:|host_snmp_username|:|host_snmp_password|:|host_snmp_auth_protocol|:|host_snmp_priv_passphrase|:|host_snmp_priv_protocol|:|host_snmp_context|indexquerygetnum_indexes!hrProcessorFrwIDnumericCPU#|chosen_order_field|Processor Index NumberinputindexProcessor Usageoutputusage
```
###### Table 12-7. Script Server XML Settings
Field | Description
--- | ---
name | (Optional) You can enter a "friendly name" for the script query here. It will not be used by Cacti, and is for identification only.
description | (Optional) You can enter a description for the script query here. It will not be used by Cacti, and is for identification only.
script_path | Enter the complete path to the script or executable that is going to handle your script query. When in doubt, specify the pull path to all binaries referenced in this path, the query may not execute otherwise.
script_function | The function within the script in the case where the script can be used for multiple data collection functions. Most script server scripts are associated with only one Data Query, but it's possible to have one script perform the collection for multiple Data Queries.
arg_prepend | A list of device variables from the host to prepend after the script function when calling the script. This information can be used to identify the device that is being monitored or pass certain device information to the script.
arg_index | Enter the argument that is to be passed to the script to retrieve a list of indexes.
arg_query | Enter the argument that is to be passed to the script to retrieve a list of values given a field name.
arg_get | Enter the argument that is to be passed to the script to retrieve a single value given a field name and index value.
arg_num_indexes | Enter the argument that is to be passed to the script to determine the total number of available indexes. If specified, this will be used to determine when to automatically re-cache this script query when it is attached to a device.
output_delimeter | Enter the one character delimiter that will be used to separate output values. This is only used when you "query" the script in which case it outputs 'index(delimiter)value'.
index_order | Cacti will attempt to find the best field to index off of based on whether each row in the query is unique and non-null. If specified, Cacti will perform this check on the fields listed here in the order specified. Only input fields can be specified and multiple fields should be delimited with a comma.
index_transient | If set to 'true', this field instructs Cacti not to stop attempting to Graph an index if it disappears from the host cache as a result of a re-index. This setting is for indexes that come and go, for example PPPoE statitics or user statistics which appear when a user log's in, but disappear a few hours after the connection is terminated.
index_order_type | For sorting purposes, specify whether the index is numeric or alphanumeric. numeric: The indexes in this script query are to be sorted numerically (ie. 1,2,3,10,20,31) alphabetic: The indexes in this script query are to be sorted alphabetically (1,10,2,20,3,31).
index_title_format | Specify the title format to use when representing an index to the user. Any input field name can be used as a variable if enclosed in pipes (|). The variable |chosen_order_field| will be substituted with the field chosen by Cacti to index off of (see index_order above).
###### Table 12-6. Script Server XML Field Settings
Each field contained within the Script Query must be defined under the field tag
as show in the example above. In addition, each defined field in the Script
Query must have a unique name given to it. Do not use spaces or any
non-alphanumeric characters, this name must be identifiable within Cacti.
Field | Description
--- | ---
name | Here you can specify a "friendly name" for the field. This name will be used by Cacti to help the user identify this field.
direction | input: Input values are the "known" values that you will use to derive the output values, this is where the "query" part of script query comes in. When you create a graph based on a script query, Cacti will prompt you to choose the input value to base the graph on. output: Output values are "unknown" values that are returned from the script. A script query may return multiple statistics for a single index. For instance, a single partition could return free disk space, total disk space, fragmentation percentage, etc. A rule of thumb is that input fields contain semi-static data that is not graphable, while the output fields contain the data that will be graphed.
query_name | Enter the name that Cacti must use when asking the script for information about this field. For instance, the following should return values: '(script_name) query (query_name)'.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Source-Templates.md 0000664 0000000 0000000 00000013012 14124124457 0022461 0 ustar 00root root 0000000 0000000 # Data Source Templates
Data sources serve an important role in Cacti data sources are data points
collected from the devices you monitor in Cacti.
Data sources take the data that has been collected by the poller.
The Data source then holds the value to be presented to the graph.
The Data source template is then associated with a graph template.
These data sources can be for example incoming traffic on an interface.
Cacti allows you to create data source templates to associate to data queries
the template allows you to describe what type of data Cacti should expect.
To create a Data source you will need to select the proper data input there are
several options but the most popular ones would be GET SNMP data or GET SNMP
data (indexed.)
You would use Get SNMP data (indexed) for interfaces for example as Cacti would
need to query the device to find the interface index. You would use Get SNMP
data and put in a single OID for an OID that won't change for example CPU usage
generally does not have an index and the OID won't change
You will also need to tell the template what the data source type is.
The most common ones being Gauge and Counter. These data types come from the
RRDtool its self here are the following supported data types and their uses
(Source https://oss.oetiker.ch/rrdtool/doc/rrdcreate.en.html)
GAUGE
is for things like temperatures or number of people in a room or the value of a RedHat share.
COUNTER
is for continuous incrementing counters like the ifInOctets counter in a router.
The COUNTER data source assumes that the counter never decreases, except when a counter overflows.
The update function takes the overflow into account. The counter is stored as a per-second rate.
When the counter overflows, RRDtool checks if the overflow happened at the 32bit or 64bit border
and acts accordingly by adding an appropriate value to the result.
DCOUNTER
the same as COUNTER, but for quantities expressed as double-precision floating point number.
Could be used to track quantities that increment by non-integer numbers, i.e. number of seconds that some routine has taken to run,
total weight processed by some technology equipment etc.
The only substantial difference is that DCOUNTER can either be upward counting or downward counting, but not both at the same time.
The current direction is detected automatically on the second non-undefined counter update and any further change in the direction is considered a reset.
The new direction is determined and locked in by the second update after reset and its difference to the value at reset.
DERIVE
will store the derivative of the line going from the last to the current value of the data source.
This can be useful for gauges, for example, to measure the rate of people entering or leaving a room.
Internally, derive works exactly like COUNTER but without overflow checks.
So if your counter does not reset at 32 or 64 bit you might want to use DERIVE and combine it with a MIN value of 0.
DDERIVE
the same as DERIVE, but for quantities expressed as double-precision floating point number.
NOTE on COUNTER vs DERIVE
by Don Baarda
If you cannot tolerate ever mistaking the occasional counter reset for a legitimate counter wrap,
and would prefer "Unknowns" for all legitimate counter wraps and resets, always use DERIVE with min=0.
Otherwise, using COUNTER with a suitable max will return correct values for all legitimate counter wraps,
mark some counter resets as "Unknown", but can mistake some counter resets for a legitimate counter wrap.
For a 5 minute step and 32-bit counter, the probability of mistaking a counter reset for a legitimate wrap is arguably about 0.8% per 1Mbps of maximum bandwidth.
Note that this equates to 80% for 100Mbps interfaces, so for high bandwidth interfaces and a 32bit counter, DERIVE with min=0 is probably preferable.
If you are using a 64bit counter, just about any max setting will eliminate the possibility of mistaking a reset for a counter wrap.
ABSOLUTE
is for counters which get reset upon reading. This is used for fast counters which tend to overflow.
So instead of reading them normally you reset them after every read to make sure you have a maximum time available before the next overflow.
Another usage is for things you count like number of messages since the last update.
COMPUTE
is for storing the result of a formula applied to other data sources in the RRD.
This data source is not supplied a value on update, but rather its Primary Data Points (PDPs) are computed from the PDPs of the data sources
according to the rpn-expression that defines the formula.
Consolidation functions are then applied normally to the PDPs of the COMPUTE data source (that is the rpn-expression is only applied to generate PDPs).
In database software, such data sets are referred to as "virtual" or "computed" columns.
You are also able to use Variables to set the name for the data source.
The avaliable Variables can be seen here
https://github.com/Cacti/documentation/blob/develop/Variables.md
What is also an important setting is the internal data source name.
This will be used to asociate the Data source with the Graph template.
so be sure to name is something that is recognizable.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Data-Sources.md 0000664 0000000 0000000 00000005464 14124124457 0020724 0 ustar 00root root 0000000 0000000 # Data Source Management
Data sources in Cacti are the points of data that Cacti will collect from a
device. The following are examples of different sources that can be utililised
for graphing, though is just the surface of what is achievable:
- Monitoring a device via ping will usually count as 1 data source.
- A 24 port switch and you poll the device via snmp and graph all of
the ports then there will be 24 data sources
> **Note**: if you add more graphs that base their data on the original
> **Data source** that would not count as another **Data Source** since
> it uses the already existing source.
For example, if you have a 24 port switch that you create an **In/Out Bits**
graph for each interface, and you then add the **In/Out Bits with 95th
Percential** for each interface, you would still only have 24 data sources.
Keeping on top of the amount of data sources you have is important as the more
data sources you have the more resources you will need to allocate
to your server.
You can see how many data sources are associated with a single device by going
to managment then clicking on devices.
You can also see the total amount of data sources by checking the poller stats
on the system. Click the log tab and filter by stats and lookout for the below
messege
```console
2019/05/24 17:21:11 - SYSTEM STATS: Time:9.5913 Method:spine Processes:2 Threads:2 Hosts:14 HostsPerProcess:7 DataSources:162 RRDsProcessed:117
```
This output tells us we have 162 data sources on the system.
### Storage considerations and datasources
The amount of data sources on your system has an impact on the amount of storage
you will need. You will also need to consider what rate you are polling your
devices. e.g. 1 minute or 5 Minute polls
Here is the approximate amount of storage you can expect to consume per data source
###### 30 second polling
Retention | File size
------------- |:-------------:
Daily | 48kb
Weekly | 43kb
Monthly | 46kb
Yearly | 140kb
###### 1 minute polling
Retention | File size
------------- |:-------------:
Daily | 93kb
Weekly | 45kb
Monthly | 47kb
Yearly | 140kb
###### 5 minute polling
Retention | File size
------------- |:-------------:
Daily | 19b
Weekly | 22kb
Monthly | 25kb
Yearly | 26kb
### Viewing all Data sources by device
You are able to check the data sources asociated to a specific device in the Console -> Managment -> Data sources
You can then search based on a device you may be interested in to view the Data sources in use
You can also view Orphaned data sources in this view by setting Orphaned from All to Orphaned
Orphaned data sources are where the graph has been deleted but the data source was not deleted
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Debugging.md 0000664 0000000 0000000 00000021411 14124124457 0020313 0 ustar 00root root 0000000 0000000 # Debugging
Cacti users sometimes complain about NaN's in their graphs. Unfortunately, there
are several reasons for this result. The following is a step-by-step procedure
recommended for debugging.
## Check Cacti Log File
Your cacti log file should be located at `/log/cacti.log`. If it is
not, see `Settings`, `Paths`. Check for this kind of error:
```console
SPINE: Host[...] DS[....] WARNING: SNMP timeout detected [500 ms], ignoring host '........'
```
For "reasonable" timeouts, this may be related to a snmpbulkwalk issue. To
change this, see `Settings`, `Poller` and lower the value for `The Maximum SNMP
OIDs Per SNMP Get Request`. Start at a value of 2 and increase it again, if the
poller starts working. (1 or less disables snmpbulkwalk) Some agent's don't have
the horsepower to deliver that many OIDs at a time. Therefore, we can reduce the
number for those older/under-powered devices.
## Check Basic Data Gathering
For scripts, run them as cactiuser from CLI to check basic functionality. E.g.
for a Perl script named `your-perl-script.pl` with parameters "p1 p2" under *nix
this would look like:
```sh
su - cactiuser
/full/path/to/perl your-perl-script.pl p1 p2
... (check output)
```
For SNMP, snmpget the _exact_ OID you're asking for, using same community string
and SNMP version as defined within cacti. For an OID of `.1.3.6.1.4.something`,
community string of `very-secret` and version 2 for target host `target-host`
this would look like
```sh
snmpget -c very-secret -v 2c target-host .1.3.6.1.4.something
.... (check output)
```
## Check Cacti's poller
First make sure that crontab always shows poller.php. This program will either
call cmd.php, the PHP based poller _or_ spine, the fast alternative, written in
C. Define the poller you're using at `Settings`, `Poller`. Spine has to be
implemented separately, it does not come with cacti by default.
Now, clear `./log/cacti.log` (or rename it to get a fresh start)
Then, change `Settings`, `Poller Logging Level` to DEBUG for _one_ polling
cycle. You may rename this log as well to avoid more stuff added to it with
subsequent polling cycles.
Now, find the host/data source in question. The `Host[]` is given
numerically, the `` being a specific number for that host. Find this ``
from the `Devices` menu when editing the host: The URL contains a string like
```console
id=
```
Check, whether the output is as expected. If not, check your script (e.g.
`/full/path/to/perl`). If OK, proceed to next step
This procedure may be replaced by running the poller manually for the failing
host only. To do so, you need the ``, again. If you're using cmd.php, set
the DEBUG logging level as defined above and run
```sh
php -q cmd.php
```
If you're using spine, you may override logging level when calling the poller:
```sh
./spine --verbosity=5
```
All output is printed to STDOUT in both cases. This procedure allows for
repeated tests without waiting for the next polling interval. And there's no
need to manually search for the failing host between hundreds of lines of
output.
## Check MySQL updating
In most cases, this step can be skipped. You may want to return to this step if
the next one fails (e.g. no rrdtool update to be found)
From debug log, find the MySQL update statement for that host concerning table
`poller_output`. On very rare occasions, this will fail. Copy that SQL statement
and paste it to a MySQL session started from CLI. This may as well be done from
some tool like phpMyAdmin. Check the SQL return code.
## Check RRDfile updating
Down in the same log, you should find some
```sh
rrdtool update --template ...
```
You should find exactly one update statement for each file.
RRDfiles should be created by the poller. If it does not create them, it will
not fill them either. If it does check your `Poller Cache` from Utilities and
search for your target. Does the query show up here?
## Check RRDfile ownership
If RRDfiles were created e.g. with root ownership, a poller running as
cactiuser will not be able to update those files
```sh
cd /var/www/html/cacti/rra
ls -l localhost*
-rw-r--r-- 1 root root 463824 May 31 12:40 localhost_load_1min_5.rrd
-rw-r--r-- 1 cactiuser cactiuser 155584 Jun 1 17:10 localhost_mem_buffers_3.rrd
-rw-r--r-- 1 cactiuser cactiuser 155584 Jun 1 17:10 localhost_mem_swap_4.rrd
-rw-r--r-- 1 cactiuser cactiuser 155584 Jun 1 17:10 localhost_proc_7.rrd
-rw-r--r-- 1 cactiuser cactiuser 155584 Jun 1 17:10 localhost_users_6.rrd
```
Run the following command to cure this problem
```sh
chown cactiuser:cactiuser *.rrd
```
## Check RRDfile numbers
You're perhaps wondering about this step, if the former was OK. But due to data
sources MINIMUM and MAXIMUM definitions, it is possible, that valid updates for
RRDfiles are suppressed, because MINIMUM was not reached or MAXIMUM was
exceeded.
Assuming, you've got some valid `rrdtool update` in step 3, perform a
```sh
rrdtool fetch AVERAGE
```
and look at the last 10-20 lines. If you find NaN's there, perform
```sh
rrdtool info
```
and check the `ds[...].min` and `ds[...].max` entries, e.g.
```sh
ds[loss].min = 0.0000000000e+00
ds[loss].max = 1.0000000000e+02
```
In this example, MINIMUM = 0 and MAXIMUM = 100. For a `ds.[...].type=GAUGE`
verify, that e.g. the number returned by the script does not exceed
`ds[...].MAX` (same holds for MINIMUM, respectively).
If you run into this, not only should you update the data source definition
within the Data Template, but also perform a:
```sh
rrdtool tune --maximum :
```
for all existing RRDfiles belonging to that Data Template.
At this step, it is wise to check `step` and `heartbeat` of the RRDfile as
well. For standard 300 seconds polling intervals (step=300), it is wise to set
`minimal_heartbeat` to 600 seconds. If a single update is missing and the next
one occurs in less than 600 seconds from the last one, RRDtool will interpolate
the missing update. Thus, gaps are "filled" automatically by interpolation. Be
aware of the fact, that this is no "real" data! Again, this must be done in the
Data Template itself and by using `rrdtool tune` for all existing RRDfiles of
this type.
## Check `rrdtool graph` statement
Last resort would be to check, that the correct data sources are used. Go to
`Graph Management` and select your Graph. Enable DEBUG Mode to find the whole
`rrdtool graph` statement. You should notice the `DEF` statements. They specify
the RRDfile and data source to be used. You may check, that all of them are as
wanted.
## Miscellaneous
Up to current cacti 0.8.6h, table `poller_output` may increase beyond reasonable
size.
This is commonly due to php.ini's memory settings of 8MB default. Change this to
at least 64 MB.
To check this, run the following SQL from MySQL CLI (or phpMyAdmin or the like)
```sql
select count(*) from poller_output;
```
If the result is huge, you may get rid of those stuff by
```sql
truncate table poller_output;
```
As of current SVN code for upcoming cacti 0.9, I saw measures were taken on both
issues (memory size, truncating poller_output).
## RPM Installation
Most rpm installations will setup the crontab entry now. If you've followed the
installation instructions to the letter (which you should always do ;-) ), you
may now have two poller running. That's not a good thing, though. Most rpm
installations will setup cron in `/etc/cron.d/cacti`
Now check all your crontab, especially `/etc/crontab` and crontab of users root
and cactiuser. Leave only one poller entry for all of them. Personally, I've
chosen `/etc/cron.d/cacti` to avoid problems when updating RPM's. Most often,
you won't remember this item when updating lots of RPM's, so I felt more secure
to put it here. And I've made some slight modifications, see
```sh
shell> vi /etc/cron.d/cacti
```
```ini
*/5 * * * * cactiuser /usr/bin/php -q /var/www/html/cacti/poller.php > /var/local/log/poller.log 2>&1
```
This will produce a file `/var/local/log/poller.log`, which includes some
additional informations from each poller's run, such as RRDtool errors. It
occupies only some few bytes and will be overwritten each time.
If you're using the crontab of user "cactiuser" instead, this will look like
```sh
shell> crontab -e -u cactiuser
```
```ini
*/5 * * * * /usr/bin/php -q /var/www/html/cacti/poller.php > /var/local/log/poller.log 2>&1
```
## Not NaN, but 0 (zero) values
Pay attention to custom scripts. It is required, that external commands called
from there are in the `$PATH` of the cactiuser running the poller. It is
therefor recommended to provide `/full/path/to/external/command`
User "criggie" reported an issue with running smartctl. It was complaining "you
are not root" so a quick `chmod +s` on the script fixed that problem.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Device-Rules.md 0000664 0000000 0000000 00000002475 14124124457 0020720 0 ustar 00root root 0000000 0000000 # Automation Device Rules
This section will describe **Device Rules** in Cacti.
Cacti Automation relies on create device Rules these rules help the automation
process figure out what type of device is being scanned. Based on the device
rule REGEX the automation engine can apply the appropriate template to the
device i.e if there is a REGEX for IOS. The automation engine may pick the
Cisco router template for the device.
Below you will be able to choose a REGEX that will help identify the device
the REGEX can be in any Perl supported format. You can select either to
match by system description i.e the device hostname or the system name
i.e Cisco.
An example regex for Cisco would be (Cisco Internetwork Operating System
Software|IOS) This matches based on the system name of the Cisco IOS software.
Using this info automation would apply the appropriate device template you
choose. If you see below we match for a system that matches Linux once a
device is found with that system name it is assigned the Net-SNMP device
template.
If the System/Device you are matching has a unique OID you can also match based
on that.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Device-Templates.md 0000664 0000000 0000000 00000004422 14124124457 0021556 0 ustar 00root root 0000000 0000000 # Device Templates
**Device Templates** are Cacti objects that allows you to define classes of
**Devices** that includes from one to many **Graph Templates**, **Data Queries**
and other **Plugin** related object types.
The purpose of **Device Templates** is to simplify the **Automation** process by
pre-defining the **Graphs** that should be created for every **Device** that is
added to Cacti. They work in conjunction with **Automation Templates** so that
when Cacti discovers a **Network** it knows what **Graphs** to create for each
**Device**.
The **Device Templates** main screen looks like the image below:
From this page, you can see the title of each **Device Template**, it's ID which
is important for the Cacti CLI scripts. You can see if the **Device Template**
can be removed, and the number of **Devices** using the **Device Template**.
Templates that are used by **Devices** can not be removed and therefore if you
attempt to remove one of these Templates, you will receive and error message.
From the drop down there are three options, they are:
Option | Description
--- | ---
Delete | Remove the **Device Template** if it's *Deletable*
Duplicate | Make an exact copy of the **Device Template**.
Sync Devices | Update all **Devices** using this **Device Template** with the latest definition, adding, but not removing **Graph Templates**, and **Data Queries**.
When editing a **Device Template**, you will see the page as displayed below.
From this page, you can add and remove **Graph Templates**, **Data Queries**,
and other **Plugin** objects. In the image below, you can see that the *Cisco
Router* has one **Graph Template** that of *Cisco - CPU Usage* and one **Data
Query** that of *SNMP - Interface Statistics*. There are no **Threshold
Templates** defined on the system, so there is no way to select one.
To add a **Graph Template** or **Data Query** to the **Device Template**, simply
select it from the drop down, and press the *Add* button. There is no need to
*Save* afterwards. To removed one of these items, simply press the x glyph to
the right of the desired **Graph Template** or **Data Query**.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Devices.md 0000664 0000000 0000000 00000015077 14124124457 0020015 0 ustar 00root root 0000000 0000000 # Device Management
This section will describe **Device** management in Cacti.
Adding a **Device** to Cacti can be done in a few different ways, either via
the Web GUI, Cacti's Automation, or the Command Line Interface (CLI).
## Web GUI Option
To add a device via the Web GUI first click on `Console > Managment > Devices` and
you will see the below device console window which will show existing devices
if any
You will now select the + on the top right hand corner
Once you select the + otherwise known as the add device button you will see the
below screen which will ask you for device specific information
Some of the most important information about the device will be required in this
window which includes
- **Description** - The name that will appear on **Graphs** by default
- **IP/Hostname** - The DNS or IP address of the actual **Device**
- **Poller Association** - Defines which **Data Collector** is responsible for
pulling information about the **Device**
- **Device Template** - Cisco, Net-SNMP, Linux, etc - The Cacti object that
holds all the **Graph Templates** and **Data Queries** to be graphed
- **Site, Location** - Very important to performing Meta queries, or for
Site level Graph organization on Cacti **Graph Trees**
- **Availability/Reachability** - Settings that describe **Device**
timeouts and availability methods.
- **SNMP information** - SNMP Credentials for connecting to the **Device**
- **Device Notes** - Arbitrary unstructured information about the **Device**
Cacti requires this basic information to be able to monitor the device and once
entered, click save on the bottom right corner. With the device created you will
need to add graphs for the device by clicking **Create graphs for this device**
on the top right hand corner.
## Availability/Reachability Settings
Cacti prefers to use the Simple Network Management Protocol (SNMP) to communicate
with **Devices**. Therefore, when creating a **Device**, you need to provide SNMP
credentials to obtain information about the **Device** in order to collect data from
it. Before Cacti will query the **Device** for data, it first verifies that the
**Device** is up and responding. When doing so, you have several options.
They include:
- **None** - Always assume the device is up. This is generally reserved for **Device**
objects that do not have a state.
- **SNMP Uptime** - Query the SNMP Uptime Instance OID
- **Ping and SNMP Uptime** - Ping the device but also check the SNMP Uptime
Instance OID
- **Ping** - Either ICMP, TCP at a port, or UDP as a port
- **Ping or SNMP Uptime** - Only one needs to be working for Cacti to collect data
- **SNMP Desc** - Query the SNMP sysDecription in cases where the SNMP Uptime OID
is not available
- **SNMP GetNext** - Query the first available OID in the OID tree for the **Device**
Used for certain devices that have limited SNMP support.
## SNMP Credentials
When providing the SNMP credentials, Cacti currently supports the following versions:
- **Version 1** - Rarely used any more. Reserved for very old hardware
- **Version 2** - Still very popular, and support 64 bit counters except on Windows
- **Version 3** - Support is provided, but there are presently limitations for example
at the present time only MD5, and SHA1 Auth Protocols, and DES and AES128
Privacy Protocols. Higher level encryption is currently scheduled for a future
release.
When providing the SNMP Credentials, Cacti will warn you if you have provided
incomplete information depending on the SNMP Version and SNMP Security Level
you have specified.
## Additional Important Options
There are some additional options that you should note before starting to use Cacti.
They include the following:
- **Device Threads** - If your device is far away, and can tolerate multiple threads
querying information, you can increase this number to reduce the time it takes
to collect all information.
- **Maximum OIDs Per Get Request** - Otherwise known as MaxOID's, this SNMP option
will allow the SNMP client to gather more metrics per get request. Please keep
in mind that the higher you make this number, the longer a SNMP respond may take.
So, you have to be sensitive about the SNMP timeout as the number get's larger.
Since, by default SNMP is generally collected over UDP, you will also be limited
in the number of responses depending on how many routers or VPN's you traverse
to reach a device. When traversing VPN connections, many VPN's limit the MTU
to around 500 bytes, which will significantly limit how large the Max OID's can
be. In some cases, it may be better to deploy a **Remote Data Collector** when
your device is either far way from a latency perspective, or that you must
traverse VPN's to communicate with.
- **External ID** - This field is normally used for Asset Tracking information for
the **Device**, but it use is entirely up to the System Administrator.
## Plugin Behavior
Many Cacti Plugins can and do add additional columns to the Device table in Cacti.
Depending on the Plugin you have installed, you will find other information that
you can provide about the device including things like:
- **Notification Settings** - Who to notify when the **Device** changes state
- **Criticality** - How important is the device
- **Failure and Recovery Counts** - How long till a device is treated as truely
down.
- **Ping Thresholds** - What RTL is considered bad when reaching a device
## Creating devices via CLI script
You can also create device by using the CLI script located at /cactidir/cli/
```console
usage: add_device.php --description=[description] --ip=[IP] --template=[ID] [--notes="[]"] [--disable]
[--poller=[id]] [--site=[id] [--external-id=[S]] [--proxy] [--threads=[1]
[--avail=[ping]] --ping_method=[icmp] --ping_port=[N/A, 1-65534] --ping_timeout=[N] --ping_retries=[2]
[--version=[0|1|2|3]] [--community=] [--port=161] [--timeout=500]
[--username= --password=] [--authproto=] [--privpass= --privproto=] [--context=] [--engineid=]
[--quiet]
Required:
--description the name that will be displayed by Cacti in the graphs
--ip self explanatory (can also be a FQDN)
```
To add a device using the bare minimum information would look something like this
```console
$ php add_device.php --description=test --ip=192.168.1.15
Adding test (192.168.1.15) as "Cacti Stats" using SNMP v3 with community "public"
Success - new device-id: (45)
```
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Discovered-Devices.md 0000664 0000000 0000000 00000002177 14124124457 0022077 0 ustar 00root root 0000000 0000000 # Automation Discovered Devices
After you initiate a scan from automation Cacti will compare devices
found to the device rules and SNMP options you set.
If Cacti is unable to match the device to a device template or unable to
find a proper SNMP credential.
Also if you have the automatically add to Cacti set to off the devices will
also be put in this section.
The Discovered Devices section can be found by navigating to the
following area.
Below you can see devices that have been found during the scan that did
not meet a match criteria.
You will see the IP that was scanned as well if avaliable the resolved
hostname either via DNS or netbios.
You can then select the device you are interested in adding click the
checkbox next to the device
on the dropdown you select add device this will bring up the below menu.
From this Menu you will be able to fill out the details of the new device.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Export-Template.md 0000664 0000000 0000000 00000053252 14124124457 0021462 0 ustar 00root root 0000000 0000000 # Template Exporting
Cacti allows **Device**, **Graph**, and **Data** Templates to be
exported in XML format. You can access the screen below by going
to `Console > Import / Export > Template Export`. When you get
to this page, the most popular option is to export the
**Device Template**, but the discretion is upto the user. Once
you pick the object type, the list of available templates
is presented. The most popular option is to save to a file,
but you have additional options.
Inside of the Template, Cacti uses a **hash** Global Uniqueue ID (GUID)
to uniquely identify every Template component. So, any Template
that you export can be shared with anyone around the globe without
ambiguity. See the Linux Device Template Example below.
In this Template thaere are Many Components:
1) The Device Template Name itself and it's GUID
2) All the Graph Templates and their GUID's
3) All the Graph Template inputs and their GUID's
4) All the Data Templates and their GUID's
5) All the Data Input Method's and their GUID's
6) All the GPrint Presets and their GUID's
7) All the CDEF's and VDEF's and their GUID's
8) All the Data Source Profiles and their GUID's
Although the output is human readable, some columns are encoded
so as to not cause problems with the XML output format.
To read them, you must base64_decode them in PHP or some
other language.
Presently they are saved in XML format, but there are
discussions with making these templates YAML formatted.
```xml
Local Linux Machinehash_0001029fe8b4da353689d376b99b2ea526cc6b|hash_000102fe5edd777a76d48fc48c11aded5211ef|hash_00010263610139d44d52b195cc375636653ebd|hash_0001026992ed4df4b44f3d5595386b8298f0echash_0401028ffa36c1864124b38bcda2ae9bd61f46Unix - Processes|host_description| - Processesprocesses12007001000onon21000000on4000Processes Data Sourcetask_item_idhash_000102d023fcaa39c9ffe41116492a116ea18e|hash_00010210b6ba6d1f88815cfac5397d41c426a6|hash_000102eadd16a7d7cb09b2b0555ac3710196ef|hash_0001025ae0cb568c7ca4ea3e6a0fbef39a7f76Legend Colorcolor_idhash_000102d023fcaa39c9ffe41116492a116ea18eUnix - Load Average|host_description| - Load Averagerun que length12007001000onon2on10000000on40001 Minute Data Sourcetask_item_idhash_0001023702a05e8729c3d48d162208dd072137|hash_000102862aeaac11049c1d81ae654d66c97dfb|hash_000102124baf8d0260ff62a1e6d21d9c4a4e97|hash_00010242b9183300db803dfcc0af1fd4b9f122|hash_000102cb9b5207c9f1f1009b813ef56f55702f5 Minute Data Sourcetask_item_idhash_000102ab258aac51f4a0160d43e0ba20b9b393|hash_0001020984a4c622139c0d11b78608160b33e3|hash_00010264469091b7dc7d6b39d3754980fc4a43|hash_0001028457ef82c0b87cae267536de4b667e09|hash_0001024e8ee8aa54c425e1ec17c83441fcc39315 Minute Data Sourcetask_item_idhash_0001022438af0fdd01e612291791acb29a711d|hash_000102752e3ae4e9a82bc3c923b0b236a5ac67|hash_0001028060cd7596e4f6b0831bf73ef8ba531a|hash_0001024a6c18ff005f2bcb751cdba638757566|hash_000102bfc93ecb2b6784c8525bc00d6448617bUnix - Logged in Users|host_description| - Logged in Usersusers12007001000onon2on10000on40Logged in Users Data Sourcetask_item_idhash_000102ab8392b002d42ad2fa1ba35a99ea51fe|hash_000102ad192b4b614505bbc36a8afd01d1781d|hash_0001023dcb58ff0357a88a9031cbf27b6f4c60|hash_000102efbf534120dad14b8ffcec7d71961640|hash_000102a1b9a134b64c84366bedc7e8d4c3a5bbLegend Colorcolor_idhash_000102ab8392b002d42ad2fa1ba35a99ea51feLinux - Memory Usage|host_description| - Memory Usagebytes12007001000onon2on1000000on4000Free Data Sourcetask_item_idhash_000102404665179f589ad7ce64b458bf93a58d|hash_00010264dd010cd56ccca790f2d640486a5bb7|hash_000102216032db321bbce61c28e318e1610c19|hash_0001026b871e99f6f37c98004a43df0155f521Swap Data Sourcetask_item_idhash_0001023e8ad5940852e6d4bf3cefa6680885b4|hash_000102bb01f635dbb02625115a9640ba6ece90|hash_0001025f16039fc5cef2deaa4dbe10d12a90b8|hash_000102fa62617953fa551b24d4109c52f6906eUnix - Available Disk Spaceon|host_description| - Available Disk Spacebytes12007001024onon2on10000on40Available Disk Space Data Sourcetask_item_idhash_0001023343968ae34b1a88fa46213c3e070d95|hash_00010243c7d573c7ae75f2ce7b8b5f43b8dc88|hash_00010283ae02d7a5034b683ee150a8245aa8a4|hash_000102b7a591d11b24890b366e82d15f70f474|hash_000102e277320375d05534aa01971d9320fc2eUsed Disk Space Data Sourcetask_item_idhash_000102b3d537a4ecdabbcd43313ed3a9ba3243|hash_000102b8bddc548722b2666a52beb9637890d8|hash_000102b09a9febbd898acec5a0af9296861c5b|hash_000102b974496fa30d693fafdea2aba4eda440|hash_00010288cce764897070f936dccdc37d620ed9Unix - Get Mounted PartitionsQueries a list of mounted partitions on a unix-based host with the/resource/script_queries/unix_disk.xmlhash_03010280e9e4c4191a5da189ae26d0e237f015hash_0001028e7c8a511652fe4a8e65c69f3d34779dDisk SpacedskAvailablehash_010102e4ac6919d4f6f21ec5b281a1d6ac4d4ehash_080102e801aab0a4b1d242b1e2bd49004d48abdskUsedhash_010102e4ac6919d4f6f21ec5b281a1d6ac4d4ehash_0801027b94166ab8c3e3374f44f13c8e36c109title1|host_description| - Disk Space - |query_dskDevice|namehash_010102e4ac6919d4f6f21ec5b281a1d6ac4d4e1|host_description| - Free Space - |query_dskDevice|Get Script Data (Indexed)4Index Typeindex_typeinindex_typeIndex Valueindex_valueinindex_valueOutput Type IDoutput_typeinoutput_typeOutput Valueonoutoutput
```
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/External-Links.md 0000664 0000000 0000000 00000001066 14124124457 0021264 0 ustar 00root root 0000000 0000000 # External Links
This section will describe **External Links** in Cacti.
External Links allows Administrators to add tabs to external links within
the Cacti GUI. This can be for example to google.ca
When the user clicks on the Tab an Iframe will display the webpage.
This feature can be very useful to create a single UI for helpdesk/NOC.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Frequently-Asked-Questions.md 0000664 0000000 0000000 00000034134 14124124457 0023601 0 ustar 00root root 0000000 0000000 # Frequently Asked Questions
## Using Cacti
**Q:** How do I create traffic graphs?
**A:** Before you can create traffic graphs, Cacti must have working SNMP
support. One way to do this is to compile PHP with SNMP support built in, many
times you can install the 'php-snmp' package to do this. The second option is
to have Cacti call the snmpget and snmpwalk binaries from your ucd-snmp or
net-snmp installation. You can use the about page to determine whether to are
using "built-in" or "external" SNMP support.
Now that you have working SNMP support, follow these steps.
1. Click Devices on Cacti's menu.
2. Click Add to add a new device.
3. Type a description, hostname, management IP, and SNMP community. Make sure
to select "Generic SNMP-enabled Host" under Host Template and click Create.
4. Click Create Graphs for this Host at the top of the page.
5. You should see one or more interfaces listed under the Data Query [SNMP -
Interface Statistics] box. Place a check next to each interface that you want
to graph. Below the box, select type of graph that you want to create (bits,
bytes, summation, etc).
6. Click Create, and Create again on the following screen to create your
graphs.
## General
**Q:** When I visit the Cacti Monitoring Website, I see garbage instead of a
login prompt.
**A:** Starting with Cacti 1.2.x, the first thing you should always see is a
login prompt asking for your admin credentials before the installation wizard
will be displayed. However, if you fail to see the login prompt, you may be
presented with text that looks like:
```php
How do I enable PHP under ...
Replacing the three dots with your operating system and web server software
should reveal many results on how to do this. The specific steps are outside of
the scope of Cacti's FAQ documentation, though there are several How To
installation documents included that may also help.
**Q:** I have forgotten my 'admin' password to Cacti, how do I reset it?
**A:** To reset the admin account password back to the default of 'admin',
connect to your Cacti database at the command line.
```sql
shell> mysql -u root -p cacti
```
Now execute the following SQL:
```sql
MySQL> update user_auth set password=md5('admin') where username='admin';
```
## Monitoring
**Q:** I am polling thousands of items and poller.php takes more than 5 minutes
to run.
**A:** Give Spine, the fast replacement for poller.php a try. Unlike
poller.php, Spine is written in c and makes use of threads. On a typical
installation, it is not uncommon for Spine to poll about 50000 items in less then
10 seconds. Spine supports upto several threads per poller process and
can also poll a single hosts with more than a single thread. If using spine
alone does not help, look to both the amount of memory and CPU threads are
available on your Cacti server. You should generally not use more than 2 times
the number of CPU threads as you have spine threads. Remember, every spine
thread has to also talk to the database, so having more CPU threads on your
Cacti server has a direct impact on performance. If you make the thread
setting too high, it will actually decrease performance. So, be careful.
**Q:** I changed x, and now some of my graphs are not updating.
**A:** First, check your Poller Cache to see if the poller entries for the
Data Sources in question are still found there. Then, if you find that they
are missing, you can either resave the Device in question, if it's a single
device, or Repopulate the Poller cache if it impacts multiple Devices. If
you have a large installation with thousands or tens of thousands of devices
you should use the CLI script `rebuild_poller_cache.php` to perform this action.
Often times, if you have changed a Template, bad things can happen. So, it's
always advisable to have a backup of your Graph and Data Templates as well as
any Script or XML files you used to create the Templates. Another good practice
is to perform database backups daily just in case of either an unintended
change, or a disaster.
**Q:** I am using Redhat 8.0 and SNMP is not working.
**A:** Redhat 8.0 comes with a broken php-snmp package. Updating your
'php-snmp' and 'net-snmp' packages to their latest versions should fix this
problem.
**Q:** How do I configure net-snmp so it will work with Cacti?
**A:** Run `snmpconf -g basic_setup` and follow the prompts. Also check that
the file being used by snmpd is the correct config file. For Redhat Linux,
snmpconf creates the `/etc/snmpd.conf`, but snmpd uses `/etc/snmpd/snmpd.conf`.
If this doesn't work a very simple config file is:
# contact
syslocation Something
syscontact "root@someone.com"
# auth
rocommunity public
# disk monitoring
disk /
# Don't monitor NFS
skipNFSInHostResources true
# Allow for real big disk volumes
realStorageUnits 0
After you have made the changes to the net-snmp configuration file, you should
restart the service using the following command:
```sh
shell> systemctl enable snmpd
shell> systemctl restart snmpd
```
Though there are many more advanced settings available in net-snmp, it generally
recommended to keep a simpler configuration unless your information security
policies require more stringent settings.
**Q:** I've installed Cacti, and scheduled a network discovery, but nothing
is happening. Where should I go to see the issue?
**A:** You should click the **Log** tab at the top of the page. When you get
to the **Log** tab, you should search for an entry "SYSTEM STATS:". If you
do not find that entry, it means that you Cacti Data Collector, otherwise known
as the Cacti Poller is not running.
This can happen if you have neglected to create either a CRON entry for the
Cacti Poller, or registered and started the `cactid` service available in
the latest Cacti. If you find that the CRON entry is there, you should look
at your systems CRON log for entries like **permission denied**. Sometimes
the user accounts you have selected to run the CRON are not permitted to do
so. We strongly recommend that you use the `cactid` service with Cacti 1.x
though and avoid CRON based Data Collection though.
## Graphs
**Q:** I just installed Cacti and all of my graphs appear as broken images.
**A:** For you to actually get graph images, poller.php must run at least once
so it can create .rrd files in Cacti's 'rra/' directory. Double check that you
configured your `/etc/crontab` file or the `cactid` service to execute poller.php
at the desired frequency, normally either every 1 or 5 minutes. Also make sure
that the user poller.php runs as has permission to create new files in Cacti's 'rra/'
directory. In the modern Cacti, both the Web Server account and Cacti's Poller
account must have write access.
If all of your settings appear correct, try running poller.php manually by
cd'ing to Cacti's directory and typing:
```sh
shell> php poller.php
```
If you have files in your 'rra/' directory, but your graphs still appear as
broken images, you should enable graph debug mode see exactly why the graphs
are not rendering. To do this go into Cacti, select Graph Management from the
menu, select any graph listed, and select Turn On Graph Debug Mode.
**Q:** My graphs render, but they do not contain any data.
**A:** More often than not, this problem's cause is permissions. For instance
if you run poller.php manually as root for testing, any .rrd files that it
creates will be owned by root. Now when poller.php runs from cron, it will not
be able to update these .rrd files because they are owned by root. You can
double check the owner of your .rrd files by running the following command in
your Cacti directory:
```sh
shell> ls -al rra/
```
If only some of your graphs are not updating correctly, double check the
Maximum Value field for all data sources used by these graphs. If the value
being fed to the .rrd file exceeds its Maximum Value, RRDtool will insert an
Unknown and you will see no data on the graph.
**Q:** A lot of my graphs contain long ifAlias names, but they are being
truncated to 15 characters.
**A:** Cacti does this by default to better control graph title formatting. You
can change this limit, by going to Cacti Settings on the Cacti menu, selecting
the Visual tab, and changing the value for Data Queries - Maximum Field Length.
**Q:** One of my devices rebooted and now I have a huge spike on my graph!
**A:** This occurs because the reboot causes SNMP counters to reset, which
can cause a rather large spike on the graph when RRDtool tries to determine the
change between the new small counter value and the large previous value. One
way to combat this issue is to specify realistic maximum values for your data
sources. RRDtool will ignore any value that is larger than the maximum value.
If you already have a spike on one or more of your graphs, there is a really
[useful Perl script](http://cricket.sourceforge.net/contrib/files/killspike2)
that will remove them for you.
**Q:** RRDtool Says: ERROR: unknown option '--slope-mode' or RRDtool Says:
ERROR: Garbage ':39:24 To 2005/10/22 16:39:24\c' after command: COMMENT:From
2005/10/21 16:39:24 To 2005/10/22 16:39:24\c
**A:** This occurs because the version of RRDtool that you are running does not
match the RRDtool version Cacti is configured to use. Double check your Cacti
Settings and make sure that the RRDtool version matches what version of RRDtool
you are running.
## Windows Related
**Q:** I get a "Fatal error: Cannot redeclare title_trim()" error message from
Cacti.
**A:** Contrary to previous versions of Cacti, you must not put Cacti in your
PHP include path. Check your `php.ini` file to make sure there is not something
like `include_path = C:/Apache2/htdocs/cacti`.
## Common Problems
### Cron is out of sync with the Poller Interval
```shell
WARNING: Cron is out of sync with the Poller Interval! The Poller Interval is
'15' seconds, with a maximum of a '60' second Cron, but 300.9 seconds have
passed since the last poll!
```
This warning message may be recorded in the Cacti logs if you have a mismatch
between the cron file that runs the poller.php and the settings within Cacti
itself. Browse to **Console > Configuration > Settings > Poller** *(tab)*
and check that the Cron Interval is defined as either 1 minute or 5 minutes.
If the cron inteval is 5 minutes, then the schedule within the cron
configuration file (normally /etc/cron.d/cacti) should be set to:
```console
*/5 * * * *
```
For 1 minute intervals, this should be:
```console
* * * * *
```
### Poller Runtime exceeded
```shell
POLLER: Poller[0] Maximum runtime of xxx seconds exceeded.
```
This error indicates that Cacti was unable to finish the polling cycle in time.
This can be for a few reasons.
* You are using spine and have not entered the correct mysql credentials in spine.conf
* You do not have an adaquete proccess setting for cmd.php or thread/process
count for spine
* Network related issue either an network outage or a network slowdown
* System related trouble cpu/memory exhaustion
* Insufficient MySQL connections resulting in spine failing
### RRDtool reports Unknown Error
Sometimes, RRDtool can be rather unhelpful and display the simple error within
the graph image of "Unknown Error". When this occurs, the best course of action
would be to grab the command that Cacti uses and see if any more information is
given at the command line level.
To do this, edit a graph that has the issue, select **Turn On Graph Debug** and
a new section should appear beneath the graph. This should show both the
command and what output we received from the tool.
```console
RRDtool Command:
/usr/bin/rrdtool graph - \
--imgformat=PNG \
--start='-86400' \
--end='-60' \
--pango-markup \
--title='localhost - CPU Usage' \
--vertical-label='percent' \
--slope-mode \
--base=1000 \
--height=200 \
--width=700 \
--tabwidth '40' \
--rigid \
--alt-autoscale-max \
--lower-limit='0' \
COMMENT:"From 2019/10/19 12\:37\:00 To 2019/10/20 12\:36\:00\c" \
COMMENT:" \n" \
--color BACK#F3F3F3 \
--color CANVAS#FDFDFD \
--color SHADEA#CBCBCB \
--color SHADEB#999999 \
--color FONT#000000 \
--color AXIS#2C4D43 \
--color ARROW#2C4D43 \
--color FRAME#2C4D43 \
--border 1 --font TITLE:11:'Arial' \
--font AXIS:8:'Arial' \
--font LEGEND:8:'Courier' \
--font UNIT:8:'Arial' \
--font WATERMARK:6:'Arial' \
--slope-mode \
--watermark 'Generated by Cacti' \
DEF:a='/usr/share/cacti/site/rra/127_0_0_1_5min_cpu_40.rrd':'5min_cpu':MAX \
AREA:a#FF0000FF:'CPU Usage' \
GPRINT:a:LAST:'Current\:%8.0lf' \
GPRINT:a:AVERAGE:'Average\:%8.0lf' \
GPRINT:a:MAX:'Maximum\:%8.0lf\n'
RRDtool Says:
OK
```
If the output above isn't helpful, simply copy the command section and then
run it as the user which the website runs as. For Linux, you can do this by
either `su - ` and then running the command, or `sudo -u `
to stay as your current user but run the command as the website user.
For Windows, the following command will allow you to spawn a command prompt as
the website user, from which you can then run the above command to see the
output.
```console
runas /user:\ cmd.exe
```
The newly created command prompt should show the user name if you have entered
the correct password.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/GPRINTs.md 0000664 0000000 0000000 00000001721 14124124457 0017610 0 ustar 00root root 0000000 0000000 # GPRINT Presets
GPRINT Presets are an object in Cacti used for formatting
Legend output on RRDtool Graphs. These GPrint Presets
closely fillow printf(), sprintf() ANSI syntax. They
are simple to create and edit. You can find the format
strings on the [RRDtool Website](https://oss.oetiker.ch/rrdtool/doc/rrdgraph_graph.en.html#PRINT).
The stock GPrint Presets are generally sufficient for most
**Graph Templates**, but they can easily be extended,
and are a part of the Graph Template Export XML file. So,
they are portable once created.
In the image below, you can see the default GPrint Presets
and the actions that can be taken on them. Keep in mind
that once a GPrint Preset is being used by a **Graph**
or a **Graph Template**. It can not be removed.
Below you can see the GPrint Preset edit screeen.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/General-Installing-Instructions.md 0000664 0000000 0000000 00000025003 14124124457 0024602 0 ustar 00root root 0000000 0000000 # General Installing Instructions
Make sure the following packages are installed according to your operating
systems requirements. Verify, that httpd/apache and MySQL/MariaDB are started
at system startup.
## 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 come 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 to 5.7 are supported. MariaDB to 10.2 is also supported.
- mysql
- mysql-server
- libmysqlclient
or
- mariadb
- mariadb-server
- libmariadbclient
### PHP Modules
The installation of these modules vary 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)
## FreeBSD
When installing on FreeBSD you can use two ways. For both ways, cacti has a lot
of dependent packages, you don't need to install anything else. Everything is
prepared. Both ways have few pros and cons:
- Compiled packages - fast, but invariant dependencies (like older MySQL server,
PHP version, ...)
```sh
pkg install cacti
pkg install spine
```
- FreeBSD ports - compilation could last long time, but without invariant
dependencies (See [Howto use
ports](https://www.freebsd.org/doc/handbook/ports-using.html))
```sh
portsnap fetch extract
portsnap fetch update
cd /usr/ports/databases/mariadb102-server (or mysql57-server)
make install
cd /usr/ports/net-mgmt/cacti
make install
cd /usr/ports/net-mgmt/spine
make install
```
Apache and other software is possible install with package or Ports too.
Everything in FreeBSD is installed to /usr/local/ directory! In this
documentation you can see paths like /etc/php.ini, /usr/bin/spine, ...
Please use correct paths - /usr/local/etc, /usr/local/bin/spine, ...
For Spine set suid bit (without this isn't possible make ICMP ping):
```sh
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](http://www.php.net/manual/en/configuration.php) 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/UNIX OS' automatically configure the Web Server to allow PHP content.
So there should be no need to provide additional configuration. However, the
following section is included below for reference in the case that you are
running a UNIX version that does not properly configure the Webserver properly.
The documentation below is written specifically for RHEL and variants. So, the
instructions may vary.
Find the file `/etc/httpd/conf/httpd.conf` or its equivalent and make the
following changes to it:
```ini
# 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`
```ini
# 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 loose
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.
```sh
shell> mysqladmin --user=root password somepassword
shell> mysqladmin --user=root --password reload
```
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.
```sh
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: There are several tables which are set to use the MEMORY
storage engine which do not get replicated among nodes which can cause problems.
If you configure Cacti to only connect to 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 you should remove all but one node from rotation during Cacti
installation or update. After the installation/update login to your MySQL server
and execute the following commands to update those tables to use the InnoDB
engine:
```sql
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_processes` ENGINE=InnoDB;
```
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.
```sh
shell> tar xzvf cacti-version.tar.gz
```
2. Create the MySQL database:
```sh
shell> mysqladmin --user=root create cacti
```
3. Import the default cacti database:
```sh
shell> mysql cacti < cacti.sql
```
4. Optional: Create a MySQL username and password for Cacti.
```sql
shell> mysql --user=root mysql
MySQL> GRANT ALL ON cacti.* TO cactiuser@localhost IDENTIFIED BY 'somepassword';
MySQL> GRANT SELECT ON mysql.time_zone_name TO cactiuser@localhost IDENTIFIED BY 'somepassword';
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`.
```sql
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.
```php
$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.
```sh
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
```console
*/5 * * * * apache php /poller.php &>/dev/null
```
For systemd unit's file install, you will need to modify the
included units file to following your install location
and desired user and group's to run the Cacti poller as.
To complete the task, follow the procedure below:
```console
vim /service/cactid.service (edit the path)
touch /etc/sysconfig/cactid
cp -p /service/cactid.service /etc/systemd/system
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:
```sh
shell> chown -R resource scripts include/config.php
```
Once the installation is complete, you may change the permissions to more
restrictive settings.
9. Point your web browser to:
`http:///cacti/`
Log in the with a username/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
```sh
shell>./bootstrap
```
If the `boostrap` script is successful, you then will follow the instructions it
provides to compile and install.
Assuming, you've managed to install spine correctly, you will have to configure
it. The configuration file may be placed in the same directory as spine itself
or at /etc/spine.conf.
```ini
DB_Host 127.0.0.1 or hostname (not localhost)
DB_Database cacti
DB_User cactiuser
DB_Password cacti
DB_Port 3306
```
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Graph-Overview.md 0000664 0000000 0000000 00000006051 14124124457 0021270 0 ustar 00root root 0000000 0000000 # Graph Overview
Almost everything in Cacti is somehow related to a **Graph**. At any time, you can
list all available **Graph** by clicking on `Console > Management > Graphs` menu
pick. While it is possible to manually create graphs through this interface,
new users should follow the instructions provided in the next chapter for
creating **New Graphs** in Cacti.
For users who are familiar with [RRDtool](http://www.RRDtool.org/), you will
immediately recognize that a **Graph** in Cacti is closely modeled after RRDtool's
graphs. This makes sense since Cacti provides a user friendly interface to
RRDtool without requiring users to understand how RRDtool works. With this in
mind, every **Graph** in Cacti has certain settings and at least one **Graph Item**
associated with it. While graph settings define the overall properties of a
**Graph**, the **Graph Items** define the data that is to be represented on the **Graph**.
So the **Graph Items** define which data to display and how it should displayed,
and also define what should be displayed on the legend.
Each **Graph** and **Graph Item** has a set of parameters which control various aspects
of the **Graph**. Fortunately through the use of **Graph Templates**, it is not
necessary to understand the function of each field to create **Graphs** for your
network. When you are ready to take on the task of creating your own **Graph
Templates**, extensive field descriptions for both **Graphs** and
**Graph Items** are provided in that section of the manual.
Below, you can see a simple version of the Graph Management interface found
by going to `Console > Management > Graphs`
From this interface, you can see the Name, and ID of the **Graph**,
the Source **Graph Template**, and it's size. At the bottom of the page, there
is a list of Action that can be taken on **Graphs**. These actions are fairly
extensive, and are also extended as you add **Plugins** to Cacti.
When you click on the Name of the **Graph**, you will be taken to a `Graph Edit`
page as shown below.
In most cases, where the **Graph** is owned by a **Graph Template**, there is
not much your can do on this page. However, in the case that a **Graph**
is not managed by a template as in the image below, there are many more
options you will have when working with the **Graph**. The downside of
not leveraging a **Graph Template** for your **Graphs** is that you have
to duplicate the work for each **Graph** created.
When viewing a Non-Templated **Graph**, you have complete control of the
**Graphs** Canvas and all the **Graph Items** as you would in a **Graph Template**,
and the Graph Configuration as shown below.
The settings in both the Canvas and Configuration components of the **Graph**
will be covered in the **Graph Template** section of the manual and not
covered here.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Graph-Rules.md 0000664 0000000 0000000 00000003627 14124124457 0020562 0 ustar 00root root 0000000 0000000 # Automation Graph Rules
This section will describe **Graph Rules** in Cacti.
Graph rules are used by the Cacti automation process after a device has been
identified and a template has been applied the next step is graph creation.
Graph rules are processed from top to bottom.
The graph rule matches the graph template by looking at the data fields
chosen that are available in the data query for example below we are creating
graphs for interface traffic the data query has several fields available to
match on.
You can see how these rules would take place by clicking the show matching
objects link.
A practical example if you want to create graphs for interfaces that are in
up/up status you would choose the ifOperstatus field and match the status to
UP this would tell automation to create the graph for that interface only if
the data query discovers the operational status is equal to up.
A device selection Criteria is also important Cacti needs a way to find which
device it needs to match. In the below example we are matching any device
that has an interface that is up and is not a Windows server.
You can preview which devices this will apply to by clicking the Show matching
devices link.
This output shows us which devices match our devices rules this can help with
tweaking rules as needed.
This output shows which interfaces,drives,sensors etc will be graphed based
on the graph rules.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Graph-Templates.md 0000664 0000000 0000000 00000016407 14124124457 0021426 0 ustar 00root root 0000000 0000000 # Graph Templates
**Graph Templates** are Cacti objects that allows you to define how RRDtool is
to render a Cacti **Graph**. Most RRDtool options are supported including
CDEF's and VDEF's, Left and Right Axis, Ticks and Dashes, multiple Auto Scaling,
Grid, and Legend Options.
The purpose of **Graph Templates** is to simplify the **Automation** process by
pre-defining the layout of **Graphs** for various metrics that are to be
monitored in Cacti. When used in Conjunction with Cacti's **Graph Rules**, you
can automatically create just about any **Data Query** based **Graph** during
Cacti's **Network Discovery** process.
The **Graph Templates** main screen looks like the image below:
From this page, you can see the title of each **Graph Template**, it's ID which
is important for the Cacti CLI scripts. You can see if the **Graph Template**
can be removed, and the number of **Graphs** using the **Graph Template** as
well as the *Size* of the **Graphs** that will be created, the *Image Format*,
and *Vertical Label*. Templates that are used by **Devices** can not be removed
and therefore if you attempt to remove one of these Templates, you will receive
and error message.
From the drop down there are three options, they are:
Option | Description
--- | ---
*Delete* | Remove the **Graph Template** if it's *Deletable*
*Duplicate* | Make an exact copy of the **Graph Template**
*Resize* | Make a resize decision that affects both the **Graph Template** and any **Graphs** created using this **Graph Template**
*Sync Graphs* | Update all **Graphs** using this **Graph Template** with the latest definition, adding new *Graph Items* and removing orphaned *Graph Items*
When Editing a **Graph Template**, there will be several sections that will
require information from the Administrator. Those sections include:
Section | Description
--- | ---
*Graph Template Items* | These items paint inside the canvas of the **Graph**
*Graph Item Inputs* | This list is created automatically when you add **Data Sources** to a **Graph Template**. However, you can also override certain **Data Template** and **Graph Template** fields by adding specifically named objects to this section as well.
*Graph Template* | Allows you to name the **Graph Template**, and whether or not you will allow multiple instances of this **Graph Template** to be used for a **Device**, and whether or not to test for valid data before allowing the creation of **Graphs**. The *Test Data Source* option is useful when you want to leverage a complex **Device Template** that contains **Graph Templates** that may not be applicable for all classes of **Devices** using the **Graph Template**.
*Common Options* | Things like Title, Vertical Label, Image Format, Height and Width, Base Value and Slope Mode
*Scaling Options* | Which determine if the Graph is auto-scaled and by what means. Determines if the Graph will have fixed upper and lower limits
*Grid Options* | Defines how the Graph canvas grid is rendered
*Axis Options* | Defines if there should be a right Axis and how it should be formatted
*Legend Options* | Defines how the Legends should be formatted
Each of these sections are displayed below for reference. For more information
on how to use these options, please visit the [RRDtool
Website](http://RRDtool.org).
The *Graph Items* make up what is draw within the canvas of the Graph. There
are several *Graph Item* types including:
Type | Description
--- | ---
*AREA* | Place an *Area Fill* on the canvas
*AREA:STACK* | The second item of an *Area Fill* to be stacked upon the first
*COMMENT* | A written comment. Can include: |host_*|, |query_*|, |input_*| *Replacement Variables*
*GPRINT* | Print a numeric value from the RRDfile with an optional **CDEF** or **VDEF** and formatted using a **GPRINT Preset**.
*GPRINT:AVERAGE* | Print a numeric value from the RRDfile from the *AVERAGE* *Consolidation Function* within the RRA, modified by an optional **CDEF**, or **VDEF**, and formatted using a **GPRINT Preset**.
*GPRINT:LAST* | Print a numeric value from the RRDfile from the *LAST* *Consolidation Function* within the RRA, modified by an optional **CDEF**, or **VDEF**, and formatted using a **GPRINT Preset**.
*GPRINT:MAX* | Print a numeric value from the RRDfile from the *MAX* *Consolidation Function* within the RRA, modified by an optional **CDEF**, or **VDEF**, and formatted using a **GPRINT Preset**.
*GPRINT:MIN* | Print a numeric value from the RRDfile from the *MIN* *Consolidation Function* within the RRA, modified by an optional **CDEF**, or **VDEF**, and formatted using a **GPRINT Preset**.
*HRULE* | Draw an *Horizontal Rule* at the given point on the canvas. You can NOT use any Data Source element or an optional **CDEF** or **VDEF**, but may be able to use either a |query_*|, or |input_*| *Replacement Variable*.
*LEGEND* | Draw a *Legend* from three *GPRINTS* using the same **GPRINT Preset**, and **VDEF** or **CDEF**. The *Current*, *Average*, and *Max* *Consolidation Functions* are used.
*LEGEND_CAMM* | Draw a *Legend* from four *GPRINTS* using the same **GPRINT_Preset**, and **VDEF** or **CDEF**. The *Current*, *Average*, "Min*, and "Max" functions are used for this *Legend*.
*LINE[1,2,3]* | Draw a 1, 2, 3 or used defined thickness pixel *Line* from the RRDfile onto the canvas, modified by an optional **CDEF**, or **VDEF**.
*LINE:STACK* | Stack a Line of a user defined thickness on top of another *Line*, modified by an optional **CDEF**, or **VDEF**.
*TEXTALIGN* | Modify future text using the alignment provided.
*VRULE* | Place a *Vertical Rule* on the canvas of a specific color and time position.
The canvas is painted from the first *Graph Item* till the last with each
successive *Graph Item* rendered on top of the previous. Please keep this in
mind when creating a **Graph Template**.
Under the *Common Options*, you will create a template for the *Graph Name*,
assign it's *Veritcal Label*, specify the *Width* and *Height*, and *Image
Format* for the resulting **Graph**. The *Base Value* is important as some
units of measure can be for example: MB (for Mega Bytes - 1024) and MiB (for
Mega integer Bytes - 1000). Lastly, the *Slope Mode* gives the resulting
**Graphs** a smoother look.
The *Scaling Options* allow the Administrator to apply either *Rigid* or *Auto
Scaling* settings to the resulting *Graph*. These options are fairly self
explanatory. However, you can always view the RRDtool Documentation online for
more information.
The *Grid Options* are rarely necessary unless you have specific requirements to
render the resulting **Graphs** with some exotic unit.
The *Axis Options* allow you to define a *Right Axis* and optional *Formatters*.
The *Legend* options allow you to specify how the *Legend* should be placed on
the resulting **Graph** modern RRDtool has several options that were not
available in Cacti prior to Cacti 1.0.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Graph-a-Single-SNMP-OID.md 0000664 0000000 0000000 00000011033 14124124457 0022301 0 ustar 00root root 0000000 0000000 # Creating a Graph for a Single SNMP OID
When dealing with SNMP-enabled **Devices**, there are often times when you want to
graph the value of a single OID. This tutorial explains how to do this in
Cacti. It also assumes that you have the "SNMP - Generic OID Template" **Graph
Template** which is available in the **Generic SNMP Device Package**.
If you do not see this **Graph Template** listed under **Graph Templates**,
install the **Generic SNMP Device Package** using the `import_package.php`
command line script located in Cacti's cli directory.
To start the process of creating a new graph for your OID, click go to
`Cosnole > Create > New Graphs`, and from there find the **Device**
you would like to add the **Graph** to.
From the image below, you can see the **New Graphs** interface.
In this image, only the **Graph Template** based **Graph Templates** are displayed.
Had the `Graph Types` been switched to any of the **Data Query** based `Graph Types`
the interface would look a bit different.
From that Interface, to create a `Generic SNMP OID` based Graph, you need to first
select it from the `Select a graph type to create` drop-down. Once you have selected
it, you may press the `Create` button, at which point in time, you will see the
image below.
From this interface, you must define various attributes for your resulting **Graph**
as shown in the table below.
###### Table 10-1. Field Description: SNMP - Generic OID Template
Name | Description
--- | ---
(Graph) Title | The title that is to be used for the new graph. It is generally a good idea to keep `|host_description|` in the title, as to make the graph easier to identify later.
(Graph) Vertical Label | The text that will be printed along the y-axis of the graph. It is generally used to describe units, such as 'bytes' or 'percent'.
(Graph Items) Legend Color | The color that will be used to represent the data on the graph.
(Graph Items) Opacity/Alpha Channel | This optionally provides an opacity (not available with RRDtool-1.0.x) for a colored item.
(Graph Items) Legend Text | The text that will be used to describe the data on the graph legend.
(Data Source) Name | The title that is to be used for the new data source. It is generally a good idea to keep |host_description| in the title, as to make the data source easier to identify later.
(Data Source) Maximum Value [snmp_oid] | The maximum value that will be accepted from the OID. Make sure you choose a value that is reasonable for the data you are trying to graph because anything larger than the maximum will be ignored. If you are graphing a percentage, you should use '100' as the value should never exceed this.
(Data Source) Data Source Type [snmp_oid] | How the data from the OID should be stored by RRDtool and interpreted on the graph. If the value of the OID represents the actual data, you should use GAUGE for this field. If the OID value is a constantly incremented number, you should use COUNTER for this field. The two remaining field values, DERIVE and ABSOLUTE can be ignored in most situations.
(Custom Data) OID | The actual SNMP OID to graph. It is typically a good idea to enter the number OID here as opposed to using MIB names. For instance, to get the number of open files on a Netware server, you would use ".1.3.6.1.4.1.23.2.28.2.7.0" as the OID.
So, based upon your specific OID that you are graphing, You will need
to fill out these fields before the new graph can be created properly.
When finished filling in values for these fields, click the Create button. Your
new **Graph** can now be accessed through the
`Cosole > Management > Graphs` menu pick.
> **NOTE**: When comparing the Table above, to the image, you will see
> that the `Opacity/Alpha Channel` pick is missing from the interface.
> To add it, you simply need > to edit the `Generic SNMP OID`
> **Graph Template**, add a new **Graph Item Input**
> override to the Alpha/Opacity on the Graph Template as shown below.
> That topic will be covered in the **Graph Template** section of
> the manual though.
#### Important Note on graphing single OID's with Cacti
In order to ensure that Spine and cmd.php will process single OID's correctly,
They should be written using numeric format separated by dots, such as `1.3.6.1.4.1.9.9.97.`
At this time, ASN's (named OID's) such as `enterprise.9.9.97` (Cisco Switch) or
`enterprises.cisco.ciscoMgnt.ciscoSwitchEngineMIB` are not supported.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/Graphs.md 0000664 0000000 0000000 00000002051 14124124457 0017643 0 ustar 00root root 0000000 0000000 # Graph Management
This section will describe **Graph** management in Cacti.
Cacti features a way to view the graphs per device via the console. This allows
the administrator to view the graphs that are attached to a specific device. You
can also search by type of graph. Below we search for graphs that are
associated with the local linux server
Clicking on one of the graphs in the list shows the below menu. From this menu
you can enable debugging on the specific graph you can also change the template
of the graph amongst other things
### Modifying the graph template
Cacti allows you to change many aspects of the graph template. You can
change parameters such the title of the graph as well the size of the graphs.
These changes will be pushed to the graph template so other devices using the
template will also be updated.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-Create-Data-Input-Method.md 0000664 0000000 0000000 00000034461 14124124457 0024131 0 ustar 00root root 0000000 0000000 # Data Input Methods - From Script Output to Complete Graph
In this How-To we will take you through the process of creating a script
and then from the scripts output generate a complete **Graph Template**
that you can apply to your Cacti system. You should be able to reproduce
this process regardless of the script type in question.
## Data Input Method returning a single value
Lets start with a simple script that takes a hostname or IP address as input
parameter returning a single value.
`/scripts/ping.pl`:
```shell
#!/usr/bin/perl
# take care for tcp:hostname or TCP:ip@
$host = $ARGV[0];
$host =~ s/tcp:/$1/gis;
# old Linux version use "icmp_seq"
# newer use "icmp_req" instead
open(PROCESS, "ping -c 1 $host | grep 'icmp_[s|r]eq' | grep time |");
$ping = ;
close(PROCESS);
$ping =~ m/(.*time=)(.*) (ms|usec)/;
if ($2 == "") {
print "U"; # avoid cacti errors, but do not fake RRDtool stats
}elsif ($3 eq "usec") {
print $2/1000; # re-calculate in units of "ms"
}else{
print $2;
}
```
To define this script as a **Data Input Method** to Cacti go to **Data
Input Methods** and click **Add**. You should see:
Please fill in **Name**, select **Script/Command** as Input Type and provide the
command that should be used to retrieve the data. You may use `` as
a symbolical name for the path_to_your_Cacti_installation. Those commands will
be executed from crontab; so pay attention to providing full path to binaries if
required (e.g. `/usr/bin/perl` instead of `perl`). Enter all **Input
Parameters** in `<>` brackets. Click create to see:
Now lets define the **Input Fields**. Click **Add** as given above to see:
The drop down **Field [Input]** contains one single value only. This is taken
from the **Input String** `` above. Fill **Friendly Name** to serve your
needs. The **Special Type** Code allows you to provide parameters from the
current Device to be queried. In this case, the **hostname** will be taken from
the current device. Click create to see:
At least, define the **Output Fields**. Again, click **Add** as described above:
Provide a short **Field [Output]** name and a more meaningful **Friendly Name**.
As you will want to save those data, select **Update RRDfile**. Create to see:
Click **Save** and you're done.
## Creating the Data Template
Now you want to tell Cacti, how to store the data retrieved from this script.
Please go to **Data Templates** and click Add. You should see:
Fill in the **Data Templates Name** with a reasonable text. This name will be
used to find this Template among others. Then fill in the **Data Source
Name**. This is the name given to the host-specific **Data Source**. The
variable **|host_description|** is taken from the actual **Device**. This is to
distinguish **Data Sources** for different devices. The **Data Input Method** is
a drop down containing all known scripts and the like. Select the **Data Input
Method** you just created. The **Associated RRA's** is filled by default. At the
moment there's no need to change this. The lower part of the screen looks like:
The **Internal Data Source Name** may be defined at your wish. There's no need
to use the same name as the Output Field of the **Data Input Method**, but it
may look nicer. Click create to see:
Notice the new drop down **Output Field**. As there is only one Output Field
defined by our **Data Input Method**, you'll see only this. Here's how to
connect the **Data Source Name** (used in the RRDfile) to the Output Field of
the Script. Click **Save** and you're done.
## Creating the Graph Template
Now you want to tell Cacti, how to present the data retrieved from this script.
Please go to **Graph Templates** and click **Add**. You should see:
Fill in **Name** and **Title**. The variable `|host_description|` will again be
filled from the Device's definition when generating the **Graph**. Keep the rest
as is and **Create**. See:
Now click the plus (+) glyph to **Add** the first item to be shown on the
**Graphs**:
Select the correct **Data Source** from the drop down, fill in a color of your
liking and select AREA as a **Graph Item Type**. You want to fill in a **Text
Format** that will be shown underneath the **Graph** as a legend. Again,
**Create**:
Notice, that not only an entry was made under **Graph Template Items**, but
under **Graph Item Inputs** as well. Don't bother with that now. Lets fill some
more nice legends, see:
Notice, that the **Data Source** is filled in automagically. Select LEGEND as
**Graph Item Type** (it is not really a **Graph Item Type** in RRDtool-speak,
but a nice time-saver), and click **Create** to see:
Wow! Three items filled with one action!
## Apply the Graph Template to a Device
Now go to the **Devices** and select the one of your choice. See the
**Associated Graph Templates** in the middle of this page:
Select your newly created **Graph Template** from the Add **Graph Template**
drop down. Click the plus (+) glyph to see:
By default, the **Graph Template** is added and shown as **Is Being Graphed**.
The reason for this is that Cacti now automatically creates **Graphs**
automatically, unless disabled. If the **Graph Template** shows **Not Being
Graphed**, you can create the **Graph** by pressing the **Create Graphs** at the
top of the **Devices** page. Click this link to see:
Check the box that belongs to the new template and Create. See the results:
This will automatically
- Create the needed **Graph Description** from the **Graph Template**. As you
may notice from the success message, this **Graph** takes the hosts name in
it: **router - Test ping** (router is the hosts name of this example).
- Create the needed **Data Source Description** from the **Data Template**.
Again, you will find the Hosts name replaced for |host_description|
- Create the needed RRDfile with definitions from the **Data Template**. The
name of this file is derived from the Host and the **Data Template** in
conjunction with an auto-incrementing number.
- Create an entry to the poller_item to instruct Cacti to gather data on each
polling cycle.
You'll have to wait at least two polling cycles to find data in the **Graph**.
Find your **Graph** by going to **Graph Management**, filtering for your host
and selecting the appropriate **Graph** (there are other methods as well). This
may look like:
## Walkthrough: Script with more Output Parameters
The script below will be implemented in perl. Please note that any supported
language is supported using Cacti from direct command execution to scripts
written in perl, python, php, bash, etc.
```shell
#!/usr/bin/perl -w
# --------------------------------------------------
# ARGV[0] = <hostname> required
# ARGV[1] = <snmp port> required
# ARGV[2] = <community> required
# ARGV[3] = <version> required
# --------------------------------------------------
use Net::SNMP;
# verify input parameters
my $in_hostname = $ARGV[0] if defined $ARGV[0];
my $in_port = $ARGV[1] if defined $ARGV[1];
my $in_community = $ARGV[2] if defined $ARGV[2];
my $in_version = $ARGV[3] if defined $ARGV[3];
# usage notes
if (
( ! defined $in_hostname ) ||
( ! defined $in_port ) ||
( ! defined $in_community ) ||
( ! defined $in_version )
) {
print "usage:\n\n
$0 <host> <port> <community> <version>\n\n";
exit;
}
# list all OIDs to be queried
my $udpInDatagrams = ".1.3.6.1.2.1.7.1.0";
my $udpOutDatagrams = ".1.3.6.1.2.1.7.4.0";
# get information via SNMP
# create session object
my ($session, $error) = Net::SNMP->session(
-hostname => $in_hostname,
-port => $in_port,
-version => $in_version,
-community => $in_community,
# add more parameters if there's a need for them:
# [-localaddr => $localaddr,]
# [-localport => $localport,]
# [-nonblocking => $boolean,]
# [-domain => $domain,]
# [-timeout => $seconds,]
# [-retries => $count,]
# [-maxmsgsize => $octets,]
# [-translate => $translate,]
# [-debug => $bitmask,]
# [-username => $username,] # v3
# [-authkey => $authkey,] # v3
# [-authpassword => $authpasswd,] # v3
# [-authprotocol => $authproto,] # v3
# [-privkey => $privkey,] # v3
# [-privpassword => $privpasswd,] # v3
# [-privprotocol => $privproto,] # v3
);
# on error: exit
if (!defined($session)) {
printf("ERROR: %s.\n", $error);
exit 1;
}
# perform get requests for all wanted OIDs
my $result = $session->get_request(
-varbindlist => [$udpInDatagrams, $udpOutDatagrams]
);
# on error: exit
if (!defined($result)) {
printf("ERROR: %s.\n", $session->error);
$session->close;
exit 1;
}
# print results
printf("udpInDatagrams:%s udpOutDatagrams:%s", # <<< cacti requires this format!
$result->{$udpInDatagrams},
$result->{$udpOutDatagrams},
);
$session->close;
```
It should produce following output, when executed from command line:
```console
[prompt]> perl udp_packets.pl localhost 161 public 1
udpInDatagrams:10121 udpOutDatagrams:11102
```
Where “public” would be replaced by your community string. Those input
parameters again are controlled by the `Input Fields` in Cacti and the output
from the script will be mapped to `Output Fields`. If you wish to return
multiple output values, they must be space delimited name value pairs in the
form of nameA:valueA nameB:valueB ...
## The Data Input Method
To define this script as a **Data Input Method** to Cacti go to **Data
Input Methods** and click the plus (+) glyph.
You should see:
Enter the name of the new **Data Input Method**, select **Script/Command** and
type in the command to call the script. Please use the **full path to the
command interpreter**. Instead of entering the specific parameters, type
`` for each parameter the script needs. **Save**:
Now add each of the input parameters in the **Input Fields** section, one after
the other. All of them are listed in sequence, starting with ``:
``
``
``
We've used some of Cacti builtin parameters. When applied to a host, those
variables will be replaced by the hosts actual settings. Then, this command will
be stored in the poller_command table. Now **Save** your work to see
After having entered all **Input Fields**, let's now turn to the **Output
Fields**, respectively. Add the first one, udpInDatagrams:
Now udpOutDatagrams:
Be careful to avoid typos. The strings entered here must **exactly** match those
spitted out by the script. **Double check Output Fields**! Now, results should
be like
Finally Save and be proud!
## The Data Template
The previous step explained how to call the script that retrieves the data. Now
it's time to tell Cacti, how to store them in RRDfiles. You will need a single
**Data Template** only, even if two different output fields will be stored. RRD
files are able to store more than one output fields; RRDtool's name for those is
**Data Source**. So we will create
1. One single **Data Template** representing one RRDfile
2. Two output fields/data sources
The first step is quite the same as Create the **Data Template** for a simple
**Data Input Method**. For sure, we provide a different name, **Example - UDP
Packets**. Now, let's enter the first **Data Source**. Again, its like above.
But we now provide the name of **udpInPackets**, enter a **Maximum value** of
100,000 and select the **Data Source Type** of COUNTER.
Then save and find with the exception that the *Output Field* will be set to
*None Selected*. Therefore, before adding the second *Data Source Item*, make
sure you select the *Output Field* of *udpInDatagrams* and press the Save button
to create the association.
Then, add the second **Data Source** by pressing the plus (+) glyph and
providing data for *udpOutPackets*. Pay attention to select the correct *Output
Field* defined by the **Data Input Method** as we did with the *udpInDatagrams*.
To deactivate maximum checking, enter 'U', else the desired number. Do not
forget to select the correct *Data Source Type* and the *Output Field* as
before.
## The Graph Template
Most of this task of creating a **Graph Template** has already been covered in
our example. You will basically create a new **Graph Template**, provide a
*Line* or an *Area Fill* followed by a *Legend* for both the *udpInDatagrams*
and *udpOutDatagrams*. The result of those actions will be the image below:
After you have created your **Graph Template** you can proceed to Add the
**Graph Template** to your **Device**, and either allow the automation to create
the **Graph** for you, or to manually add it from the **New Graphs** menu pick.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-Data-Queries.md 0000664 0000000 0000000 00000015321 14124124457 0022022 0 ustar 00root root 0000000 0000000 # How To Work with Data Queries
During the past few weeks as I've made various SNMP Data Query templates I've
ran into a few 'tricks' (which existing user scripts use) to make them work
with most devices. It'd probably be beneficial to publish these in some manner
on the documentation site so others don't have to stumble.
As you already know getting an index is the hardest thing users struggle with.
I've ran across three scenarios and their solutions:
## SNMP index is present
Basically mimic the interface.xml template which comes with Cacti
`(cacti/resource/snmp_queries/interface.xml)`.
SNMPWALK:
```console
Raw OIDs:
.1.3.6.1.2.1.2.2.1.1.1 = INTEGER: 1
.1.3.6.1.2.1.2.2.1.1.2 = INTEGER: 2
.1.3.6.1.2.1.2.1.0 = INTEGER: 2
```
```console
Textual MIB names:
IF-MIB::ifIndex.1 = INTEGER: 1
IF-MIB::ifIndex.2 = INTEGER: 2
IF-MIB::ifNumber.0 = INTEGER: 2
```
In the SNMP XML file, specify the `` and optional
`` fields. For example:
```XML
Get SNMP InterfacesQueries a host for a list of monitorable interfaces.1.3.6.1.2.1.2.2.1.1.1.3.6.1.2.1.2.1.0Indexwalkvalueinput.1.3.6.1.2.1.2.2.1.1
```
A verbose query from inside Cacti shows the following:
```shell
+ Running data query [1].
+ Found type = '3' [snmp query].
+ Found data query XML file at 'C:/Inetpub/wwwroot/cacti/resource/snmp_queries/interface.xml'
+ XML file parsed ok.
+ Executing SNMP walk for list of indexes @ '.1.3.6.1.2.1.2.2.1.1'
+ Index found at OID: 'iso.3.6.1.2.1.2.2.1.1.1' value: '1'
+ Index found at OID: 'iso.3.6.1.2.1.2.2.1.1.2' value: '2'
+ Located input field 'ifIndex' [walk]
+ Executing SNMP walk for data @ '.1.3.6.1.2.1.2.2.1.1'
+ Found item [ifIndex='1'] index: 1 [from value]
+ Found item [ifIndex='2'] index: 2 [from value]
```
## SNMP Index is a STRING
Some devices (like on a F5 BigIP) use a STRING to represent the Index due to
the fact it is user configurable. In this case we need Cacti to parse out the
variable length Index.
Sample of a STRING Index:
Raw OID:
```console
.1.3.6.1.4.1.3375.2.2.10.2.3.1.1.5.76.88.87.69.66 = STRING: "LXWEB"
.1.3.6.1.4.1.3375.2.2.10.2.3.1.1.6.69.80.88.87.69.66 = STRING: "EPXWEB"
```
Textual MIB names:
```console
F5-BIGIP-LOCAL-MIB::ltmVirtualServStatName."LXWEB" = STRING: LXWEB
F5-BIGIP-LOCAL-MIB::ltmVirtualServStatName."EPXWEB" = STRING: EPXWEB
```
Next we need to define a OID/REGEXP that will look for the start of the STRING
and create the Index. In this case the regexp "^.{32}" matches the first 32
characters beginning at the start of the OID -- this is the length of the OID
from the leading dot up to the start of the index. Then the capturing parens
"(.*)" grab the remainder of the OID as a backreference. Use the following SNMP
XML script:
```XML
Get F5 Big-IP Load Balancer Virtual Server Statistics.1.3.6.1.4.1.3375.2.2.10.2.3.1.1OID/REGEXP:^.{32}(.*)vsIndexalphabeticIndexindexinput
```
After creating the Data Query Data & Graph templates in Cacti a verbose query
will spit out the following:
```shell
+ Running data query [20].
+ Found type = '3' [snmp query].
+ Found data query XML file at 'C:/Inetpub/wwwroot/cacti/resource/snmp_queries/f5_bigip_vs.xml'
+ XML file parsed ok.
+ Executing SNMP walk for list of indexes @ '.1.3.6.1.4.1.3375.2.2.10.2.3.1.1'
+ Index found at OID: 'enterprises.3375.2.2.10.2.3.1.1.5.76.88.87.69.66' value: 'LXWEB'
+ Index found at OID: 'enterprises.3375.2.2.10.2.3.1.1.6.69.80.88.87.69.66' value: 'EPXWEB'
+ index_parse at OID: 'enterprises.3375.2.2.10.2.3.1.1.5.76.88.87.69.66' results: '5.76.88.87.69.66'
+ index_parse at OID: 'enterprises.3375.2.2.10.2.3.1.1.6.69.80.88.87.69.66' results: '6.69.80.88.87.69.66'
+ Inserting index data for field 'vsIndex' [value='5.76.88.87.69.66']
+ Inserting index data for field 'vsIndex' [value='6.69.80.88.87.69.66']
```
## SNMP Index does not exist
Some devices do not offer a traditional Index OID to query. Here we need to
create/fake the index for Cacti. This is accomplished once again with a simple
REGEX to split off the last OID (or middle, etc) to create the index for cacti.
SNMPWALK:
Raw OIDs:
```console
.1.3.6.1.2.1.7.1.0 = Counter32: 69367
.1.3.6.1.2.1.7.2.0 = Counter32: 11
.1.3.6.1.2.1.7.3.0 = Counter32: 0
.1.3.6.1.2.1.7.4.0 = Counter32: 64392
```
Textual MIB name:
```console
UDP-MIB::udpInDatagrams.0 = Counter32: 69458
UDP-MIB::udpNoPorts.0 = Counter32: 11
UDP-MIB::udpInErrors.0 = Counter32: 0
UDP-MIB::udpOutDatagrams.0 = Counter32: 64471
```
Consulting the MIB file for these OIDs, we know that the associated index will
always be "0" for each OID. We'll want to split this off with the
REGEX.
Create the following SNMP XML file:
```XML
Get RFC1213 StatsManagement Information Base for Network Management of TCP/IP-based internets.1.3.6.1.2.1.7.2OID/REGEXP:.*\.([0-9]{1,2})$IndexalphabeticIndexindexinput
```
Once all of the required templates have been created, a verbose query from
Cacti results in the following:
```shell
+ Running data query [23].
+ Found type = '3' [snmp query].
+ Found data query XML file at 'C:/Inetpub/wwwroot/cacti/resource/snmp_queries/RFC1213.xml'
+ XML file parsed ok.
+ Executing SNMP walk for list of indexes @ '.1.3.6.1.2.1.7.2'
+ Index found at OID: 'iso.3.6.1.2.1.7.2.0' value: '11'
+ index_parse at OID: 'iso.3.6.1.2.1.7.2.0' results: '0'
+ Inserting index data for field 'Index' [value='0']
```
## A note on Textual SNMP MIBS and SPINE
Please be aware the SPINE does not parse out textual Mibs. This means that if
you were to use an OID that contained a string reference rather than numerical
this will cause Graphs to fail as they will not be generated due to spine not
reciving a value at each poll
Example of a bad OID reference for spine:
```shell
interfaces.mib.1.1.1.1.1
```
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-Determine-Template-Version.md 0000664 0000000 0000000 00000002543 14124124457 0024650 0 ustar 00root root 0000000 0000000 # How To Determine a Cacti Template Version
Users are often bewildered when they are unable to import templates found on
the forum and presented with the error, **Error: XML: Hash version does not
exist**. Cacti prevents templates that have been exported on new versions back
to older versions for compatibility. Quickly looking inside a XML template,
it's not very clear how to determine what version it was created on. There IS
a reason to the madness -- the hash!
Take the following example: ``
The first 2 digits are the type of the template.
The next 4 digits are the Cacti version it was created on.
The next 32 digits are a random number.
## List of Versions
```php
"0.8.4" => "0000",
"0.8.5" => "0001",
"0.8.5a" => "0002",
"0.8.6" => "0003",
"0.8.6a" => "0004",
"0.8.6b" => "0005",
"0.8.6c" => "0006",
"0.8.6d" => "0007",
"0.8.6e" => "0008",
"0.8.6f" => "0009",
"0.8.6g" => "0010",
"0.8.6h" => "0011",
"0.8.6i" => "0012",
"0.8.6j" => "0013",
"0.8.7" => "0014",
"0.8.7a" => "0015",
"0.8.7b" => "0016",
"0.8.7c" => "0017",
"0.8.7d" => "0018",
"0.8.7e" => "0019",
"0.8.7f" => "0020",
"0.8.7g" => "0021",
"0.8.7h" => "0022",
"0.8.7i" => "0023",
"0.8.8" => "0024",
"0.8.8a" => "0024"
```
For the example above, this template was exported with Cacti 0.8.7d.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-Existing-SNMP-Data-Queries.md 0000664 0000000 0000000 00000020711 14124124457 0024364 0 ustar 00root root 0000000 0000000 # SNMP Data Queries
## Walkthrough: A New SNMP Data Query
For SNMP Queries, you won't need to create a data retrieval script. Cacti will
use SNMP to retrieve information. But cacti will need additional information on
how the indexed data is structured. Think about a table (a MIB table in this
case); you'll have to tell cacti about the table structure. This is done by
defining an XML file. Basically, you have to define the index to tell cacti
about the number of rows and about their unique index. This index is later used
to access each rows data. Furthermore, you may define columns, that serve as
**descriptive fields** to be shown in the selection table. The XML file knows
them as
```xml
input
```
You will have to define those fields, that will be queried for the readings,
e.g. ifInOctets, ifOutOctets, ifInErrors, …The XML file knows them as
```xml
output
```
Lets have an example: standard Interface MIB with the corresponding part of the
`/resources/snmp_queries/interfaces.xml` file are displayed using
the following table:
and see the corresponding table structure when defining **New Graphs** for that
**Device** (my laptop):
Now you can map
- Index: IF-MIB::ifIndex
- Status: IF-MIB::ifOperStatus
- Description: IF-MIB::ifDescr
- Type: IF-MIB::ifType
- Speed: IF-MIB::ifSpeed
All those are `input` Parameters. They serve as
descriptive information to each row to help you identify the proper interface to
use. Those parameters of `output` can be compared to
output parameters of a script (see ping.pl script above). These are the readings
from the device. By selecting the appropriate row (the one grayed out had been
selected by me), you tell cacti to retrieve data from the interface defined by
this index. But how does cacti know, what output parameters it shall retrieve?
See the Select a Graph type dropdown. It specifies a **Graph Template** defined
for this Data Query. The Graph Template in turn references a **Data Template**
which incorporates the needed output parameters as Data Sources. This works
quite the same way as defined for a Data Input Method.
To sum up: the SNMP XML file is somehow a **replacement** for the **Data Input
Method** described above to be used on indexed values. It tells cacti, what data
it should retrieve (direction: output). To help you identifying the relevant
indexes, the XML defines descriptive parameters (direction: input) to be
displayed in the selection table.
A walkthrough for this is given now. It is based on the already supplied
interfaces.xml XML file.
## Create a Data Query to tell cacti how to retrieve data
Go to **Data Queries** and click the plus (+) glyph to see:
Here, we are using the already existing interface.xml file. Select **Get SNMP
Data (Indexed)** as **Data Input Method**. Press **Create** to see:
See, that cacti found the XML file. Don't bother with the Associated Graph
Templates at the moment. The success message does not include checking of the
XML file's content. Not lets proceed to the next definitions.
## Create a Data Template to tell Cacti how to store data
This is the exact copy of the definitions made above. So I do not repeat
everything here. **Data Input Method** must be selected as **Get SNMP Data
(Indexed)**. As this data source is a COUNTER type, select this as the *Data
Source Type*. But after saving the new Data Source definition, you may want to
define a second Data Source to the same **Data Template**. To do so, select New
from the *Data Source Item* heading to see:
The name of the internal RRDtool Data Source (ifOutOctets) is not replaced in
the Tab until you save your work. By default, *Maximum Value* is set to 100.
This is way too low for an interface. All readings above this value will be
stored as NaN by RRDtool. To avoid this, set to 0 (no clipping) or to a
reasonable value (e.g. interface speed). Don't forget to specify COUNTER! You
will have noticed, that the name of the data source does not match the Name in
the interface.xml. Don't worry, the solution to this is given later on. Before
leaving, pay attention to the bottom of the page:
This is specific to indexed **Data Queries**. You will have to check the last
three items to make indexing work. All other items should be left alone, there
values will be taken from the appropriate device definitions. Now click **Save**
and you're done with this step.
> Note that if you wish to hand Edit mappings of various indexed interfaces
> manually for each **Graph** in the future, you should check the following
> three fields *Index Type*, *Index Value* and *Output Type ID* as shown below.
> Do this for each **Data Template** *Data Source Items* in the **Data
> Template**.
## Create a Graph Template to tell cacti how to present the data
Since creating a new **Data Query** based upon an existing Data Query called
*SNMP - Interface Statistics* we don't need to create any **Graph Templates**,
we can use the ones created for the other **Data Query**.
### Add Graph Template to the Data Query
Now it's time to re-visit our **Data Query**. Remember the **Associated Graph
Template** we've left alone in the very first step? Now it will get a meaning.
Go to **Data Queries** and select our new one. Then press the plus (+) glyph,
and select *Interface - Traffic (bits/second)* from the drop down as shown
below. Press **Create** to initialize the association of this **Graph
Template** with out new **Data Query**.
Once we press the **Create** button, we should get an image like the one below.
From here, it's important that we associate the *Data Sources* to the XML file
columns that retrieve the data using SNMP. Press the **Save** button to
complete the mapping of *Data Sources* to the XML file *Data Source Output
Values*.
In addition, we need to setup any *Suggested Values* as you can see from the
example below. *Suggested Values* are optional when the **Data Query** can have
a multitude of suggested names based upon the output from the **Data Query**.
For both the *Suggested Values - Graphs* and *Suggested Values - Data Sources*,
we must include the name of the column, and the *Suggested Value* which can
includes the special tag *|query_xmlcolumn|* as shown in the examples below.
Once the **Associated Graph Template** mappings have been completed, you should
see the image below, where we have:
- Mapped the internal **Data Template** *Data Sources* to the XML file *Input
Data Sources*
- Added any *Suggested Values* for the *Graph Title* or other **Graph** fields
- Added any *Suggested Values* for the *Data Source* name or other **Data
Source** fields
Once you have confirmed all the values, you can press **Return** to return to
the **Data Query** page for our Example **Data Query** as shown below.
## Apply the Data Query to your Device
Now go to your **Device** to add the **Associated Data Query**:
Click **Add** and then **Create Graphs for this Host** to see:
Now select the wanted *Interfaces* and press **Create** to generate the Traffic
Graph. As long as there's only one **Associated Graph Template** for that **Data
Query**, there will be no *Associated Graph Type* drop down. Once you create
more than one **Associated Graph Template** for the **Data Query**, you will see
a drop down just above the **Create** button showing the available **Graph
Templates** for the **Data Query** in question, like the *SNMP - Interface
Statistics* as show below.
Pressing the *Set Default* button will set the selected *Graph Type* to be the
default for this **Data Query**.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-New-SNMP-Data-Queries.md 0000664 0000000 0000000 00000044751 14124124457 0023335 0 ustar 00root root 0000000 0000000 # SNMP Data Query Walkthrough
This walkthrough will show you how to implement a new SNMP Data Query.
Assuming, you know the SNMP table, the next steps show how to proceed.
## Building Raw XML File
The starting point will be snmptable for a well know table of the HOSTS MIB:
```console
snmptable -c -v 1 HOST-RESOURCES-MIB::hrStorageTable
SNMP table: HOST-RESOURCES-MIB::hrStorageTable
hrStorageIndex hrStorageType hrStorageDescr hrStorageAllocationUnits hrStorageSize hrStorageUsed hrStorageAllocationFailures
1 HOST-RESOURCES-TYPES::hrStorageOther Memory Buffers 1024 Bytes 1035356 59532 ?
2 HOST-RESOURCES-TYPES::hrStorageRam Real Memory 1024 Bytes 1035356 767448 ?
3 HOST-RESOURCES-TYPES::hrStorageVirtualMemory Swap Space 1024 Bytes 1048568 0 ?
4 HOST-RESOURCES-TYPES::hrStorageFixedDisk / 4096 Bytes 2209331 826154 ?
5 HOST-RESOURCES-TYPES::hrStorageFixedDisk /sys 4096 Bytes 0 0 ?
6 HOST-RESOURCES-TYPES::hrStorageFixedDisk /proc/bus/usb 4096 Bytes 0 0 ?
7 HOST-RESOURCES-TYPES::hrStorageFixedDisk /boot 1024 Bytes 102454 9029 ?
8 HOST-RESOURCES-TYPES::hrStorageFixedDisk /home 4096 Bytes 507988 446407 ?
9 HOST-RESOURCES-TYPES::hrStorageFixedDisk /usr/local 4096 Bytes 507988 17133 ?
10 HOST-RESOURCES-TYPES::hrStorageFixedDisk /var 4096 Bytes 507988 129429 ?
11 HOST-RESOURCES-TYPES::hrStorageFixedDisk /var/lib/nfs/rpc_pipefs 4096 Bytes 0 0 ?**
```
This given, the first step will be the definition of an XML file based on those
OIDs. So change to your `/resources/snmp_queries` directory and
create a file named **hrStorageTable.xml**. You may of course choose your own
name, but for me it seems appropriate to take the name of the SNMP Table
itself. Before doing so, it is necessary to identify the Index of that table.
Without looking at the MIB file, simply perform
```console
snmpwalk -c -v 1 -On HOST-RESOURCES-MIB::hrStorageTable|more
.1.3.6.1.2.1.25.2.3.1.1.1 = INTEGER: 1
.1.3.6.1.2.1.25.2.3.1.1.2 = INTEGER: 2
.1.3.6.1.2.1.25.2.3.1.1.3 = INTEGER: 3
.1.3.6.1.2.1.25.2.3.1.1.4 = INTEGER: 4
.1.3.6.1.2.1.25.2.3.1.1.5 = INTEGER: 5
.1.3.6.1.2.1.25.2.3.1.1.6 = INTEGER: 6
.1.3.6.1.2.1.25.2.3.1.1.7 = INTEGER: 7
.1.3.6.1.2.1.25.2.3.1.1.8 = INTEGER: 8
.1.3.6.1.2.1.25.2.3.1.1.9 = INTEGER: 9
.1.3.6.1.2.1.25.2.3.1.1.10 = INTEGER: 10
.1.3.6.1.2.1.25.2.3.1.1.11 = INTEGER: 11
.1.3.6.1.2.1.25.2.3.1.2.1 = OID: .1.3.6.1.2.1.25.2.1.1
.1.3.6.1.2.1.25.2.3.1.2.2 = OID: .1.3.6.1.2.1.25.2.1.2
```
The first index is `.1.3.6.1.2.1.25.2.3.1.1.1`, but the Index Base is
`.1.3.6.1.2.1.25.2.3.1.1.` This OID is needed for the XML file:
```xml
Get hrStoragedTable InformationGet SNMP based Partition Information out of hrStorageTablehrStorageDescr:hrStorageIndexnumeric.1.3.6.1.2.1.25.2.3.1.1Indexwalkvalueinput.1.3.6.1.2.1.25.2.3.1.1
```
Lets talk about the header elements
Field | Description
--- | ---
Name | Short Name; choose your own one if you want
Description | Long Name
index_order | tells us, which field shall be selected to index on; evaluated from left to right
index_order_type | numeric instead of alphabetic sorting
oid_index | the index of the table
There are more header elements, but for sake of simplification, we'll stick to
that for now.
Lets turn to the fields. They correspond to the columns of the snmptable. For
debugging purpose it is recommended to start with the Index field first. This
will keep the XML as tiny as possible. The `` section contains one or
more fields, each beginning with `` and ending with
``. It is recommended but not necessary to take the textual
representation of the OID or an abbreviation of that.
Field | Description
--- | ---
Name | Short Name
Method | Walk or get (representing snmpwalk or snmpget to fetch the values)
Source | Value = take the value of that OID as the requested value. Sounds ugly, but there are more options that we won't need for the purpose of this example
Direction | Input (for values that may be printed as COMMENTs or the like). Output (for values that shall be graphed, e.g. COUNTERs or GAUGEs).
OID | the real OID as numeric representation
Now save this file and lets turn to cacti to implement this one. First, go to
**Data Queries** to see
and **Add** a new one:
Fill in Short and Long Names at your wish. Enter the file name of the XML file
and don't forget to choose **Get SNMP Data (indexed)**. **Create** to see
It has now **Successfully located XML file**. But this does not mean that there
are no errors. So lets go on with that. Turn to the **Device** you want to
query and add the new **Data Query** as shown:
**Index Count Changed** was chosen on purpose to tell cacti to re-index not
only on reboot but each time the Index Count (e.g. number of partitions)
changed. When done, see the results as
You'll notice, that on my laptop there are 11 indices = 11 partitions. So the
XML worked up to now! To make this clear, select **Verbose Query** to see:
## Insert all descriptive table columns
Now lets put all descriptive table columns into the SNMP Query XML file. This
refers to
- hrStorageType
- hrStorageDescr
- hrStorageAllocationUnits
I like to take the XML field names from the snmptable output, but this is not a
must.
```xml
Get hrStoragedTable InformationGet SNMP based Partition Information out of hrStorageTablehrStorageDescr:hrStorageIndexnumeric.1.3.6.1.2.1.25.2.3.1.1Indexwalkvalueinput.1.3.6.1.2.1.25.2.3.1.1Typewalkvalueinput.1.3.6.1.2.1.25.2.3.1.2Descriptionwalkvalueinput.1.3.6.1.2.1.25.2.3.1.3Allocation Units (Bytes)walkvalueinput.1.3.6.1.2.1.25.2.3.1.4
```
The `` information will later show up as a column heading. Don't
forget to provide the correct base OIDs. Remember, that the **Index** will
always be appended to those OIDs, e.g. the first Description will be fetched
from OID = `.1.3.6.1.2.1.25.2.3.1.3.1` (that is base OID =
`.1.3.6.1.2.1.25.2.3.1.3` together with the appended index `.1` will form the
complete OID `.1.3.6.1.2.1.25.2.3.1.3.1.`
Please notice, that all fields that will yield descriptive columns only take
`input`
If you have completed your work, turn to the cacti web interface and select
your host from the **Devices** list to see:
Select the little green circle next to our SNMP XML to update your last
changes. Then you'll see something like:
When using **Verbose Query**, you'll now find
And clicking **Create Graphs for this host** will result in
You're not supposed to really create graphs at this moment, cause the XML is
not yet complete. And you'll notice, that the second column does not present
very useful information. So it may be omitted in later steps.
## Getting the Output Values
Now lets modify the XML again. As said earlier, the second column is not very
meaningful, so lets drop it. To get the output values, I appended the last two
XML field descriptions, see:
```xml
Get hrStoragedTable InformationGet SNMP based Partition Information out of hrStorageTablehrStorageDescr:hrStorageIndexnumeric.1.3.6.1.2.1.25.2.3.1.1Indexwalkvalueinput.1.3.6.1.2.1.25.2.3.1.1Descriptionwalkvalueinput.1.3.6.1.2.1.25.2.3.1.3Allocation Units (Bytes)walkvalueinput.1.3.6.1.2.1.25.2.3.1.4Total Size (Units)walkvalueoutput.1.3.6.1.2.1.25.2.3.1.5Used Space (Units)walkvalueoutput.1.3.6.1.2.1.25.2.3.1.6
```
This works very much the same way as above.
- Provide the fields hrStorageSize and hrStorageUsed
- Provide a useful name
- Don't forget to specify `output`
- Give the corresponding base OIDs
Now we may proceed as said above: Pressing the green circle runs that XML
definitions against the host and updates the rows/columns. You will notice the
“missing” second column only when Create Graphs for this Host is selected.
---
Note: Don't forget to set `output` for all
variables/fields, that should be stored in RRDfiles and be graphed!. This is
the mistake that occurs most often.
### Defining the Data Template
The Data Template will define, how the data is retrieved by the XML Query is
saved. For more information about the principles of operation, please see
Common Tasks. Please go to **Data Templates** and **Add**:
Define the **Name** of the Data Template. When defining the Name of the **Data
Source**, do not forget to check the **Use Per-Data Source Value (Ignore this
Value)** checkbox. This will come in useful later. Data Input Method will read
**Get SNMP Data (Indexed)**. Select the **Data Source Profile** as usual:
Now to the **Data Source Items**. I like giving them the names of the MIB OIDs,
see:
and **New** or the plus sign on the **Data Source Item** panel.
Now enter the second **Data Source Item**:
Please pay attention to setting the **Maximum Value** to 'U' (no limit). Else, all
values exceeding the pre-defined as **NaN**. Now scroll down to the bottom
of the page and check **Index Type, Index Value and Output Type Id**
**Save** and the **Data Template** is finished.
### Defining the Graph Template
The Graph Template will define, how the data is presented. For more information
about the principles of operation, please see [Common Tasks](Common-Tasks.md).
Please go to Graph Templates and Add:
Fill in the header names and don't forget to check the **Use Per-Graph Value
(Ignore this Value)** for the **Graph Template Title**:
and **Create**.
Now **Add** the first Graph Item as usual:
Add the Legend and the second Graph Item:
Again, add the Legend to end up with
### Revisiting The Data Query
We'll now have to revisit the **Data Query**
**Create**:
Select the correct **Data Sources** and check the boxes on the right. **Save**.
Now fill in some useful **Suggested Values**, at first for the **Data
Template**:
Now apply suggested values for the **Graph Template**:
Now the **Data Query** is complete:
## Create Graphs for this Host
Now we're almost done. Everything's ready for use now. So go to your device and
select **Create Graphs for this Host**. Select some of the partitions you're
interested in:
and **Create** to see:
Lets visit the **Data Sources**:
As you can see, the **Suggested Values** of the Data Query defined the Name of
the Data Template. So lets go to **Graph Management**:
to see the title defined by the **Suggested Values**. When turning to the
**Graphs**, you may see something like
This might be the end of the show. While it should be enough to define some
“easy” SNMP XML based Data Queries, there are some tricks and hints left to
explain.
As you may have noticed, the quantities defined by this example are counted in
Units, not Bytes. This is somewhat inconvenient but may be changed. Lets wait
for the next Section...
### VALUE/REGEXP in Action
As said above, with the current XML size values are measured in **Units**. The
current Unit Size is given by **hrStorageAllocationUnits**, but the reading of
it is like **4096 Bytes**. To use this in any calculations, we must get rid of
the string **Bytes**. This can be done by the **VALUE/REGEXP** Feature of
Cacti's XML definitions. So please change
```xml
Allocation Units (Bytes)walkvalueinput.1.3.6.1.2.1.25.2.3.1.4
```
By
```xml
Allocation Units (Bytes)walkVALUE/REGEXP:([0-9]*) Bytesinput.1.3.6.1.2.1.25.2.3.1.4
```
To prove this, go to your device and again **Verbose Query** our Data Query to see:
Now select **Create Graphs for this Host** and notice the change of the column
**Allocation Units (Bytes)**. The string “Bytes” has gone:
To use these values, we define a CDEF:
Notice, that with recent releases of cacti, it is possible to use `|query_*|`
values within CDEFs. Finally, go to **Graph Templates** and use this CDEF with
all **Graph Items**:
Change the **Base Value** to 1024 for Bytes → kBytes and the y-axis description
to **Bytes**:
Now the Graph looks like
Please find the example resources below. Save `hrStorageTable.xml`
into `./resource/snmp_queries` and import the Graph Template from
`cacti_graph_template_host_mib_hrstoragetable.xml`.
[Cacti Graph Template Host MIB hrStorageTable](resource/xml/cacti_graph_template_host_mib_hrstoragetable.xml)
[hrStorageTable](resource/xml/hrStorageTable.xml) download and store into `resource/snmp_queries`.
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-SSH-Tunnels.md 0000664 0000000 0000000 00000006031 14124124457 0021617 0 ustar 00root root 0000000 0000000 # How To Setup SSH Tunnels to graph a remote Unix server
Howto created by `fmangeant` at [Cacti
Forum](http://forums.cacti.net/viewtopic.php?t=24960)
This HowTo will explain how to use SSH tunnels to graph a Unix server that
isn't directly reachable by your Cacti server :
In this example, the Cacti server can reach the Gateway, which can reach the
target server.
## Configuring the SSH tunnel
On Gateway, create a "cactiuser" user :
```console
# useradd -d /home/cactiuser -m cactiuser
```
Then you have to generate SSH keys (without passphrase) :
```console
# su - cactiuser
$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (/home/cactiuser/.ssh/id_rsa):
Enter passphrase (empty for no passphrase):
Enter same passphrase again:
Your identification has been saved in /home/cactiuser/.ssh/id_rsa.
Your public key has been saved in /home/cactiuser/.ssh/id_rsa.pub.
The key fingerprint is:
40:f6:91:a1:2d:d1:46:d4:76:e3:d8:c6:3f:c2:cf:f2 cactiuser@gateway
```console
The public key of the "cactiuser" user has then to be authorized as an input key :
```console
$ cd $HOME/.ssh
$ cp -p id_rsa.pub authorized_keys
```
Finally, create the SSH tunnel :
```console
# su - cactiuser -c "ssh -f -N -g -L 192.168.0.2:10000:192.168.1.2:161 cactiuser@localhost"
```
This SSH tunnel will forward all packets sent to 192.168.0.2 on TCP port 10000,
to 192.168.1.2 on port TCP 161.
The options that are used are the following :
```shell
-f : requests SSH to go to background just before command execution
-N : do not execute a remote command
-g : allows remote hosts to connect to local forwarded ports
-L : specifies that the given port on the local (client) host is to be forwarded to the given host and port on the remote side.
```
You can add this command to `/etc/rc.local`, so it will be executed at boot time.
## Configuring Net-SNMP
By default, the Net-SNMP agent listens on UDP port 161; we'll modify its
configuration to listen on TCP port 161.
To do so, use that in `snmpd.conf` on the target server :
```ini
agentaddress tcp:161
rocommunity mycommunity
```
For a more detailed configuration of snmpd.conf, follow the [Net-SNMP guide in
the
manual](https://docs.cacti.net/manual:087:1_installation.1_install_unix.4_configure_snmp)
### Testing the SNMP connectivity
From the Gateway host, run this command :
```console
$ snmpwalk -v 1 -c mycommunity tcp:192.168.1.2 sysname
SNMPv2-MIB::sysName.0 = STRING: target_server
```
From the Cacti server, run this command :
```console
$ snmpwalk -v 1 -c mycommunity tcp:192.168.0.2:10000 sysname
SNMPv2-MIB::sysName.0 = STRING: target_server
```
If everything works fine, your host is then ready to be added to Cacti.
If not, review your network configuration (firewall rules, especially).
## Adding the device to Cacti
In Cacti, create a new device like that :
Voila ! Your target server is graphed by Cacti :)
---
Copyright (c) 2004-2021 The Cacti Group
documentation-release-1.2.19/How-To-Script-Data-Queries.md 0000664 0000000 0000000 00000106042 14124124457 0023265 0 ustar 00root root 0000000 0000000 # Script Data Query Walkthrough
Goal of this HowTo will be to show the **principles of writing a Script
Query**, including script, xml and all needed templates. Why should you create
such a thing? Suppose, your target features some indexed readings, that are
**not** available via SNMP but by some other method (e.g. wget/cgi, ssh, NRPE,
…). Writing a Script Data Queries works very much the same way as SNMP Data
Queries. But nevertheless, I'll take you through all of the steps now.
The example uses PHP. Why PHP? First, it's easier to copy stuff from already
existing PHP scripts. Second, it would be possible to use cacti functions. It
should be possible to imagine, how this works with other programming languages.
Strictly speaking, I'm not that PHP expert. So be patient with me.
Please pay attention. This HowTo will not explain how to write a **Script
Server Data Query** (yes, there is such a thing!). It would not introduce that
many changes. But this will be left to some other HowTo.
Personally, my primary goal was to use an example, that all users should be
able to copy to execute each and every step on its own. Unfortunately, there
seems to be no example, that is common enough and interesting at the same time.
So I'm sorry to announce, that this HowTo will show “Interface Traffic Data
Gathering”. Yes, I know, this is not that new. And surely, it will not be as
fast as pure SNMP. So, to my shame, I suppose that this will never make it into
any production environment. But, again, this is not the primary goal.
Before starting the work, I feel encouraged to point out a drawback of this
approach. Cacti will start a PHP instance, each time it has to fetch a value
from the target device. This is not that fast, obviously. And it will not
prosper from the performance boost when switching over from cmd.php to Spine.
Of course, even Spine will need to start php! And that's exactly, where the
thingy called **Script Server Data Query** drops in. But let's leave this for
the next main chapter.
The code runs on Cacti 0.8.7 versions.
## Basic Script
The starting point will be some very basic php script. Put it into
`/scripts/query_interface_traffic.php`. It will show interface
indices only for the given target host. The script takes two parameters as
input, the **hostname** of the target and the string **index**. You have to
implement the **index method**, as OO programmers would say. In this case,
there's an “if” clause to process index requests. Output is a list of indices,
each one on a separate line.
```php
'.1.3.6.1.2.1.2.2.1.1',
);
$xml_delimiter = '!';
# all required input parms
$hostname = $_SERVER['argv'][1]; # hostname/IP@
$cmd = $_SERVER['argv'][2]; # one of: index/query/get
# put your own community string here
$snmp_community = 'public'; # community string
$snmp_version = 1; # snmp version
$snmp_port = 161; # snmp port
$snmp_timeout = 500; # snmp timeout
$snmp_retries = 3; # snmp retries
$max_oids = 1; # max oids for V2/V3 hosts
# required for SNMP V3
$snmp_auth_username = '';
$snmp_auth_password = '';
$snmp_auth_protocol = '';
$snmp_priv_passphrase = '';
$snmp_priv_protocol = '';
$snmp_context = '';
# -------------------------------------------------------------------------
# main code starts here
# -------------------------------------------------------------------------
# -------------------------------------------------------------------------
# script MUST respond to index queries
# the command for this is defined within the XML file as
# index
# you may replace the string 'index' both in the XML and here
# -------------------------------------------------------------------------
# php -q