Difference between revisions of "Freeside:4:Documentation:Cacti"

From Freeside
Jump to: navigation, search
m (Connecting Cacti To Freeside)
(Connecting Cacti To Freeside)
 
(7 intermediate revisions by the same user not shown)
Line 7: Line 7:
  
 
In the regular Cacti interface, create a Host Template to be used by  
 
In the regular Cacti interface, create a Host Template to be used by  
devices exported by Freeside, and note the template's id number.  Optionally,
+
devices exported by Freeside, and note the template's id number.  Make sure
create a Graph Tree for these devices to be automatically added to, and note
+
the Host Template has Associated Graph Templates and Data Queries for
the tree's id number. Configure a Graph Export (under Settings) and note  
+
any graphs you wish to automatically generate.  Create a Graph Tree for  
the Export Directory.
+
new devices to be automatically added to, and note the tree's id number.
 +
Configure a Graph Export (under Settings) and note the Export Directory.
  
 
In Freeside, go to Configuration->Services->Provisioning exports to
 
In Freeside, go to Configuration->Services->Provisioning exports to
 
add a new export.  From the Add Export page, select cacti for Export then enter...
 
add a new export.  From the Add Export page, select cacti for Export then enter...
  
* the Hostname or IP address of your Cacti server
+
* Hostname or IP - of your Cacti server
  
* the User Name with permission to run scripts in the cli directory
+
* User Name - with permission to run scripts in the cli directory
  
* the full Script Path to that directory (eg /usr/share/cacti/cli/)
+
* Script Path - full path to that directory (eg /usr/share/cacti/cli/)
  
* the Host Template ID for adding new devices
+
* Host Template ID - for adding new devices
  
* the Graph Tree ID for adding new devices (optional)
+
* Graph Tree ID - to which the host will be added
  
* the Description for new devices; you can use the tokens $ip_addr and $description to include the equivalent fields from the broadband service definition, or $contact to use the customer's contact name
+
* Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer
  
* the Graph Export Directory, including connection information if necessary (user@host:/path/to/graphs/)
+
* Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)
  
* the minimum minutes between graph imports to Freeside (graphs will otherwise be imported into Freeside as needed.) This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.
+
* Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this.  This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.
  
* the maximum size per graph, in MB; individual graphs that exceed this size will be quietly ignored by Freeside.  Defaults to 5 if unspecified.
+
* Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside.  Defaults to 5 if unspecified.
 +
 
 +
* Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved.  Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)
 +
 
 +
* Path to cacti include dir (relative to script_path) - optional, defaults to ../site/include/ if unspecified, might need to be changed to ../include/ if you installed cacti from source
 +
 
 +
Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page.  See [http://www.cacti.net/downloads/docs/html/cli_add_graphs.html cacti add_graphs documentation] for details on these fields.  You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.
  
 
After adding the export, go to Configuration->Services->Service definitions.
 
After adding the export, go to Configuration->Services->Service definitions.
Line 41: Line 48:
 
When properly configured broadband services are provisioned, they will now
 
When properly configured broadband services are provisioned, they will now
 
be added to Cacti using the Host Template you specified.  If you also specified
 
be added to Cacti using the Host Template you specified.  If you also specified
a Graph Tree, the created device will also be added to that.
+
a Graph Tree, the created device will also be added to that.  Graphs will be
 +
generated for each graph template you specified, as well as any you explicitly
 +
configured.
  
 
Once added, a link to the graphs for this host will be available when viewing  
 
Once added, a link to the graphs for this host will be available when viewing  
Line 49: Line 58:
 
and they will be deleted and re-added if the ip address changes.
 
and they will be deleted and re-added if the ip address changes.
  
Currently, graphs themselves must still be added in Cacti by hand or some
+
==Troubleshooting==
other form of automation tailored to your specific graph inputs and data sources.
+
 
 +
After a device is provisioned, the graphs won't show up until the next time the
 +
cacti server runs its poller and exports the graphs;  by default, this is every
 +
five minutes.  If you try to view the graphs in this window, it will say they don't
 +
exist.
 +
 
 +
When upgrading a freeside server that uses this export, make sure to check that
 +
the most recent freeside_cacti.php file is copied into the script directory
 +
on the cacti server.
 +
 
 +
==Known Issues==
 +
 
 +
Currently does not support non-ASCII characters in Description, and apostrophes will be removed
 +
 
 +
Currently does not support graph-title in graph generation (specify title in template instead)
 +
 
 +
Currently does not support graphs that require custom input-fields
 +
 
 +
Currently does not support specifying reindex-method for graphs from Data Queries

Latest revision as of 01:06, 24 November 2015

Connecting Cacti To Freeside

Copy the freeside_cacti.php script from the bin directory of your Freeside installation to the cli directory of your Cacti installation. Give this file the same permissions as the other files in that directory, and create (or choose an existing) user with sufficient permission to read these scripts.

In the regular Cacti interface, create a Host Template to be used by devices exported by Freeside, and note the template's id number. Make sure the Host Template has Associated Graph Templates and Data Queries for any graphs you wish to automatically generate. Create a Graph Tree for new devices to be automatically added to, and note the tree's id number. Configure a Graph Export (under Settings) and note the Export Directory.

In Freeside, go to Configuration->Services->Provisioning exports to add a new export. From the Add Export page, select cacti for Export then enter...

  • Hostname or IP - of your Cacti server
  • User Name - with permission to run scripts in the cli directory
  • Script Path - full path to that directory (eg /usr/share/cacti/cli/)
  • Host Template ID - for adding new devices
  • Graph Tree ID - to which the host will be added
  • Description - for new devices. You can use the tokens $ip_addr, $description and $contact to include the equivalent fields from the broadband service definition or associated customer
  • Graph Export Directory - as configured, including connection information if necessary (user@host:/path/to/graph/export/)
  • Minimum minutes between graph imports - graphs will be imported from the export directory into Freeside as needed, but not more often than this. This should be at least as long as the minumum time between graph exports configured in Cacti. Defaults to 5 if unspecified.
  • Maximum size per graph - in MB. Individual graphs that exceed this size will be quietly ignored by Freeside. Defaults to 5 if unspecified.
  • Delete associated graphs and data sources when unprovisioning - if this is unchecked, only host will be deleted, but graphs and data sources will be preserved. Note that this deletion process does not use official cacti api, but rather queries the cacti database directly; test before deploying (developed & tested on cacti 0.8.8a)
  • Path to cacti include dir (relative to script_path) - optional, defaults to ../site/include/ if unspecified, might need to be changed to ../include/ if you installed cacti from source

Basic graphs will automatically be generated for each Graph Template associated with the Host Template, but if you want to add graphs based on associated Data Queries, you will have to specify their inputs explicitly at the bottom of this page. See cacti add_graphs documentation for details on these fields. You can also specify additional Graph Templates here for basic graph generation, just leave the SNMP fields blank.

After adding the export, go to Configuration->Services->Service definitions. The export you just created will be available for selection when adding or editing broadband service definitions; check the box to activate it for a given service. Note that you should only have one cacti export per broadband service definition.

When properly configured broadband services are provisioned, they will now be added to Cacti using the Host Template you specified. If you also specified a Graph Tree, the created device will also be added to that. Graphs will be generated for each graph template you specified, as well as any you explicitly configured.

Once added, a link to the graphs for this host will be available when viewing the details of the provisioned service in Freeside.

Devices will be deleted from Cacti when the service is unprovisioned in Freeside, and they will be deleted and re-added if the ip address changes.

Troubleshooting

After a device is provisioned, the graphs won't show up until the next time the cacti server runs its poller and exports the graphs; by default, this is every five minutes. If you try to view the graphs in this window, it will say they don't exist.

When upgrading a freeside server that uses this export, make sure to check that the most recent freeside_cacti.php file is copied into the script directory on the cacti server.

Known Issues

Currently does not support non-ASCII characters in Description, and apostrophes will be removed

Currently does not support graph-title in graph generation (specify title in template instead)

Currently does not support graphs that require custom input-fields

Currently does not support specifying reindex-method for graphs from Data Queries