|
This document describes the use of the inventory system introduced in November 2008.
Three talks were given on the background of the inventory system that was the outcome of the Inventory System project:
N.B.The above talks did not describe the final version of systems implemented. The notes below describe these more accurately.
The inventory data is held within the Informatics database as a set of tables (order, item, system, location, hostname etc) - the inventory cluster tables (see also the cluster diagram). Much of this data is maintained automatically by processes that feed data from various sources into the Informatics database.
The data that cannot be maintained automatically needs to be maintained by hand using the commands supplied by the dice-invtools rpm; these are currently the invquery and invedit commands.
Both of these commands make us of an encrypted dbiproxy (A proxy server for the perl DBD::Proxy driver) connection to the database server from the client on which the command is run. For this reason the commands are only available on those hosts that have been set up to talk to the Informatics database server, that is the hosts that include the infdb-client.h header
To set up a host to use the invquery and invedit commands do the following:
_DBIPROXY_ADD(<hostname>,<uun> INVQUERY )
wait for the configuration of dbiproxy on the Informatics database server to change (check /var/lcfg/log/dbiproxy) and restart the dbiproxy daemon:
om dbiproxy restart
this will allow the invquery perl script to connect to the Informatics database server as the database user invquery (and also allow the database user with uun <uun> to run the invedit perl script from host <hostname>).
N.B. In order for a user to use the invedit command in their own right they must have a database account set up on the Informatics database server, and have the appropriate database permissions set for querying and updating the inventory cluster tables.
The options that can be used with the inventory tools invquery and invedit are long options prefixed by a double dash --. The option names are descriptive and long rather than cryptic and short, however in supplying the options one only needs to type the shortest unambiguous start of the option string.
In the examples below the full option names are given but it is not necessary to use the full names in practice.
The --host options to the invquery and invedit commands and the --name option for the invedit command take hostnames as arguments. The two commands use the gethostbyname routine to convert these arguments into fully qualified domain names. As a consequence it is not necessary to use the FQDN hostname when supplying these arguments. For example tickle.inf.ed.ac.uk can be shortened to just tickle, and 3w0.f.net.inf.ed.ac.uk can be shortened to 3w0.f.net in the supplied argument. However be careful not to shorten the name if the shortened name is in itself a valid FQDN; so at3b.at.net.inf.ed.ac.uk can not be shortened to at3b.at.net because the latter is itself a valid FQDN.
The primary use of the invquery command is to retrieve data from the Informatics database on host systems. The typical use is to query the database for data on a specific host:
invquery --host <hostname>
e.g.
% invquery --host tickle
tickle.inf.ed.ac.uk is a Dell Optiplex GX620 made by Dell.
Its serial no. 4R1VB2J and 'primary' MAC address is 00:13:72:d4:44:8e.
It is running OS sl5, release develop/unmanaged.
It is allocated to ktd (Ken Dawson) and located in IF-1.12.
It is managed by ktd, and owned by informatics.
Warranty is 3 years nbd educational support from 05/07/2006.
It was ordered off budget 747DIV/G40588,40522 from Dell
on order number A636554 and cost £528.
The command may be used to retrieve inventory data on all current hosts:
invquery --currenthosts
The data is returned using a different default formatting more suitable for reporting data on a large number of systems (in CSV format). To override the format of the per-host data retrieved one can specify a template for the data, for example:
% invquery --currenthosts --template '"%h","%s","%b-%r"%n'
"miehle.inf.ed.ac.uk","NLEW244913","IF-B.03"
"urquhart.inf.ed.ac.uk","CK212HOLM1X","IF-B.03"
"canongate.inf.ed.ac.uk","JNGSG3J","IF-2.54"
....
"koberger.inf.ed.ac.uk","NL7T092694","IF-B.03"
"5m3.f.net.inf.ed.ac.uk","CN805ZU058","IF-5.Z22"
"pchmanurun.inf.ed.ac.uk","29KVZ0J","IF-4.25"
The default format for this option is:
'"%h","%k","%m","%p","%s","%M","%o","%a","%f","%l","%b","%r","%g","%O","%w","%W","%F","%S","%N","%c","%C"%n'
See the template option below for an interpretaion of this and other formats and for further details.
Another important use of the command is to retrieve data on inventory items which may or may not be computer systems. To query the database for data on an item with a specific serial number:
invquery --serial <serial-number>
Here is an example of a query in which the item is not a computer system:
% invquery --ser L01238
Item with serial no. L01238 is a PH5138/001 made by Philips
located in FH-.
Warranty is from 01/06/1990.
It was ordered from on order number A131894 and cost £2400.
If the serial number supplied is that of a computer system then system specific information is also returned:
% invquery --serial 4R1VB2J
Item with serial no. 4R1VB2J is a Dell Optiplex GX620 made by Dell
located in IF-1.12.
Warranty is 3 years nbd educational support from 05/07/2006.
It was ordered from Dell on order number A636554 and cost £528.
It is part of host tickle.inf.ed.ac.uk allocated to ktd (Ken Dawson)
which has 'primary' MAC address 00:13:72:d4:44:8e, is owned by informatics,
is running OS sl5, release develop/unmanaged and is managed by ktd.
The command may be used to retrieve inventory data on all non-disposed of items:
invquery --items
or on all items whether disposed of or not:
invquery --all
The data is returned using a different default formatting more suitable for reporting data on a large number of systems (in CSV format).
The default format for these latter two options is:
'"%k","%m","%p","%s","%b","%r","%O","%w","%W","%F","%S","%N","%c","%C","%h","%M","%o","%a","%f","%l","%g"%n'
See the template option below for an interpretation of this and other formats and for further details.
A secondary use of the invquery command is to query the Informatics database for information on the known rooms and sites recorded in the database, for example:
invquery --room --site if
will return a table detailing information on the rooms in the Informatics Forum site, and
invquery --building
will return a list of known sites (buildings) showing their key and name.
The --template option of the invquery command can be used to control what inventory details are reported and in what format. The --template option can be used together with the --host, --currenthosts, --serial, --items or --all options. The --template option takes a string argument which can contain certain special patterns or macros that will be replaced by corresponding data for each host or item reported on. The macros are:
| Macro | Expanded To |
|---|---|
| %h | hostname |
| %m | model |
| %s | serial number |
| %M | MAC address |
| %o | operating system |
| %a | UUN of person to whom host is allocated |
| %f | first name of person to whom host is allocated |
| %l | last name of person to whom host is allocated |
| %b | building or site code where the host is |
| %r | room or space code where the host is |
| %g | manager |
| %O | Owner |
| %w | warranty |
| %W | Warranty date |
| %S | Supplier |
| %N | order Number |
| %c | cost |
| %k | maker |
| %d | disposal method |
| %D | Disposal date |
| %p | description |
| %F | Funding source |
| %C | Comment |
| %n | newline |
| %t | tab |
The invedit command is used to update inventory information in the Informatics database about a computer system or some other piece of equipment. It can be used to update the location of any item and the manager, operating system and hostname of any computer system and which person the system has been allocated to.
The invedit command will take your database passwd from the shell environment if you have used the ampenv command or will prompt for the password. If you choose to use the ampenv command there is no need to supply your kerberos admin principle password when that command prompts you for it.
Pieces of equipment can be specified by providing their serial number using the --serial option to the command. Networked systems can be specified by either providing their serial number as described above or by providing their current hostname using the --host option to the command (note however that if defining the initial hostname or new hostname for a networked system then one must specify the system in question using the --serial option).
In general one can update several pieces of inventory information for the same equipment or system in a single command even though, for the sake of simplicity, in many of the examples below only one piece of information at a time is updated.
Because for certain types of equipment several of the inventory details are maintained automatically by other processes using data from other sources it is not necessary to use invedit to maintain that data manually. The data that needs to be maintained manually is described in the following table:
| DICE host in server room | DICE host not in server room | Switches and Other hosts in server room | Other hosts not in server room | Equipment not attached to the network | |
|---|---|---|---|---|---|
| Location | Yes | No | Yes | No | Yes |
| Allocated | Yes | Yes | N/A | ||
| Manager | Yes | Yes | Yes? | ||
| Initial Hostname | No | Yes | N/A | ||
| Changed Hostname | Yes | Yes | N/A | ||
| Operating System | No | Yes | N/A | ||
| MAC address | No | Yes | N/A | ||
| Disposal | Yes | Yes | Yes | ||
From the table above it can be seen that for DICE machines that are not in the server room all that is normally necessary to set manually is the manager and allocated information. This would be done with a command like the following:
invedit --host cocklepub --manager support-team --allocated mc
which would update the system with hostname cocklepub to be managed by support-team and allocated to user with UUN mc.
In the examples below the system is sometimes specified by the serial number of the system. This may be because the hostname is not set yet, will not ever be set or is not known.
To update the location of a piece of equipment or system one uses the --building and --room options, for example:
% invedit --serial 4R1VB2J --building if --room 1.12
or
% invedit --host tickle --building if --room 1.12
The values used as arguments must be recognised site and room values. If these values are not known then use the invquery command to find out.
Special site and room values that can be used are for an unknown location:
% invedit --serial 999XRF8 --building unkn --room -
or
% invedit --host rocks --building unkn --room -
and for the home of the person to whom the equipment has been allocated:
% invedit --serial 999XRF8 --building home --room -
or
% invedit --host rocks --building home --room -
To update the person who has been allocated a system one uses the --allocated option, for example:
% invedit --host tickle --allocated ktd
or
% invedit --serial 4R1VB2J --allocated ktd
N.B. A host can only be allocated to a person (not a group or use); the person is specified by their UUN.
If a system had been allocated to a person but is now to be unallocated then use the special argument value unallocated, for example:
% invedit --host tickle --allocated unallocated
or
% invedit --serial 4R1VB2J --allocated unallocated
and this will set the allocated field to the NULL value and set the manager field to unallocated.
If a system is too old to be managed and it is to be disposed of in the not too distant future then use the special argument value JUNK, note the upper case to avoid any possible clash with a uun value of junk, for example:
% invedit --host rubislaw --allocated JUNK
or
% invedit --serial G9XL50J --allocated JUNK
and this will set the allocated field to the NULL value and set the manager field to junk.
To update the manager of a system one uses the --manager option, for example:
% invedit --host bunbury --manager support-team
or
% invedit --serial CZC5301029 --manager support-team
The manager field can be any non-empty string value.
To set the initial hostname of a system (an item of networked equipment) or to change the hostname of an existing system one uses the --name option, for example:
% invedit --serial SG751KJH78 --name 3w0.f.net
The name field is a string that will resolve to the appropriate FQDN.
To update the operating system of a computer system one uses the --os option, for example:
% invedit --host canna --os 'MDP WindowsXP-Pro'
or
% invedit --serial GVJ4M0J --os 'MDP WindowsXP-Pro'
The os field can be any non-empty string value.
To update the comment associated with a computer system or piece of equipment one uses the --comment option, for example:
% invedit --host patriol --comment 'random hardware problems.'
or
% invedit --serial HF0ZB2J --comment 'random hardware problems.'
The comment field can be any string value (including an empty string).
To set the MAC address of a system (an item of networked equipment) that does not already have a MAC address set one uses the --mac option, for example:
% invedit --host canna --mac 00:07:e9:cc:65:6e
or
% invedit --serial GVJ4M0J --mac 00:07:e9:cc:65:6e
The mac field is colon-delimited octets in hexadecimal form (the value will be stored in lower case but can be supplied in lower, upper or mixed case).
To record that a piece of equipment has been disposed of one uses the --disposal option, for example:
% invedit --serial BGMQL0J --disposal
The date of disposal is by default today's date and the disposal method is by default set to the value 'WEEE recycling'.
To set a different date for the disposal also use the --ddate option, for example:
% invedit --serial BGMQL0J --disposal --ddate 2008-05-15
The ddate field must be in yyyy-mm-dd format or it will be silently ignored.
To set a different disposal method also use the --dmethod option, for example:
% invedit --serial 1234567 --disposal --ddate 2007-11-21 --dmethod 'Stolen'
One of the goals of the design of the new inventory system was to maintain the accuracy of the inventory data as efficiently as possible by automatically updating the inventory data in the Informatics database from other sources of the data where one could be fairly confident that those sources were accurate.
The sources used were the details of the orders as created and maintained by the Computing Support Officer responsible for orders, information reported by DICE clients themselves and information from the network switches concerning the MAC addresses that they had detected on the switch ports.
Another goal of the new inventory system was to master as little as possible of the inventory data in the LCFG profiles. The inventory data is now held primarily in the Informatics database. The data is now exported to the LCFG profiles via generated header files.
When a new order is created or an existing one updated, processes are automatically run that transfer the data to the Informatics database. When an order file is created or edited, the customtoxml script is run to make a translation of the order into a standard XML format of the order and then the xmltoinfdb script is run to synchronise the data in that XML file with the corresponding data in the Informatics database (see diagram).
The above processes create a new record in the order table when a new order is created and a new record in the item table for each item in the order (note that if an order contains just one line that orders 100 computers of the same specification say, then 100 records will be created in the item table).
When the serial numbers are known and are added to the order file then the item records corresponding to the line of the order for which the serial numbers are known are updated with the serial numbers. If the maker and description fields for an item of an order match any of a set of patterns held in the rfe-maintained systems file then a system table record will also be created for each item with a serial number and a part record linking the corresponding records in the item table and the system table (see diagram).
When equipment is delivered the order is updated with the date of delivery and this is similarly updated in the corresponding records of the item table.
The LCFG profile of a newly installed DICE client will have the MAC address of the client but should not contain any other inventory information. As a DICE client is being installed it will run the clientreport script as a post-install script for the dice-orders-clientreport rpm and then twice a day from cron thereafter. The script reports back to the ordershost various information including its hostname, serial number and model (from the PROM), operating system from /etc/redhat-release and primary MAC address from the value of the LCFG resource dhclient.mac.
In order to quickly grab the data for newly installed clients every ten minutes during office hours the clientreporttoinfdb script is run on the Informatics database host infdb. It is run by the pseudo-user daidb from cron. This script reads the contents of the clientreport table on the ordershost where all the data reported back from the DICE clients is held. For each client listed in that table the clientreporttoinfdb script associates the hostname with the sytem with the corresponding serial number and creates a hostname table record, containg the hostname and operating system values linked to the system table record of the corresponding serial number (unless one already exists). It also sets the MAC address in the system table record of the corresponding serial number (unless already set) and the model in the item table (see diagram).
The network switches keep a record of which MAC addresses are seen on which network ports. A summary of this data is maintained automatically by scripts written by the Infrastructure Unit. This data is accessible for each site and in particular for the Informatics Forum and the Appleton Tower
Twice a day, for each of Forum and Appleton Tower sites, the switchtoinfdb script is run on the Informatics database host infdb. It is run by the pseudo-user daidb from cron. This script reads the contents of the one or other of the above-mentioned web pages and processes that data to track and automatically update the location table record of equipment attached to the network for which the MAC address is known (see diagram).
Not all the data present on those web pages is used. Ideally the scripts would use information associated with each of the ports that was a leaf node of the network, but currently it is not possible to identify all these ports from the data held on the web page. So only the ports that are labelled with room locations are used. Since ports in the server rooms that are connected to servers are not labelled with a room location the switchtoinfdb script can not currently track the location of hosts in the server rooms.
Because the MAC address for a host that moves location will appear multiple times on the web page with different time stamps only data that has a time stamp with the same hour value as the time the switchtoinfdb script is run is used. The script needs to be run towards the end of the hour for this reason.
Inventory data for each host with FQDN address matching either <simple-hostname>.inf.ed.ac.uk or <simple-hostname>.diy.inf.ed.ac.uk is exported each day from the Informatics database in the form of LCFG header files, one per host, that are then copied via rdist to the lcfg-master server. The files are generated by the generate_lcfg_headers script that is run on the Informatics database host infdb. It is run by the pseudo-user daidb from cron.
The inventory data can also be accessed via the TEC GUI. This interface is available on all DICE desktop machines. The simplest way of firing up the TEC GUI for the purposes of the inventory is via the cosdb command. This starts up the TEC interface and displays the COS DESKTOP custom form. From this form it is easy to start up the two custom forms written for the current inventory data: the Inventory Item-Part and the Computer System custom forms.
|
Informatics Forum, 10 Crichton Street, Edinburgh, EH8 9AB, Scotland, UK
Tel: +44 131 651 5661, Fax: +44 131 651 1426, E-mail: school-office@inf.ed.ac.uk Please contact our webadmin with any comments or corrections. Logging and Cookies Unless explicitly stated otherwise, all material is copyright © The University of Edinburgh |
