import repository from arizona
[raven.git] / owl / client / owl.x
1 [NAME]
2 owl \- Client-side Owl daemon
3 [DESCRIPTION]
4 .PP
5 Owl is a client-side daemon for sending status information to an Owl server. 
6 An Owl server supports a collection of
7 .I databases
8 that store status information.
9 The status information is organized into 
10 .I modules
11 and each module has a set of 
12 .I fields.
13 The modules and associated fields are defined by the module configuration files that 
14 .B owl
15 processes when it starts and are used to configure the Owl server.
16 The module configuration files are processed in alphabetical order.
17 After the modules are configured 
18 .B owl 
19 periodically runs the scripts in the scripts directory to generate the updated values
20 for the fields. The output from the scripts is used to update the Owl server.
21 [OWLD CONFIGURATION FILE]
22 .PP
23 The 
24 .B owl
25 configuration file
26 .I owl.conf
27 configures 
28 .B owl
29 itself. Its syntax is that parsed by the Python ConfigParser class, so it is similar to
30 a Windows INI file:
31
32     [section]
33     name=value
34
35 The   
36 .I owl.conf
37 file has one section
38 .B Owl
39 that has the following options:
40 .TP
41 .B conf_dir
42 directory containing module configuration files [default: /etc/owl/conf.d]
43 .TP
44 .B script_dir
45 directory containing module scripts [default: /etc/owl/scripts.d]
46 .TP
47 .B url
48 base URL of the Owl server [default: http://owl.cs.arizona.edu/owl/]
49 .TP
50 .B databases
51 comma-separated list of databases to be updated [default: None]
52 .TP
53 .B interval
54 interval for updating the Owl server (seconds) [default: 60]
55 .TP
56 .B timeout
57 timeout when updating the Owl server (seconds) [default: 10]
58 .TP
59 .B max_register_backoff
60 maximum backoff interval when retrying failed attempts to register a module with the
61 Owl server  (seconds) [default: 600]
62 .TP
63 .B max_update_backoff 
64 maximum backoff interval when retrying failed attempts to update the Owl server (seconds) [default: 600]
65 .TP
66 .B log_file
67 name of the log file [default: /var/log/owl]
68 .TP
69 .B verbosity
70 verbosity level (0-2) [default: 1]
71 .TP
72 .B planetlab
73 If specified, sets database to slice name. [default: False]
74
75 [MODULE CONFIGURATION FILE]
76 .PP
77 A module configuration file has the same syntax as the Owl configuration file. 
78 It must
79 contain a 
80 .B Module 
81 section with the following options:
82 .TP
83 .B name
84 (required) name of the module
85 .TP
86 .B version
87 (required) version of the module. This is used to update the module information on the Owl 
88 server, so it is important to increment this field when you change the format of the module
89 configuration.
90 .TP
91 .B heading
92 (optional) heading for the module in the Owl output. By default it is the name
93 of the module.
94 .TP
95 .B fields
96 (required) comma-separated list of fields in the module. The fields will be displayed in the
97 order in which they appear in this list.
98 .PP
99 Each field specified by the fields option must have a corresponding section with the same name.
100 The section for a field has the following options:
101 .TP
102 .B type
103 type of the field: integer or string. [default: string]
104 .TP
105 .B heading
106 heading for the field in the Owl output. [default: name of the field]
107 .TP
108 .B headingAlign
109 alignment of the heading in the Owl output: left, center, or right. [default: center]
110 .TP
111 .B align
112 alignment of the field value in the Owl output: left, center, or right. [default: center]
113 .TP
114 .B description
115 description of the field. This is displayed in the Owl output legend.
116
117 [MODULE SCRIPT]
118 .PP
119 A module script is a program that is executed by Owl to produce the values for the module's
120 fields. The output of the script must be in INI format and must have a section for the module
121 and options for each of the fields to be updated. There does not have to be a one-to-one mapping
122 between scripts and modules -- a single script can produce output for multiple modules and
123 a single module can be updated by multiple scripts. 
124
125 Care should be taken that a module script does not introduce a security hole.
126 [Examples]
127 .PP
128 .B Owl Configuration File
129
130     [Owl]
131     conf_dir=/etc/owl/conf.d
132     script_dir=/etc/owl/scripts.d
133     url=http://quake.cs.arizona.edu/owl/
134     databases=test
135
136 .B Module Configuration File
137
138     [Module]
139     name=date
140     version=0.1
141     fields=date
142
143     [date]
144     type=string
145     heading=Date
146
147 .B Module Script
148
149     #!/bin/bash
150     echo '[date]'
151     echo "date=`date`"
152
153 [FILES]
154 .I /etc/owl/owl.conf
155 .RS
156 Owl configuration file
157 .RE
158 .I /etc/owl/conf.d
159 .RS
160 Directory containing module configuration files
161 .RE
162 .I /etc/owl/scripts.d
163 .RS
164 Directory containing module scripts
165 .RE
166 [AUTHOR]
167 John H. Hartman
168 University of Arizona