Inventory is distributed as a gzipped, tar file containing one or more virtual machine images. There are three roles which always exist. Based on sizing though more than one role may be installed on a particular virtual machine.

The three roles are:


  1. Use "tar -xzf " to unpack the downloaded file. This will produce one or more very large files which are either OVA or qcow2 formated virtual machine images. KVM formatted files include a second file for each of the machine specifications.
  2. Import these images into your existing VMware or KVM based systems. This is where placement becomes important.
  3. Turn them all on
  4. Make whatever changes you need to, including informing the system of its serial number
  5. Point a browser at Web. Enter the set of credentials to use, and a few seeding targets
  6. Click Scan
  7. In less than 1 hour you should have a fully populated CMDB

Placement of roles on your network

Web is the core role. This is the one that needs outbound access to the Internet, and is your primary point of interaction with the system. All the other roles depend on Web. There is no inbound need from the Internet for the Web role. It just needs to be able to get to from where it is. This conversation was deliberately left unencrypted so that you can see what is going on if you want to. When Web "calls home", it reports the total number of devices it has in the CMDB, and then downloads an update if one is needed.

Database is what it is. Feel free to load the MySQL client software onto your machine(s) and just connect to this resource. It's your data. Use it.

Inv is the tricky one typically. If you have jump hosts in play, where you log into a jump host to then log into a networking device, then the Inv role needs to be where the jump hosts are. If you have a fully isolated management network, then you will need to configure the virtual machine running the Inv role to have two ethernet interfaces, again just like your jump hosts have in this situation. If you are inventorying servers as well as networking gear, then you will likely need to run multiple virtual machines running the Inv role. You can run as many Inv machines as you like. There is no licensing limit here.

Let's talk about having multiple Inv machines running

In the default case, all Inv machines are equal and thus any machine can process any item in the scan queue.
If that isn't the case, say where you have one Inv setup to scan servers and the other to scan networking gear, then these can't process each others targets. This is "Segmented" mode. More on that later.

Once you have the virtual machines placed and they are running, you now need to inform the system of its serial number

How to inform Inventory of its Serial number

Inventory reports its assigned IP address to the console screen. You can use any browser to inform the system of the serial number. You can only give the serial number via this method. You cannot change IPs, or invoke segmented mode.

Your other option involves a USB drive, formatted as any Linux native format (FAT typically). You will place a single file named ‘inventory.conf’ in the root directory. If there is anything else on the drive it won’t matter and it won’t be read or searched. The program just looks for that one particular file and if it exists then its contents are read and adjustments to the system are made. This is the only mechanism you have to influence how the system behaves. All lines in this file follow the same format. This is a simple <name>=<value> format. No spaces please.


This is the one thing you must do. Make the file with just the line:
SERIAL=<Your serial number>

Attach the USB drive to the running VM. The VM will notice the insertion, mount the drive, look for that file, open it if it exists and apply the changes listed. It will then eject the drive. The whole thing takes about 10 seconds.

You only need to do this step to the Web VM. When you do this Web will immediately attempt to download<Its serial number>.tgz. This is the file that contains all of the unique personality for your installation. Among other things this is all the passwords. Its also all the actual data needed to make the system work. What you downloaded was essentially a functional but blank machine that is identical to every other machine downloaded.

Internal Communication between machines

The web machine is both an NFS server and a CIFS server. All of the other machines mount "\shared" via NFS. You can mount that same shared folder via CIFS, also called "shared". This is a guest-only, public share via workgroup “AUNC”. The reason we did this is because in this share is a text file for every conversation any of the Inv instances had with any target. The file names are nothing more than the IP addresses used to connect to the target. If you ever want to see what is happening, or if you think something has gone awry you can look at these files and see the actual conversation itself.

A note about the CIFS share

If you use the net command as in:
net use * \\<IP address>\shared
Often you will get a prompt to login. You can type in anything. It doesn't matter what you type. The net command will complete successfully. This seems to be a windows setting as we couldn't replicate it realiably. Web is not asking for credentials and will allow anyone to connect.

If any machines are adjacent to the web machine, they will find it using a connection attempt to port 65535 at the subnet broadcast address. The web server replies with its actual information which is then loaded into the local /etc/hosts file. Similarly for the DB but using port 65534 instead.

If the machines are not adjacent to the web machine, then you will need to tell them what address things are at.

Add the following lines to the inventory.conf file. The two that every machine needs to know are:
WEB=<IP address of Web machine>
DB=<IP address of database machine>

In the case of a “Small” installation, these would be the same IP address. They still both need to be listed.

IP Addressing of the machines

All machines will use DHCP to obtain an address by default. If you want to statically assign an IP address to a machine, the inventory.conf file is how you do that. If the machine has multiple ethernet interfaces, you can only assign an address to the lowest numbered interface. The others will remain DHCP and cannot be changed.

To set an IP you need two lines. These will change for every machine. The lines to use are as follows:
ADDR=<IP address of machine>/<maskbits>
ADDR=<IP address of machine> <netmask>
DEFGW=<Default Gateway IP address>

Note that the second form of the ADDR field, using the netmask, is the only format where a space is allowed.
If you are assigning addresses, then you most likely will need to specify the WEB= and DB= lines above.

Firewall Rules Needed

If the machines are not adjacent to the web machine, and there is a firewall between them then the following will need to be allowed:
Destination Web:

	http - TCP 80
	https - TCP 443
	rpc-bind - TCP/UDP 111
	nfs - TCP/UDP 2049
	mountd - TCP/UDP 20048
	samba - UDP 137-138, TCP 139, TCP 445
This is also the machine which must be able to reach the Internet. Outbound only and only to We don't even use DNS.

Destination DB:
	mysql - TCP 3306

Segmented Mode

There is an option in the inventory.conf file as follows:

The file applied to all machines in this instance needs to contain the "segemented=yes" option. Only the Inv role machines use the "segment=" line. Your segment names are as follows, "1", "2", "3", etc. No you cannot change the segment names.
In segmented mode the web server includes a segment ID field in the Targets page. Its up to you to keep which targets go to which Inv segment number sane. The system is going to do whatever you tell it to do. Inv machines in this situation will only process scan targets with their segment ID, the number given in the "segment=" line of the applied inventory.conf file.

Things to Note

The Inv machine has no open ports. It responds to ping only. It is a client of both Web and DB.
Similarly you will note that none of the machines accept SSH on any port. That's because you don't ever log into these. Your only access is via the console, and we didn't give you a valid login to do that. Again, your only form of influence is the inventory.conf file.

We decided very late in the process to keep the debugging output enabled in Inventory. You can see this from the Inv console connection if you flip the console to TTY 2. [CTRL+ALT+F2] You can actually watch the automatons do their work, and the speed is mostly readable.