The Cacti Manual
Prev | Chapter 20. Command Line Scripts | Next

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

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)

    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

    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)

Please visit 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

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.

Prev | Home | Next
Copy Local Cacti Users | Up | Add a New Graph