Command Line Tools

A number of command line utilities are provided in the standard habitat distribution. These address getting data in and out of habitat's various storage systems, maintaining ringstores and being able to get data or run the suite's methods on an ad-hoc basis.

This section describes each tool and their function. Their manual pages are held separately in the appendix.

Common Arguments

Where possible, all the command line utilities share a common set of arguments. They are:

-c croute	Append user configuration data from croute (route addressing format), rather than the default file ~/.habrc. For example, -c file:cf.dat would load configuration from cf.dat.
-C cfcmd	Append a list of configuration directives from cfcmd, separated by semicolons. For example, -C “nmalloc=1;dummy=6” would set the configuration variables nmalloc to 1 and dummy to 6
-d	Place command in diagnostic mode, giving an additional level of logging and sending the text to stderr rather than default or configured destinations. Used for clockwork in daemon mode, will send output to the controlling terminal
-D	Place command in debug mode. As -d above but generating a great deal more information, designed to be used in conjunction with the source code. Also overrides normal outputs and will send the text to stderr. Used for clockwork in daemon mode, will send output to the controlling terminal
-e fmt	Change the logging output to one of eight preset alternative formats, some showing additional information. Fmt must be in the range 0-7, with format 3 being concise but useful. The formats are:- 0. everything!! time, severity, path, process ids, file, function, line, origin, code, text 1. upper case severity letter, text 2. severity, text 3. justified severity, text, file, function, line 4. upper case severity letter, short date time, binary name, file, function, line, text 5. time, severity, binary path, pid, file, function, line, code, text 6. long time, epoch time, severity, binary path, pid, tid, file, function, line, origin, code, text 7. justified severity text, justified file, line, function, text
-h	Print a help message to stdout and exit
-v	Print the version to stdout and exit

If a command does not work as expected, the user may be directed to run it with the -d or -D flags to help diagnose the problem.

Data Addressing

Most of the commands use route formats to address their data. The format of a route is similar to URLs and has been extended to cope with the formats of data storage used in habitat. It is fully explained in the concept section at the beginning of this guide.

habget

The utility habget opens a route specified on the command line, and redirects the output to stdout. As an example, the following outputs the data collected by the system probe (the data is collected at a 60 second interval):

$ habget rs:/var/lib/habitat/myhost.rs,sys,60

load1	load5	load15	runque	nprocs	lastproc
1 min load	5 minload	15 min load	num run procs	num procs	last proc run	info
4	4	4	""	""	""	max
abs	abs	abs	abs	abs	abs	sense
nano	nano	nano	u32	u32	u32	type
--
0.00	0.00	0.04	1	142	5895

The data returned has been shortened & edited for brevity. In reality, the info strings are longer and there are many more columns.

The most recent sample is returned, which in the example above is a single line. To get more data, use the additional route qualifiers t= or s=, which explicitly specify the time or sequence. For example, to return everything in the sys,60 ring, use

rs:/var/lib/habitat/myhost.rs,sys,60,s=0-

Which will return all the records from sequence 0 on to the end. When explicit time and sequence addresses are used, the output will be augmented with a sequence, time and duration column (_seq, _time and _dur). All routes are valid addresses, including http: and sqlrs:.

habput

The utility habput inserts data onto a route for storage in a ringstore or SQLringstore. The following example reads the table headed tom dick harry and stores it in the ring called myring with a 0 second duration contained in the ringstore file myfile.rs.:

	$ habput rs:myfile.rs,myring,0 <<END
	tom	dick	harry
	--
	1	2	3
	4	5	6
	END

A ring of 0 duration is the convention for data with irregular frequency. Sending the data to a ringstore causes it to be scanned for a table structure and if passed, will append the data to the ring.

If there is an error in the format of the table or in the address syntax, then the ring will generate an error and no data will be stored. Appended data is given an ascending sequence number and will be data stamped.

Rings may be implicitly created with this utility, in which case a default size and description will be given (which can be overridden with the -s and -t switches). The default ring is circular with 1,000 slots; when sequence 1,001 is appended, the oldest will be lost. To create a queue rather than a ring buffer, use -s 0.

Rings may be manipulated (size, name, description, etc) using the utility habrs, which is described in the Administration manual.

Clockwork & killclock

The commands clockwork and killclock are used to start and stop the collection daemon on each machine. (Unless habitat is installed as a system service, see /etc/init.d/habitat below). To start a shared collection service for the system, run clockwork on its own. It will become a background daemon process, requiring to be stopped with the program killclock, also with no argument.

If a collection process is not running when ghabitat is started, then a pop-up will ask if you wish to start one (see sections above). In this case, the data file will be owned by the starting user although the network service will still be available.

If a user wishes to run their own data collection in addition to system collection, they can do so by providing a custom job table to clockwork, like so:

clockwork -j jobroute

Jobroute must be a route but typically is a file created for the specific situation. Job tables are described in the Administration Manual, and describe the probes to run, their frequency and where their storage is located. The -j flag does not daemonise and stays attach to the controlling terminal, so that it may be controlled and stopped like a normal shell level process.

/etc/init.d/habitat

When habitat is fully installed as a system service or daemon, a single script manages the starting and stopping of clockwork. It is automatically run on on the machine's start-up.

As root, one can manually control clockwork collection using the conventional command syntax:

/etc/init.d/habitat [ start | stop | status ]

If this is the case in your installation, you do not need to manually start a personal instance of clockwork unless you wish to run specific jobs.

This command is covered in greater depth in the Administration manual.

Other commands

The remaining commands are covered by the Administration Manual:-