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

shell>php -q add_device.php --help

Add Device Script 1.0, Copyright 2004-2013 - 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=]

    --description  the name that will be displayed by Cacti in the graphs
    --ip           self explanatory (can also be a FQDN)
    --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:
    --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

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, please provide the parameter --template=0 or omit this parameter.

List all Community Strings

shell>php -q add_device.php --list-communities

Known communities are: (community)


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, 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

shell>php -q add_device.php --description="Device Add Test" --ip="" --template=3 --community="public"

Adding Device Add Test ( as "ucd/net SNMP Host" using SNMP v1 with community "public"
Success - new device-id: (11)

Please visit Devices to see the result:

Description** 		Graphs 	Data Sources 	Status 	Hostname 		Current (ms) 	Average (ms) 	Availability
Device Add Test 	0 	0 		Unknown 	0 		0 		100

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.