06a03c5e65cd4b2486b7df9bceb2674f91794308
[openafs.git] / doc / man-pages / pod8 / upserver.pod
1 =head1 NAME
2
3 upserver - Initializes the server portion of the Update Server
4
5 =head1 SYNOPSIS
6
7 =for html
8 <div class="synopsis">
9
10 B<upserver> [<I<directory>>+] S<<< [B<-crypt> <I<directory>>+] >>>
11     S<<< [B<-clear> <I<directory>>+] >>> S<<< [B<-auth> <I<directory>>+] >>>
12     [B<-rxbind>] [B<-help>]
13
14 =for html
15 </div>
16
17 =head1 DESCRIPTION
18
19 The B<upserver> command initializes the server portion of the Update
20 Server (the C<upserver> process). In the conventional configuration, its
21 binary file is located in the F</usr/afs/bin> directory on a file server
22 machine.
23
24 The B<upserver> command is not normally issued at the command shell prompt
25 but rather placed into a file server machine's F</usr/afs/local/BosConfig>
26 file with the B<bos create> command. If it is ever issued at the command
27 shell prompt, the issuer must be logged onto a database server machine as
28 the local superuser C<root>.
29
30 The B<upserver> command specifies which of the directories on the local
31 disk are eligible for distribution in response to requests from the client
32 portion of the Update Server (the B<upclient> process) running on other
33 machines. If no directories are specified, the B<upserver> process
34 distributes the contents of any directory on its local disk.
35
36 The B<upserver> process can distribute a directory's contents in encrypted
37 or unencrypted form. By default, it does not use encryption unless an
38 B<upclient> process requests it (this default is equivalent to setting the
39 B<-clear> flag). When the B<-crypt> flag is provided, the B<upserver>
40 process only fulfills requests for encrypted transfer.
41
42 The B<upclient> and B<upserver> processes always mutually authenticate,
43 whether or not the data they pass is encrypted; they use the key with the
44 highest key version number in the F</usr/afs/etc/KeyFile> file to
45 construct a server ticket for mutual authentication.
46
47 This command does not use the syntax conventions of the AFS command
48 suites. Provide the command name and all option names in full.
49
50 =head1 CAUTIONS
51
52 Do not use the Update Server to distribute the contents of the
53 F</usr/afs/etc> directory without the B<-crypt> flag.  The contents of
54 this directory are sensitive.
55
56 =head1 OPTIONS
57
58 =over 4
59
60 =item <I<directory>>+
61
62 Names each directory to distribute in unencrypted form (because they
63 appear before the first B<-crypt> or B<-clear> flag on the command
64 line). If this argument is omitted, all directories on the machine's local
65 disk are eligible for distribution.
66
67 =item B<-crypt> <I<directory>>+
68
69 Precedes a list of one or more directories that the B<upserver> process
70 distributes only in encrypted form.
71
72 =item B<-clear> <I<directory>>+
73
74 Precedes a list of one or more directories that the B<upserver> process
75 distributes in unencrypted form unless the B<upclient> process requests
76 them in encrypted form. Use this argument only if a list of directories
77 headed by the B<-crypt> flag precedes it on the command line.
78
79 =item B<-auth> <I<directory>>+
80
81 Precedes a list of one or more directories which the upserver process
82 distributes using a form of encryption that is intermediate in complexity
83 and security between the unencrypted and encrypted levels set by the
84 B<-clear> and B<-crypt> arguments. Do not use this argument, because the
85 B<upclient> process does not have a corresponding argument that it can use
86 to request data transfer at this level.
87
88 =item B<-rxbind>
89
90 Bind the Rx socket to the primary interface only. (If not specified, the Rx
91 socket will listen on all interfaces.)
92
93 =item B<-help>
94
95 Prints the online help for this command. All other valid options are
96 ignored.
97
98 =back
99
100 =head1 EXAMPLES
101
102 The following example bos create command defines and starts an B<upserver>
103 process on the host machine C<fs1.example.com>. The last parameter (enclosed
104 in quotes) instructs the B<upserver> process to distribute the contents of
105 the F</usr/afs/bin> directory in unencrypted form and the contents of the
106 F</usr/afs/etc> directory in encrypted form.
107
108    % bos create  -server fs1.example.com -instance upserver -type simple \
109        -cmd "/usr/afs/bin/upserver /usr/afs/bin -crypt /usr/afs/etc"
110
111 =head1 PRIVILEGE REQUIRED
112
113 The issuer must be logged in as the superuser C<root> on a file server
114 machine to issue the command at a command shell prompt. It is conventional
115 instead to create and start the process by issuing the B<bos create>
116 command.
117
118 =head1 SEE ALSO
119
120 L<BosConfig(5)>,
121 L<bos_create(8)>,
122 L<upclient(8)>
123
124 =head1 COPYRIGHT
125
126 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
127
128 This documentation is covered by the IBM Public License Version 1.0.  It was
129 converted from HTML to POD by software written by Chas Williams and Russ
130 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.