Commit | Line | Data |
---|---|---|
805e021f CE |
1 | =head1 NAME |
2 | ||
3 | upclient - Initializes the client portion of the Update Server | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | =for html | |
8 | <div class="synopsis"> | |
9 | ||
10 | S<<< B<upclient> <I<hostname>> >>> [B<-crypt>] [B<-clear>] S<<< [B<-t> <I<retry time>>] >>> | |
11 | [B<-verbose>]* <I<dir>>+ [B<-help>] | |
12 | ||
13 | =for html | |
14 | </div> | |
15 | ||
16 | =head1 DESCRIPTION | |
17 | ||
18 | The upclient command initializes the client portion of the Update | |
19 | Server. In the conventional configuration, its binary file is located in | |
20 | the F</usr/afs/bin> directory on a file server machine. | |
21 | ||
22 | The upclient command is not normally issued at the command shell prompt | |
23 | but rather placed into a file server machine's F</usr/afs/local/BosConfig> | |
24 | file with the B<bos create> command. If it is ever issued at the command | |
25 | shell prompt, the issuer must be logged onto a database server machine as | |
26 | the local superuser C<root>. | |
27 | ||
28 | The upclient process periodically checks that all files in each local | |
29 | directory named by the I<dir> argument match the files in the | |
30 | corresponding directory on the source machine named by the I<hostname> | |
31 | argument. If a file does not match, the B<upclient> process requests the | |
32 | source copy from the B<upserver> process running on the source machine. | |
33 | ||
34 | By default, the B<upclient> process requests that the B<upserver> process | |
35 | encrypt the data before transferring it. Use the B<-clear> flag to | |
36 | request unencrypted transfer if appropriate. (The B<-crypt> flag | |
37 | explicitly sets the default.) | |
38 | ||
39 | In the conventional configuration, separate instances of the B<upclient> | |
40 | process request data from the F</usr/afs/bin> and F</usr/afs/etc> | |
41 | directories, except on machines for which the system control machine is | |
42 | also the binary distribution machine for the machine's system type. The | |
43 | conventional names for the separate instances are C<upclientbin> and | |
44 | C<upclientetc> respectively. | |
45 | ||
46 | The B<upclient> and B<upserver> processes always mutually authenticate, | |
47 | whether or not the data they pass is encrypted; they use the key with the | |
48 | highest key version number in the F</usr/afs/etc/KeyFile> file to | |
49 | construct a server ticket for mutual authentication. | |
50 | ||
51 | This command does not use the syntax conventions of the AFS command | |
52 | suites. Provide the command name and all option names in full. | |
53 | ||
54 | =head1 CAUTIONS | |
55 | ||
56 | Do not use the Update Server to distribute the contents of the | |
57 | F</usr/afs/etc> directory using the B<-clear> option. The contents of | |
58 | this directory are sensitive. | |
59 | ||
60 | =head1 OPTIONS | |
61 | ||
62 | =over 4 | |
63 | ||
64 | =item <I<hostname>> | |
65 | ||
66 | Names either the cell's system control machine (if the requested directory | |
67 | is F</usr/afs/etc>), or the binary distribution machine for the local | |
68 | machine's CPU and operating system type (if the requested directory is | |
69 | F</usr/afs/bin>). | |
70 | ||
71 | =item B<-crypt> | |
72 | ||
73 | Requests the transfer of data from the upserver process in encrypted | |
74 | form. This is the default; this flag just sets the default explicitly. | |
75 | Do not use this flag with the B<-clear> flag. | |
76 | ||
77 | =item B<-clear> | |
78 | ||
79 | Requests transfer of data from the B<upserver> process in unencrypted | |
80 | form. Provide this flag or the B<-crypt> flag, but not both. | |
81 | ||
82 | =item B<-t> <I<retry time>> | |
83 | ||
84 | Specifies how often to check for changes in each specified directory, as a | |
85 | number of seconds. If this argument is omitted, the default is C<300> (5 | |
86 | minutes). This argument determines the maximum amount of time it takes for | |
87 | a change made on the source machine to propagate to this machine. | |
88 | ||
89 | =item B<-verbose>* | |
90 | ||
91 | Writes a trace of the upclient process's operations on the standard output | |
92 | stream, which usually corresponds to the machine console. Provide one, | |
93 | two, or three instances of the flag; each additional instance generates | |
94 | increasingly numerous and detailed messages. | |
95 | ||
96 | =item <I<dir>>+ | |
97 | ||
98 | Names each directory to check for modified files. The conventional choices | |
99 | are the following: | |
100 | ||
101 | =over 4 | |
102 | ||
103 | =item * | |
104 | ||
105 | F</usr/afs/bin>, in which case the recommended name for the process | |
106 | (assigned with the B<-instance> argument to the B<bos create> command) is | |
107 | C<upclientbin>. The I<hostname> is the binary distribution machine for the | |
108 | local machine's system type. You may wish to use the B<-clear> flag for | |
109 | the F</usr/afs/bin> directory, since binaries are not particularly | |
110 | sensitive and encrypting them takes system resources. | |
111 | ||
112 | =item * | |
113 | ||
114 | F</usr/afs/etc>, in which case the recommended name for the process | |
115 | (assigned with the B<-instance> argument to the B<bos create> command) is | |
116 | C<upclientetc>. The I<hostname> is the cell's system control machine. Use | |
117 | the B<-crypt> flag for the F</usr/afs/etc> directory, since it contains | |
118 | the F<KeyFile> file and other data vital to cell security. | |
119 | ||
120 | =back | |
121 | ||
122 | =item B<-help> | |
123 | ||
124 | Prints the online help for this command. All other valid options are | |
125 | ignored. | |
126 | ||
127 | =back | |
128 | ||
129 | =head1 EXAMPLES | |
130 | ||
131 | The following bos create command creates an C<upclientbin> process on the | |
132 | machine C<fs4.example.com> that refers to the machine C<fs1.example.com> as the | |
133 | source for the F</usr/afs/bin> directory (thus C<fs1.example.com> is the | |
134 | binary distribution machine for machines of C<fs4.example.com>'s type). The | |
135 | files in the F</usr/afs/bin> directory are distributed every 120 seconds. | |
136 | The command requests transfer in unencrypted form. | |
137 | ||
138 | % bos create -server fs4.example.com -instance upclientbin -type simple \ | |
139 | -cmd "/usr/afs/bin/upclient fs1.example.com -clear \ | |
140 | -t 120 /usr/afs/bin" | |
141 | ||
142 | =head1 PRIVILEGE REQUIRED | |
143 | ||
144 | The issuer must be logged in as the superuser C<root> on a file server | |
145 | machine to issue the command at a command shell prompt. It is conventional | |
146 | instead to create and start the process by issuing the B<bos create> | |
147 | command. | |
148 | ||
149 | =head1 SEE ALSO | |
150 | ||
151 | L<BosConfig(5)>, | |
152 | L<bos_create(8)>, | |
153 | L<upserver(8)> | |
154 | ||
155 | =head1 COPYRIGHT | |
156 | ||
157 | IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved. | |
158 | ||
159 | This documentation is covered by the IBM Public License Version 1.0. It was | |
160 | converted from HTML to POD by software written by Chas Williams and Russ | |
161 | Allbery, based on work by Alf Wachsmann and Elizabeth Cassell. |