← Back to branch summary

~ubuntu-branches/ubuntu/utopic/gridengine/utopic

« back to all changes in this revision

Viewing changes to doc/man/man1/qhost.1

  • Committer: Bazaar Package Importer
  • Author(s): Mark Hymers
  • Date: 2008-06-25 22:36:13 UTC
  • Revision ID: james.westby@ubuntu.com-20080625223613-tvd9xlhuoct9kyhm
Tags: upstream-6.2~beta2
Import upstream version 6.2~beta2

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/man/man1/qhost.1
 
1
'\" t
 
2
.\"___INFO__MARK_BEGIN__
 
3
.\"
 
4
.\" Copyright: 2004 by Sun Microsystems, Inc.
 
5
.\"
 
6
.\"___INFO__MARK_END__
 
7
.\"
 
8
.\" $RCSfile$ 
 
9
.\"
 
10
.\"
 
11
.\" Some handy macro definitions [from Tom Christensen's man(1) manual page].
 
12
.\"
 
13
.de SB          \" small and bold
 
14
.if !"\\$1"" \\s-2\\fB\&\\$1\\s0\\fR\\$2 \\$3 \\$4 \\$5
 
15
..
 
16
.\"
 
17
.de T           \" switch to typewriter font
 
18
.ft CW          \" probably want CW if you don't have TA font
 
19
..
 
20
.\"
 
21
.de TY          \" put $1 in typewriter font
 
22
.if t .T
 
23
.if n ``\c
 
24
\\$1\c
 
25
.if t .ft P
 
26
.if n \&''\c
 
27
\\$2
 
28
..
 
29
.\"
 
30
.de M           \" man page reference
 
31
\\fI\\$1\\fR\\|(\\$2)\\$3
 
32
..
 
33
.TH QHOST 1 "$Date$" "xxRELxx" "xxQS_NAMExx User Commands"
 
34
.SH NAME
 
35
qhost \- show the status of xxQS_NAMExx hosts, queues, jobs
 
36
.\"
 
37
.\"
 
38
.SH SYNTAX
 
39
.B qhost
 
40
[ \fB\-F\fP [\fBresource_name,...\fP]
 
41
[
 
42
.B -help
 
43
] [
 
44
.B -h host_list
 
45
] [
 
46
.B -j
 
47
] [
 
48
.B -l resource=val,...
 
49
] [
 
50
.B -u user,...
 
51
] [
 
52
.B -xml
 
53
].\"
 
54
.SH DESCRIPTION
 
55
.I qhost
 
56
shows the current status of the available xxQS_NAMExx hosts, queues and the
 
57
jobs associated with the queues. Selection options allow you
 
58
to get information about specific hosts, queues, jobs or users.
 
59
Without any option
 
60
.I qhost
 
61
will display a list of all hosts without queue or job
 
62
information.
 
63
.PP
 
64
.\"
 
65
.SH OPTIONS
 
66
.\"
 
67
.IP "\fB\-F\fP [ \fBresource_name,...\fP ]"
 
68
.I qhost
 
69
will present a detailed listing of the current 
 
70
resource availability per host with respect to all resources (if the option 
 
71
argument is omitted) or with respect to those resources contained in the 
 
72
resource_name list. Please refer to the description of the
 
73
\fBFull Format\fP in 
 
74
section \fBOUTPUT FORMATS\fP below for further detail.
 
75
.\"
 
76
.IP "\fB\-help\fP"
 
77
Prints a listing of all options.
 
78
.\"
 
79
.IP "\fB\-h host_list\fP"
 
80
Prints a list of all hosts contained in host_list.
 
81
.\"
 
82
.IP "\fB\-j\fP"
 
83
Prints all jobs running on the queues hosted by the shown hosts. This 
 
84
switch calls \fB\-q\fP implicitly.
 
85
.\"
 
86
.IP "\fB\-l resource\fP[\fB=value\fP],..."
 
87
Defines the resources required by the hosts 
 
88
on which information is requested.
 
89
Matching is performed on hosts.
 
90
.\"
 
91
.\"
 
92
.IP "\fB\-q\fP"
 
93
Show information about the queues instances hosted by the displayed hosts.
 
94
.\"
 
95
.IP "\fB\-u user,...\fP"
 
96
Display information only on those jobs and queues
 
97
being associated with the users from the given user list.
 
98
.\"
 
99
.IP "\fB\-xml\fP"
 
100
This option can be used with all other options and changes the output to XML. The used
 
101
schemas are referenced in the XML output. The output is printed to stdout.
 
102
.br
 
103
.\"
 
104
.\"
 
105
.SH "OUTPUT FORMATS"
 
106
Depending on the presence or absence of the \fB\-q\fP or \fB\-F\fP and
 
107
\fB\-j\fP option three output formats need to be differentiated.
 
108
PP
 
109
.\"
 
110
.SS "\fBDefault Format (without \-q, \-F and \-j)\fP"
 
111
For each host one line is printed. The output consists of
 
112
consisting of
 
113
.IP "\(bu" 3n
 
114
the Hostname 
 
115
.IP "\(bu" 3n
 
116
the Architecture.
 
117
.IP "\(bu" 3n
 
118
the  Number of processors.
 
119
.IP "\(bu" 3n
 
120
the Load.
 
121
.IP "\(bu" 3n
 
122
the Total Memory.
 
123
.IP "\(bu" 3n
 
124
the Used Memory.
 
125
.IP "\(bu" 3n
 
126
the Total Swapspace.
 
127
.IP "\(bu" 3n
 
128
the Used Swapspace.
 
129
.\"
 
130
.PP
 
131
If the \fB\-q\fP option is supplied, each host status line also contains
 
132
extra lines for every queue hosted by the host consisting of,
 
133
.IP "\(bu" 3n
 
134
the queue name.
 
135
.IP "\(bu" 3n
 
136
the queue type \- one of B(atch), I(nteractive), C(heckpointing),
 
137
P(arallel), T(ransfer) or combinations thereof,
 
138
.IP "\(bu" 3n
 
139
the number of used and available job slots,
 
140
.IP "\(bu" 3n
 
141
the state of the queue \- one of
 
142
u(nknown) if the corresponding
 
143
.M xxqs_name_sxx_execd 8
 
144
cannot be contacted, a(larm), A(larm), C(alendar suspended), s(uspended),
 
145
S(ubordinate), d(isabled), D(isabled), E(rror) or 
 
146
combinations thereof.
 
147
.PP
 
148
If the state is a(alarm) at least one of the load thresholds defined in the 
 
149
\fIload_thresholds\fP list of the queue configuration (see
 
150
.M queue_conf 5 )
 
151
is 
 
152
currently exceeded, which prevents from scheduling further jobs to that 
 
153
queue.
 
154
.PP
 
155
As opposed to this, the state A(larm) indicates that at least one of the
 
156
suspend thresholds of the queue (see
 
157
.M queue_conf 5 )
 
158
is currently exceeded. This will result in jobs running in that queue being
 
159
successively suspended until no threshold is violated.
 
160
.PP
 
161
The states s(uspended) and d(isabled) can be assigned to queues and
 
162
released via the
 
163
.M qmod 1
 
164
command. Suspending a queue will cause all jobs executing in that queue to
 
165
be suspended.
 
166
.PP
 
167
The states D(isabled) and C(alendar suspended) indicate that the queue 
 
168
has been disabled or suspended automatically via the calendar facility of 
 
169
xxQS_NAMExx (see
 
170
.M calendar_conf 5 ),
 
171
while the S(ubordinate) state 
 
172
indicates, that the queue has been suspend via subordination to another 
 
173
queue (see
 
174
.M queue_conf 5
 
175
for details). When suspending a queue 
 
176
(regardless of the cause) all jobs executing in that queue are suspended 
 
177
too.
 
178
.PP
 
179
If an E(rror) state is displayed for a queue,
 
180
.M xxqs_name_sxx_execd 8
 
181
on that host was unable to locate the
 
182
.M xxqs_name_sxx_shepherd 8
 
183
executable
 
184
on that host in order to start a job. Please check the
 
185
error logfile of that
 
186
.M xxqs_name_sxx_execd 8
 
187
for leads on how to resolve the problem. Please enable the
 
188
queue afterwards via the \fB-c\fP option of the
 
189
.M qmod 1
 
190
command manually.
 
191
.PP
 
192
If the \fB\-F\fP option was used, resource availability information is printed 
 
193
following the host status line. For each resource (as selected in an option 
 
194
argument to \fB\-F\fP or for all resources if the option argument was
 
195
omitted) a single line is displayed with the following format:
 
196
.IP "\(bu" 3n
 
197
a one letter specifier indicating whether the current resource availability 
 
198
value was dominated by either
 
199
.br
 
200
`\fBg\fP' - a cluster global,
 
201
.br
 
202
`\fBh\fP' - a host total or
 
203
.IP "\(bu" 3n
 
204
a second one letter specifier indicating the source for the current resource 
 
205
availability value, being one of
 
206
.br
 
207
`\fBl\fP' - a load value reported for the
 
208
resource,
 
209
.br
 
210
`\fBL\fP' - a load value for the resource after administrator
 
211
defined load scaling has been applied,
 
212
.br
 
213
`\fBc\fP' - availability derived from
 
214
the consumable resources facility (see
 
215
.M complexes 5 ),
 
216
.br
 
217
`\fBf\fP' - a fixed 
 
218
availability definition derived from a non-consumable complex attribute or 
 
219
a fixed resource limit.
 
220
.IP "\(bu" 3n
 
221
after a colon the name of the resource on which information is displayed.
 
222
.IP "\(bu" 3n
 
223
after an equal sign the current resource availability value.
 
224
.PP
 
225
The displayed availability values and the sources from which they derive are 
 
226
always the minimum values of all possible combinations. Hence, for example,
 
227
a line of the form "qf:h_vmem=4G" indicates that a queue currently has a 
 
228
maximum availability in virtual memory of 4 Gigabyte, where this value is a 
 
229
fixed value (e.g. a resource limit in the queue configuration) and it is queue 
 
230
dominated, i.e. the host in total may have more virtual memory available than 
 
231
this, but the queue doesn't allow for more. Contrarily a line "hl:h_vmem=4G" 
 
232
would also indicate an upper bound of 4 Gigabyte virtual memory 
 
233
availability, but the limit would be derived from a load value currently 
 
234
reported for the host. So while the queue might allow for jobs with higher 
 
235
virtual memory requirements, the host on which this particular queue resides 
 
236
currently only has 4 Gigabyte available.
 
237
.PP
 
238
After the queue status line (in case of \fB\-j\fP) a single line is printed
 
239
for each job running currently in this queue. Each job status
 
240
line contains
 
241
.IP "\(bu" 3n
 
242
the job ID,
 
243
.IP "\(bu" 3n
 
244
the job name,
 
245
.IP "\(bu" 3n
 
246
the job owner name,
 
247
.IP "\(bu" 3n
 
248
the status of the job \- one of t(ransfering),
 
249
r(unning), R(estarted), s(uspended), S(uspended) or T(hreshold) (see the
 
250
\fBReduced Format\fP section for detailed information),
 
251
.IP "\(bu" 3n
 
252
the start date and time and the function of the job (MASTER
 
253
or SLAVE - only meaningful in case of a parallel job) and
 
254
.IP "\(bu" 3n
 
255
the priority of the jobs.
 
256
.\"
 
257
.\"
 
258
.SH "ENVIRONMENTAL VARIABLES"
 
259
.\" 
 
260
.IP "\fBxxQS_NAME_Sxx_ROOT\fP" 1.5i
 
261
Specifies the location of the xxQS_NAMExx standard configuration
 
262
files.
 
263
.\"
 
264
.IP "\fBxxQS_NAME_Sxx_CELL\fP" 1.5i
 
265
If set, specifies the default xxQS_NAMExx cell. To address a xxQS_NAMExx
 
266
cell
 
267
.I qhost 
 
268
uses (in the order of precedence):
 
269
.sp 1
 
270
.RS
 
271
.RS
 
272
The name of the cell specified in the environment 
 
273
variable xxQS_NAME_Sxx_CELL, if it is set.
 
274
.sp 1
 
275
The name of the default cell, i.e. \fBdefault\fP.
 
276
.sp 1
 
277
.RE
 
278
.RE
 
279
.\"
 
280
.IP "\fBxxQS_NAME_Sxx_DEBUG_LEVEL\fP" 1.5i
 
281
If set, specifies that debug information
 
282
should be written to stderr. In addition the level of
 
283
detail in which debug information is generated is defined.
 
284
.\"
 
285
.IP "\fBxxQS_NAME_Sxx_QMASTER_PORT\fP" 1.5i
 
286
If set, specifies the tcp port on which
 
287
.M xxqs_name_sxx_qmaster 8
 
288
is expected to listen for communication requests.
 
289
Most installations will use a services map entry for the
 
290
service "sge_qmaster" instead to define that port.
 
291
.\"
 
292
.\"
 
293
.SH FILES
 
294
.nf
 
295
.ta \w'<xxqs_name_sxx_root>/     'u
 
296
\fI<xxqs_name_sxx_root>/<cell>/common/act_qmaster\fP
 
297
        xxQS_NAMExx master host file
 
298
.fi
 
299
.\"
 
300
.\"
 
301
.SH "SEE ALSO"
 
302
.M xxqs_name_sxx_intro 1 ,
 
303
.M qalter 1 ,
 
304
.M qconf 1 ,
 
305
.M qhold 1 ,
 
306
.M qmod 1 ,
 
307
.M qstat 1 ,
 
308
.M qsub 1 ,
 
309
.M queue_conf 5 ,
 
310
.M xxqs_name_sxx_execd 8 ,
 
311
.M xxqs_name_sxx_qmaster 8 ,
 
312
.M xxqs_name_sxx_shepherd 8 .
 
313
.\"
 
314
.\"
 
315
.SH "COPYRIGHT"
 
316
See
 
317
.M xxqs_name_sxx_intro 1
 
318
for a full statement of rights and permissions.