Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | vlserver - Initializes the Volume Location Server | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | vlserver [B<-noauth>] [B<-smallmem>] | |
11 | S<<< [B<-p> <I<number of threads>>] >>> [B<-nojumbo>] | |
12 | [B<-jumbo>] [B<-rxbind>] | |
13 | S<<< [B<-d> <I<debug level>>] >>> | |
14 | S<<< [B<-rxmaxmtu> <I<bytes>>] >>> | |
15 | S<<< [B<-trace> <I<trace file>>] >>> | |
16 | [B<-allow-dotted-principals>] | |
17 | S<<< [B<-database> | B<-db> <I<database path>>] >>> | |
18 | S<<< [B<-logfile> <I<log file>>] >>> | |
19 | [B<-transarc-logs>] | |
20 | S<<< [B<-config> <I<configuration path>>] >>> | |
21 | S<<< [B<-syslog>[=<I<facility>>]>] >>> | |
22 | [B<-enable_peer_stats>] [B<-enable_process_stats>] | |
23 | S<<< [B<-auditlog> <I<log path>>] >>> | |
24 | S<<< [B<-audit-interface> (file | sysvmq)] >>> | |
25 | S<<< [B<-restricted_query> (anyuser | admin)] >>> | |
26 | [B<-help>] | |
27 | ||
28 | =for html | |
29 | </div> | |
30 | ||
31 | =head1 DESCRIPTION | |
32 | ||
33 | The B<vlserver> command initializes the Volume Location (VL) Server, which | |
34 | runs on every database server machine. In the conventional configuration, | |
35 | its binary file is located in the F</usr/afs/bin> directory on a file | |
36 | server machine. | |
37 | ||
38 | The B<vlserver> command is not normally issued at the command shell prompt | |
39 | but rather placed into a file server machine's F</usr/afs/local/BosConfig> | |
40 | file with the B<bos create> command. If it is ever issued at the command | |
41 | shell prompt, the issuer must be logged onto a database server machine as | |
42 | the local superuser C<root>. | |
43 | ||
44 | As it initializes, the VL Server process creates the two files that | |
45 | constitute the Volume Location Database (VLDB), F<vldb.DB0> and | |
46 | F<vldb.DBSYS1>, in the F</usr/afs/db> directory if they do not already | |
47 | exist. Use the commands in the B<vos> suite to administer the database. | |
48 | ||
49 | The VL Server maintains the record of volume locations in the Volume | |
50 | Location Database (VLDB). When the Cache Manager fills a file request from | |
51 | an application program, it first contacts the VL Server to learn which | |
52 | file server machine currently houses the volume that contains the file. | |
53 | The Cache Manager then requests the file from the File Server process | |
54 | running on that file server machine. | |
55 | ||
56 | The VL Server records a trace of its activity in the | |
57 | F</usr/afs/logs/VLLog> file. Use the B<bos getlog> command to display the | |
58 | contents of the file. By default, it records on a minimal number of | |
59 | messages. For instructions on increasing the amount of logging, see | |
60 | L<VLLog(5)>. | |
61 | ||
62 | By default, the VL Server runs nine lightweight processes (LWPs). To | |
63 | change the number, use the B<-p> argument. | |
64 | ||
65 | This command does not use the syntax conventions of the AFS command | |
66 | suites. Provide the command name and all option names in full. | |
67 | ||
68 | =head1 OPTIONS | |
69 | ||
70 | =over 4 | |
71 | ||
72 | =item B<-d> <I<debug level>> | |
73 | ||
74 | Sets the detail level for the debugging trace written to the | |
75 | F</usr/afs/logs/VLLog> file. Provide one of the following values, each | |
76 | of which produces an increasingly detailed trace: C<0>, C<1>, C<5>, C<25>, | |
77 | and C<125>. | |
78 | ||
79 | =item B<-p> <I<number of threads>> | |
80 | ||
81 | Sets the number of server lightweight processes (LWPs or pthreads) to run. | |
82 | Provide an integer between C<3> and C<64>. The default is C<9>. | |
83 | ||
84 | =item B<-jumbo> | |
85 | ||
86 | Allows the server to send and receive jumbograms. A jumbogram is | |
87 | a large-size packet composed of 2 to 4 normal Rx data packets that share | |
88 | the same header. The VL Server does not use jumbograms by default, as some | |
89 | routers are not capable of properly breaking the jumbogram into smaller | |
90 | packets and reassembling them. | |
91 | ||
92 | =item B<-nojumbo> | |
93 | ||
94 | Deprecated; Jumbograms are disabled by default. | |
95 | ||
96 | =item B<-enable_peer_stats> | |
97 | ||
98 | Activates the collection of Rx statistics and allocates memory for their | |
99 | storage. For each connection with a specific UDP port on another machine, | |
100 | a separate record is kept for each type of RPC (FetchFile, GetStatus, and | |
101 | so on) sent or received. To display or otherwise access the records, use | |
102 | the Rx Monitoring API. | |
103 | ||
104 | =item B<-enable_process_stats> | |
105 | ||
106 | Activates the collection of Rx statistics and allocates memory for their | |
107 | storage. A separate record is kept for each type of RPC (FetchFile, | |
108 | GetStatus, and so on) sent or received, aggregated over all connections to | |
109 | other machines. To display or otherwise access the records, use the Rx | |
110 | Monitoring API. | |
111 | ||
112 | =item B<-allow-dotted-principals> | |
113 | ||
114 | By default, the RXKAD security layer will disallow access by Kerberos | |
115 | principals with a dot in the first component of their name. This is to avoid | |
116 | the confusion where principals user/admin and user.admin are both mapped to the | |
117 | user.admin PTS entry. Sites whose Kerberos realms don't have these collisions | |
118 | between principal names may disable this check by starting the server | |
119 | with this option. | |
120 | ||
121 | =item B<-auditlog> <I<log path>> | |
122 | ||
123 | Turns on audit logging, and sets the path for the audit log. The audit | |
124 | log records information about RPC calls, including the name of the RPC | |
125 | call, the host that submitted the call, the authenticated entity (user) | |
126 | that issued the call, the parameters for the call, and if the call | |
127 | succeeded or failed. | |
128 | ||
129 | =item B<-audit-interface> (file | sysvmq) | |
130 | ||
131 | Specifies what audit interface to use. Defaults to C<file>. See | |
132 | L<fileserver(8)> for an explanation of each interface. | |
133 | ||
134 | =item B<-rxbind> | |
135 | ||
136 | Bind the Rx socket to the primary interface only. (If not specified, the | |
137 | Rx socket will listen on all interfaces.) | |
138 | ||
139 | =item B<-syslog>[=<I<syslog facility>>] | |
140 | ||
141 | Specifies that logging output should go to syslog instead of the normal log | |
142 | file. B<-syslog>=I<FACILITY> can be used to specify to which facility the log | |
143 | message should be sent. Logging message sent to syslog are tagged with the | |
144 | string "vlserver". | |
145 | ||
146 | =item B<-noauth> | |
147 | ||
148 | Turns off all authorization checks, and allows all connecting users to act as | |
149 | administrators, even unauthenticated users. The use of this option is | |
150 | inherently insecure, and should only be used in controlled environments for | |
151 | experimental or debug purposes. See L<NoAuth(5)>. | |
152 | ||
153 | =item B<-smallmem> | |
154 | ||
155 | Specifies that the vlserver should limit its memory usage during certain | |
156 | operations, and return an error to the calling client instead of allocating | |
157 | more memory. This option is only useful on systems where memory is severely | |
158 | limited, and should not be needed on any remotely modern system. | |
159 | ||
160 | =item B<-rxmaxmtu> <I<bytes>> | |
161 | ||
162 | Sets the maximum transmission unit for the RX protocol. | |
163 | ||
164 | =item B<-trace> <I<trace file>> | |
165 | ||
166 | Turns on low-level Rx packet tracing, and logs the trace information to the | |
167 | specified file. The trace file can be later dumped into a human-readable form | |
168 | with a tool called B<dumptrace>. | |
169 | ||
170 | It is not recommended to turn on this option during normal operation, since the | |
171 | detailed tracing may cause performance issues and use up a lot of disk space. | |
172 | ||
173 | =item B<-logfile> <I<log file>> | |
174 | ||
175 | Sets the file to use for server logging. If logfile is not specified, and | |
176 | no other logging options are supplied, this will be F</usr/afs/logs/VLLog>. | |
177 | Note that this option is intended for debugging and testing purposes. | |
178 | Changing the location of the log file from the command line may result | |
179 | in undesirable interactions with tools such as B<bos>. | |
180 | ||
181 | =item B<-transarc-logs> | |
182 | ||
183 | Use Transarc style logging features. Rename the log file | |
184 | F</usr/afs/logs/VLLog> to F</usr/afs/logs/VLLog.old> when the VL Server is | |
185 | restarted. This option is provided for compatibility with older versions. | |
186 | ||
187 | =item B<-database> | B<-db> <I<database path>> | |
188 | ||
189 | Set the location of the database used by this program. This option is | |
190 | intended primarily for testing purposes. | |
191 | ||
192 | =item B<-config> <I<configuration directory>> | |
193 | ||
194 | Set the location of the configuration directory used to configure this | |
195 | service. In a typical configuration this will be F</usr/afs/etc> - this | |
196 | option allows the use of alternative configuration locations for testing | |
197 | purposes. | |
198 | ||
199 | =item B<-restricted_query> (anyuser | admin) | |
200 | ||
201 | Restrict RPCs that query information about volumes to a specific group | |
202 | of users. Only the RPCs that are not used by cache managers will be | |
203 | restricted, since cache manager connections to the Volume Server are | |
204 | always unauthenticated. You can use C<admin> to restrict to AFS | |
205 | administrators. The C<anyuser> option doesn't restrict the RPCs and | |
206 | leaves it open for all users including unauthenticated users, this is | |
207 | the default. | |
208 | ||
209 | =item B<-help> | |
210 | ||
211 | Prints the online help for this command. All other valid options are | |
212 | ignored. | |
213 | ||
214 | =back | |
215 | ||
216 | =head1 EXAMPLES | |
217 | ||
218 | The following B<bos create> command creates a vlserver process on the | |
219 | machine C<fs2.example.com> that uses six lightweight processes. Type the | |
220 | command on a single line: | |
221 | ||
222 | % bos create -server fs2.example.com -instance vlserver -type simple \ | |
223 | -cmd "/usr/afs/bin/vlserver -p 6" | |
224 | ||
225 | =head1 PRIVILEGE REQUIRED | |
226 | ||
227 | The issuer must be logged in as the superuser C<root> on a file server | |
228 | machine to issue the command at a command shell prompt. It is conventional | |
229 | instead to create and start the process by issuing the B<bos create> | |
230 | command. | |
231 | ||
232 | =head1 SEE ALSO | |
233 | ||
234 | L<BosConfig(5)>, | |
235 | L<VLLog(5)>, | |
236 | L<vldb.DB0(5)>, | |
237 | L<bos_create(8)>, | |
238 | L<bos_getlog(8)> | |
239 | ||
240 | =head1 COPYRIGHT | |
241 | ||
242 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
243 | ||
244 | This documentation is covered by the IBM Public License Version 1.0. It was | |
245 | converted from HTML to POD by software written by Chas Williams and Russ | |
246 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |