Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | BosConfig - Defines server processes for the BOS Server to monitor | |
4 | ||
5 | =head1 DESCRIPTION | |
6 | ||
7 | The F<BosConfig> file lists the processes that the Basic OverSeer (BOS) | |
8 | Server monitors on its server machine, and thus defines which AFS server | |
9 | processes run on the machine. It specifies how the BOS Server reacts when | |
10 | a process fails, and also defines the times at which the BOS Server | |
11 | automatically restarts processes as part of performance maintenance. The | |
12 | file must reside in the F</usr/afs/local> directory on each AFS server | |
13 | machine. | |
14 | ||
15 | A server process entry in the F<BosConfig> file records the following | |
16 | information: | |
17 | ||
18 | =over 4 | |
19 | ||
20 | =item * | |
21 | ||
22 | The I<entry type>, which is one of the following: | |
23 | ||
24 | =over 4 | |
25 | ||
26 | =item cron | |
27 | ||
28 | Designates a server process that runs periodically instead of | |
29 | continuously. The BOS Server starts a cron process only at specified | |
30 | times, not whenever it fails. All standard AFS process entries except | |
31 | C<fs> are simple (there are no standard cron processes). | |
32 | ||
33 | =item fs | |
34 | ||
35 | Designates a group of interdependent server processes. If one of the | |
36 | processes fails, the BOS Server must coordinate its restart with the | |
37 | restart of the other processes in the group, possibly by stopping them | |
38 | first. | |
39 | ||
40 | There is only one standard entry of this type, for which the conventional | |
41 | name is C<fs>. It combines three server processes: the File Server | |
42 | (B<fileserver> process), the Volume Server (B<volserver> process), and the | |
43 | Salvager (B<salvager> process). These processes all operate on the same | |
44 | data--the AFS data stored on an AFS server machine's F</vicep> partitions | |
45 | and mounted in the AFS filespace--but in different ways. Grouping the | |
46 | processes prevents them from attempting to access the same data | |
47 | simultaneously, which can cause corruption. | |
48 | ||
49 | During normal operation, the Salvager process is not active. If the File | |
50 | Server process fails, however, the BOS Server stops the Volume Server | |
51 | process and runs the Salvager process to correct any corruption that | |
52 | resulted from the failure. (The administrator can also issue the B<bos | |
53 | salvage> command to invoke the Salvager process.) If the Volume Server | |
54 | fails, the BOS Server can restart it without stopping the File Server or | |
55 | running the Salvager. | |
56 | ||
57 | =item simple | |
58 | ||
59 | Designates a server process that runs independently of any other on the | |
60 | server machine. If a simple process fails, the BOS Server does not have to | |
61 | coordinate its restart with any other process. | |
62 | ||
63 | =back | |
64 | ||
65 | =item * | |
66 | ||
67 | The I<entry name>. The conventional name for an entry in the F<BosConfig> | |
68 | file and the associated process matches the binary filename. When issuing | |
69 | any B<bos> command that takes the B<-instance> argument, identify each | |
70 | process by the name used in the F<BosConfig> file. For a list of the | |
71 | names, see the B<bos create> reference page. | |
72 | ||
73 | =item * | |
74 | ||
75 | The process's I<status flag>, which determines whether the BOS Server | |
76 | attempts to start the process in two cases: each time the BOS Server | |
77 | itself restarts, and when the process fails. The F<BosConfig> file | |
78 | currently uses a binary notation to indicate whether the BOS Server | |
79 | attempts to restart the process as necessary or does not monitor it at | |
80 | all. For the sake of clarity, the AFS documentation refers to the flags as | |
81 | C<Run> and C<NotRun> instead. Only a system administrator, not the BOS | |
82 | Server, can change the flag. | |
83 | ||
84 | =item * | |
85 | ||
86 | One or more I<command parameters> which the BOS Server invokes to start | |
87 | the process or processes associated with the entry: | |
88 | ||
89 | =over 4 | |
90 | ||
91 | =item * | |
92 | ||
93 | A C<cron> entry has two command parameters, the first the complete | |
94 | pathname to the program, and the second the time at which the BOS Server | |
95 | invokes the program. | |
96 | ||
97 | =item * | |
98 | ||
99 | The C<fs> entry has three command parameters, each the complete pathname | |
100 | to the B<fileserver>, B<volserver>, and B<salvager> programs, in that | |
101 | order. | |
102 | ||
103 | =item * | |
104 | ||
105 | A C<simple> entry has only one command parameter, the complete pathname to | |
106 | the program. | |
107 | ||
108 | =back | |
109 | ||
110 | =back | |
111 | ||
112 | In addition to server process entries, the F<BosConfig> file specifies the | |
113 | times at which the BOS Server performs two types of automatic process | |
114 | restarts: | |
115 | ||
116 | =over 4 | |
117 | ||
118 | =item * | |
119 | ||
120 | The I<general restart> time at which the BOS Server restarts itself and | |
121 | then each process for which the entry in the F<BosConfig> file has status | |
122 | flag C<Run>. The default setting is Sunday at 4:00 a.m. | |
123 | ||
124 | =item * | |
125 | ||
126 | The I<binary restart> time at which the BOS Server restarts any server | |
127 | process for which the time stamp on the binary file in the F</usr/afs/bin> | |
128 | directory is later than the last restart time for the process. The default | |
129 | is 5:00 a.m. | |
130 | ||
131 | =back | |
132 | ||
133 | Finally, there is an entry specifying whether the BOS Server will start in | |
134 | restricted mode. | |
135 | ||
136 | Although the F<BosConfig> file is in ASCII format, it is normally best not | |
137 | to use a text editor to alter it. The parser is very picky, and | |
138 | incorrectly formatted entries can prevent server startup in ways that are | |
139 | difficult to diagnose. Instead, use the appropriate commands from the | |
140 | B<bos> command suite: | |
141 | ||
142 | =over 4 | |
143 | ||
144 | =item * | |
145 | ||
146 | The B<bos create> command to create an entry in the file and start the | |
147 | associated process. | |
148 | ||
149 | =item * | |
150 | ||
151 | The B<bos delete> command to remove an entry from the file after the B<bos | |
152 | stop> command is used to stop the associated process. | |
153 | ||
154 | =item * | |
155 | ||
156 | The B<bos getrestart> command to display the times at which the BOS Server | |
157 | performs automatic restarts. | |
158 | ||
159 | =item * | |
160 | ||
161 | The B<bos getrestricted> command to display whether the BOS Server is running | |
162 | in restricted mode. | |
163 | ||
164 | =item * | |
165 | ||
166 | The B<bos setrestart> command to set the times at which the BOS Server | |
167 | performs automatic process restarts. | |
168 | ||
169 | =item * | |
170 | ||
171 | The B<bos setrestricted> command to place the BOS Server in restricted mode. | |
172 | ||
173 | =item * | |
174 | ||
175 | The B<bos start> command to change an entry's status flag to C<Run> and | |
176 | start the associated process. | |
177 | ||
178 | =item * | |
179 | ||
180 | The B<bos status> command to display all processes listed in the file. | |
181 | ||
182 | =item * | |
183 | ||
184 | The B<bos stop> command to change an entry's status flag to C<NotRun> and | |
185 | stop the associated process. | |
186 | ||
187 | =back | |
188 | ||
189 | There are also bos commands that start and stop processes without changing | |
190 | entries in the F<BosConfig> file. The BOS Server reads the F<BosConfig> | |
191 | file only when it starts, transferring the information into its | |
192 | memory. Thus a process's status as represented in the BOS Server's memory | |
193 | can diverge from its status in the F<BosConfig> file. The following | |
194 | commands change a process's status in the BOS Server's memory only: | |
195 | ||
196 | =over 4 | |
197 | ||
198 | =item * | |
199 | ||
200 | The B<bos restart> command restarts a specified set of processes, all | |
201 | processes, or all processes other than the BOS Server. | |
202 | ||
203 | =item * | |
204 | ||
205 | The B<bos shutdown> command stops a process. | |
206 | ||
207 | =item * | |
208 | ||
209 | The B<bos startup> command starts a process. | |
210 | ||
211 | =back | |
212 | ||
213 | When the BOS Server shuts down, it rewrites F<BosConfig>, discarding any | |
214 | changes made manually to that file. To change the configuration for the | |
215 | next BOS Server restart, instead write a new file to F<BosConfig.new>. If | |
216 | F<BosConfig.new> exists when the BOS Server starts, F<BosConfig> will be | |
217 | replaced by F<BosConfig.new> before the BOS Server reads its configuration. | |
218 | Note that the BOS Server will notice a new F<BosConfig.new> file whenever the | |
219 | I<general restart> time is reached, if one is configured, since the BOS Server | |
220 | restarts itself at that time. | |
221 | ||
222 | =head1 SEE ALSO | |
223 | ||
224 | L<bos_create(8)>, | |
225 | L<bos_delete(8)>, | |
226 | L<bos_getrestart(8)>, | |
227 | L<bos_getrestricted(8)>, | |
228 | L<bos_restart(8)>, | |
229 | L<bos_setrestart(8)>, | |
230 | L<bos_setrestricted(8)>, | |
231 | L<bos_shutdown(8)>, | |
232 | L<bos_start(8)>, | |
233 | L<bos_startup(8)>, | |
234 | L<bos_status(8)>, | |
235 | L<bos_stop(8)>, | |
236 | L<bos_salvage(8)>, | |
237 | L<fileserver(8)>, | |
238 | L<salvager(8)>, | |
239 | L<volserver(8)> | |
240 | ||
241 | =head1 COPYRIGHT | |
242 | ||
243 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
244 | ||
245 | This documentation is covered by the IBM Public License Version 1.0. It was | |
246 | converted from HTML to POD by software written by Chas Williams and Russ | |
247 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |