import repository from arizona
[raven.git] / owl / client / owl.man
1 .\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.36.
2 .TH OWL "8" "September 2011" "owl 0.30" "System Administration Utilities"
3 .SH NAME
4 owl \- Client-side Owl daemon
5 .SH SYNOPSIS
6 .B owl
7 [\fIoptions\fR]
8 .SH DESCRIPTION
9 .PP
10 Owl is a client-side daemon for sending status information to an Owl server. 
11 An Owl server supports a collection of
12 .I databases
13 that store status information.
14 The status information is organized into 
15 .I modules
16 and each module has a set of 
17 .I fields.
18 The modules and associated fields are defined by the module configuration files that 
19 .B owl
20 processes when it starts and are used to configure the Owl server.
21 The module configuration files are processed in alphabetical order.
22 After the modules are configured 
23 .B owl 
24 periodically runs the scripts in the scripts directory to generate the updated values
25 for the fields. The output from the scripts is used to update the Owl server.
26 .SH OPTIONS
27 .TP
28 \fB\-\-version\fR
29 show program's version number and exit
30 .TP
31 \fB\-h\fR, \fB\-\-help\fR
32 show this help message and exit
33 .TP
34 \fB\-q\fR, \fB\-\-quiet\fR
35 print no output
36 .TP
37 \fB\-v\fR, \fB\-\-verbose\fR
38 print verbose output
39 .TP
40 \fB\-d\fR, \fB\-\-debug\fR
41 print debugging output
42 .TP
43 \fB\-f\fR CONFIG, \fB\-\-config\fR=\fICONFIG\fR
44 config file location [default: /etc/owl/owl.conf]
45 .TP
46 \fB\-s\fR SCRIPTDIR, \fB\-\-scriptdir\fR=\fISCRIPTDIR\fR
47 script directory [default: /etc/owl/scripts.d]
48 .TP
49 \fB\-c\fR CONFDIR, \fB\-\-confdir\fR=\fICONFDIR\fR
50 config file directory [default: /etc/owl/conf.d]
51 .TP
52 \fB\-u\fR URL, \fB\-\-url\fR=\fIURL\fR
53 URL of Owl server [default:
54 http://owl.cs.arizona.edu/owl/]
55 .TP
56 \fB\-n\fR, \fB\-\-dry\-run\fR
57 don't update Owl server [default: False]
58 .TP
59 \fB\-b\fR NAME, \fB\-\-database\fR=\fINAME\fR
60 database to update
61 .TP
62 \fB\-S\fR, \fB\-\-sync\fR
63 run synchronously (don't detach) [default: False]
64 .TP
65 \fB\-l\fR LOGFILE, \fB\-\-logfile\fR=\fILOGFILE\fR
66 log file [default: /var/log/owl]
67 .TP
68 \fB\-i\fR INTERVAL, \fB\-\-interval\fR=\fIINTERVAL\fR
69 interval to run scripts in daemon mode [default: 60]
70 .TP
71 \fB\-p\fR, \fB\-\-planetlab\fR
72 PlanetLab mode. Sets database to slice name. [default:
73 False]
74 .SH EXAMPLES
75 .PP
76 .B Owl Configuration File
77
78     [Owl]
79     conf_dir=/etc/owl/conf.d
80     script_dir=/etc/owl/scripts.d
81     url=http://quake.cs.arizona.edu/owl/
82     databases=test
83
84 .B Module Configuration File
85
86     [Module]
87     name=date
88     version=0.1
89     fields=date
90
91     [date]
92     type=string
93     heading=Date
94
95 .B Module Script
96
97     #!/bin/bash
98     echo '[date]'
99     echo "date=`date`"
100 .SH "OWLD CONFIGURATION FILE"
101 .PP
102 The 
103 .B owl
104 configuration file
105 .I owl.conf
106 configures 
107 .B owl
108 itself. Its syntax is that parsed by the Python ConfigParser class, so it is similar to
109 a Windows INI file:
110
111     [section]
112     name=value
113
114 The   
115 .I owl.conf
116 file has one section
117 .B Owl
118 that has the following options:
119 .TP
120 .B conf_dir
121 directory containing module configuration files [default: /etc/owl/conf.d]
122 .TP
123 .B script_dir
124 directory containing module scripts [default: /etc/owl/scripts.d]
125 .TP
126 .B url
127 base URL of the Owl server [default: http://owl.cs.arizona.edu/owl/]
128 .TP
129 .B databases
130 comma-separated list of databases to be updated [default: None]
131 .TP
132 .B interval
133 interval for updating the Owl server (seconds) [default: 60]
134 .TP
135 .B timeout
136 timeout when updating the Owl server (seconds) [default: 10]
137 .TP
138 .B max_register_backoff
139 maximum backoff interval when retrying failed attempts to register a module with the
140 Owl server  (seconds) [default: 600]
141 .TP
142 .B max_update_backoff 
143 maximum backoff interval when retrying failed attempts to update the Owl server (seconds) [default: 600]
144 .TP
145 .B log_file
146 name of the log file [default: /var/log/owl]
147 .TP
148 .B verbosity
149 verbosity level (0-2) [default: 1]
150 .TP
151 .B planetlab
152 If specified, sets database to slice name. [default: False]
153 .SH "MODULE CONFIGURATION FILE"
154 .PP
155 A module configuration file has the same syntax as the Owl configuration file. 
156 It must
157 contain a 
158 .B Module 
159 section with the following options:
160 .TP
161 .B name
162 (required) name of the module
163 .TP
164 .B version
165 (required) version of the module. This is used to update the module information on the Owl 
166 server, so it is important to increment this field when you change the format of the module
167 configuration.
168 .TP
169 .B heading
170 (optional) heading for the module in the Owl output. By default it is the name
171 of the module.
172 .TP
173 .B fields
174 (required) comma-separated list of fields in the module. The fields will be displayed in the
175 order in which they appear in this list.
176 .PP
177 Each field specified by the fields option must have a corresponding section with the same name.
178 The section for a field has the following options:
179 .TP
180 .B type
181 type of the field: integer or string. [default: string]
182 .TP
183 .B heading
184 heading for the field in the Owl output. [default: name of the field]
185 .TP
186 .B headingAlign
187 alignment of the heading in the Owl output: left, center, or right. [default: center]
188 .TP
189 .B align
190 alignment of the field value in the Owl output: left, center, or right. [default: center]
191 .TP
192 .B description
193 description of the field. This is displayed in the Owl output legend.
194 .SH "MODULE SCRIPT"
195 .PP
196 A module script is a program that is executed by Owl to produce the values for the module's
197 fields. The output of the script must be in INI format and must have a section for the module
198 and options for each of the fields to be updated. There does not have to be a one-to-one mapping
199 between scripts and modules -- a single script can produce output for multiple modules and
200 a single module can be updated by multiple scripts. 
201
202 Care should be taken that a module script does not introduce a security hole.
203 .SH FILES
204 .I /etc/owl/owl.conf
205 .RS
206 Owl configuration file
207 .RE
208 .I /etc/owl/conf.d
209 .RS
210 Directory containing module configuration files
211 .RE
212 .I /etc/owl/scripts.d
213 .RS
214 Directory containing module scripts
215 .RE
216 .SH AUTHOR
217 John H. Hartman
218 University of Arizona