doc/man-pages/pod8/upclient.pod

   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.