Document KeyFileExt(5)
[openafs.git] / doc / man-pages / pod8 / bos_status.pod
1 =head1 NAME
2
3 bos_status - Displays the status of server processes
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 S<<< B<bos status -server> <I<machine name>> >>>  [-instance <I<server process name>>+]
11 [B<-long>]  S<<< [B<-cell> <I<cell name>>] >>>  [B<-noauth>]  [B<-localauth>]  [B<-help>]
12
13 S<<< B<bos stat -s> <I<machine name>> >>>  [-i <I<server process name>>+]
14 [B<-lon>]  S<<< [B<-c> <I<cell name>>] >>>  [B<-n>]  [B<-loc>]  [B<-h>]
15
16 =for html
17 </div>
18
19 =head1 DESCRIPTION
20
21 The bos status command reports the status of processes on the
22 server machine named by the B<-server> argument, either
23
24 =over 4
25
26 =item *
27
28 All of the AFS server processes listed in the
29 F</usr/afs/local/BosConfig> file
30
31 =item *
32
33 Only these processes named by the -instance argument
34
35 =back
36
37 =head1 OPTIONS
38
39 =over 4
40
41 =item B<-server> <I<machine name>>
42
43 Indicates the server machine for which to report server process
44 status. Identify the machine by IP address or its host name (either
45 fully-qualified or abbreviated unambiguously). For details, see L<bos(8)>.
46
47 =item -instance
48
49 Names each process for which to report status. Use the process name
50 assigned with the B<-instance> argument to the B<bos>
51 command. The output from the B<bos status> command lists the
52 names.
53
54 =item -long
55
56 Produces more detailed status information.
57
58 =item B<-cell> <I<cell name>>
59
60 Names the cell in which to run the command. Do not combine this
61 argument with the B<-localauth> flag. For more details, see L<bos(8)>.
62
63 =item B<-noauth>
64
65 Assigns the unprivileged identity C<anonymous> to the
66 issuer. Do not combine this flag with the B<-localauth>
67 flag. For more details, see L<bos(8)>.
68
69 =item B<-localauth>
70
71 Constructs a server ticket using a key from the local
72 F</usr/afs/etc/KeyFile> or F</usr/afs/etc/KeyFileExt> file. The B<bos> command
73 interpreter presents the ticket to the BOS Server during mutual
74 authentication. Do not combine this flag with the B<-cell> or
75 B<-noauth> options. For more details, see L<bos(8)>.
76
77 =item B<-help>
78
79 Prints the online help for this command. All other valid options
80 are ignored.
81
82 =back
83
84 =head1 OUTPUT
85
86 The output for a process includes at least one line, which reports one of
87 the following as the process's current status:
88
89 =over 4
90
91 =item *
92
93 C<currently running normally>. The process's status
94 flag in the B<BosConfig> file is C<Run>. For
95 B<cron> entries, this message indicates only that the command is
96 scheduled to run, not necessarily that it was executing when the B<bos
97 status> command was issued.
98
99 =item *
100
101 C<disabled>. The process is not running, and its
102 B<BosConfig> status flag is C<NotRun>.
103
104 =item *
105
106 C<temporarily disabled>. The process is not running
107 although its status flag in the B<BosConfig> file is
108 C<Run>. Either an administrator used the B<bos
109 shutdown> command to stop it, or the
110
111 =item *
112
113 BOS Server stopped trying to restart it after numerous failed
114 attempts. In the second case, the auxiliary message is C<stopped for
115 too many errors>.
116
117 =item *
118
119 C<temporarily enabled>. The process is running although its
120 status flag in the B<BosConfig> file is C<NotRun>. An
121 administrator has used the B<bos startup> command to start it.
122
123 =back
124
125 If one of the following special circumstances applies to the process, the
126 indicated message appears in its entry:
127
128 =over 4
129
130 =item *
131
132 C<has core file>. The process failed and created a core
133 file in the F</usr/afs/logs> directory. If the BOS Server was
134 able to restart the process after the failure, the primary status is
135 C<currently running normally>.
136
137 =item *
138
139 C<stopped for too many  errors>. The reason for the primary
140 status C<temporarily  disabled> is that the BOS Server's attempts
141 to restart the process all failed.
142
143 =back
144
145 The entry for the fs process always includes a second line to
146 report the process's C<Auxiliary status>, which is one of the
147 following:
148
149 =over 4
150
151 =item *
152
153 C<file server running>. The File Server and Volume Server
154 components of the File Server process are running normally.
155
156 =item *
157
158 C<salvaging file system>. The Salvager is running, so the
159 File Server and Volume Server are temporarily disabled. The BOS Server
160 restarts them as soon as the Salvager is finished.
161
162 =back
163
164 The entry for a cron process includes an C<Auxiliary
165 status> that reports when the command will next execute.
166
167 If the -long flag is used, each entry includes the following
168 additional information:
169
170 =over 4
171
172 =item *
173
174 The process's type (C<simple>, C<fs>, or
175 C<cron>).
176
177 =item *
178
179 The day and time the process last started or restarted.
180
181 =item *
182
183 The number of C<proc starts>, which is how many times the BOS
184 Server has started or restarted the process since it started itself.
185
186 =item *
187
188 The C<Last exit> time when the process (or one of the component
189 processes in the B<fs> process) last terminated. This line does
190 not appear if the process has not terminated since the BOS Server
191 started.
192
193 =item *
194
195 The C<Last error exit> time when the process (or one of the
196 component processes in the B<fs> process) last failed due to an
197 error. A further explanation such as C<due to shutdown request>
198 sometimes appears. This line does not appear if the process has not
199 failed since the BOS Server started.
200
201 =item *
202
203 Each command that the BOS Server invokes to start the process, as
204 specified by the B<-cmd> argument to the B<bos create>
205 command.
206
207 =item *
208
209 The pathname of the notifier program that the BOS Server invokes when the
210 process terminates (if any), as specified by the B<-notifier> argument
211 to the B<bos create> command.
212
213 =back
214
215 If the -long flag is provided and the BOS Server discovers that
216 the mode bits on files and subdirectories in the local F</usr/afs>
217 directory differ from the expected values, it prints the following warning
218 message:
219
220    Bosserver reports inappropriate access on server directories
221
222 The following chart summarizes the expected mode bit settings. A
223 question mark indicates that the BOS Server does not check that bit.
224
225 =head1 EXAMPLES
226
227 The following example command displays the status of processes on the
228 machine B<fs3.example.com>:
229
230    % bos status fs3.example.com
231    Instance buserver, currently running normally.
232    Instance kaserver, currently running normally.
233    Instance ptserver, currently running normally.
234    Instance vlserver, currently running normally.
235    Instance fs, has core file, currently running normally.
236        Auxiliary status is: file server running.
237    Instance upserver, currently running normally.
238
239 The following example command displays a detailed status report for the
240 B<fs> and B<ptserver> processes on the machine
241 B<fs1.example.com>.
242
243    % bos status -server fs1.example.com -instance fs ptserver -long
244    Instance fs, (type is fs), currently running normally.
245       Auxiliary status is: file server running.
246       Process last started at Wed Jan 7 5:34:49 1998 (3 proc starts)
247       Last exit at Wed Jan 7 5:34:49 1998
248       Last error exit at Wed Jan 7 5:34:49 1998, due to shutdown
249           request
250       Command 1 is '/usr/afs/bin/fileserver'
251       Command 2 is '/usr/afs/bin/volserver'
252       Command 3 is '/usr/afs/bin/salvager'
253    Instance ptserver, (type is simple) currently running normally.
254       Process last started at Tue Jan 6 8:29:19 1998 (1 proc starts)
255       Command 1 is '/usr/afs/bin/ptserver'
256
257 =head1 PRIVILEGE REQUIRED
258
259 None
260
261 =head1 SEE ALSO
262
263 L<BosConfig(5)>,
264 L<KeyFile(5)>,
265 L<KeyFileExt(5)>,
266 L<bos(8)>,
267 L<bos_create(8)>,
268 L<bos_shutdown(8)>,
269 L<bos_startup(8)>,
270 L<bos_status(8)>
271
272 =head1 COPYRIGHT
273
274 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
275
276 This documentation is covered by the IBM Public License Version 1.0.  It was
277 converted from HTML to POD by software written by Chas Williams and Russ
278 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.