Cacti (home)ForumsDocumentation

Differences

This shows you the differences between two versions of the page.

manual:100:6_reference.4_cli_script.6_add_device [2009/02/21 16:53] (current)
Line 1: Line 1:
 +==== 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
 +
 +<code>shell>php -q add_device.php --help
 +
 +Add Device Script 1.0, Copyright 2007 - 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</code>
 +
 +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 ===
 +
 +<code>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</code>
 +
 +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//, please provide the parameter //--template=0// or omit this parameter.
 +
 +=== List all Community Strings ===
 +
 +<code>shell>php -q add_device.php --list-communities
 +
 +Known communities are: (community)
 +
 +public
 +snmp-get</code>
 +
 +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
 +
 +<code>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)</code>
 +
 +Please visit //Devices// to see the result:
 +
 +<code>Description** Graphs Data Sources Status Hostname Current (ms) Average (ms) Availability
 +Device Add Test 0 0 Unknown router.mydomain.com 0 0 100</code>
 +
 +Please 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.





Personal Tools