doc/man-pages/pod8/kaserver.pod

   1 =head1 NAME
   2
   3 kaserver - Initializes the Authentication Server
   4
   5 =head1 SYNOPSIS
   6
   7 =for html
   8 <div class="synopsis">
   9
  10 B<kaserver> [B<-noAuth>] [B<-database> <I<dbpath>>]
  11     S<<< [B<-auditlog> [<I<interface name>>:]<I<path to log file>>[:<I<parameters to interface>>]] >>>
  12     S<<< [B<-audit-interface> <I<interface name>>] >>>
  13     S<<< [B<-localfiles> <I<lclpath>>] >>> S<<< [B<-minhours> <I<n>>] >>>
  14     S<<< [B<-servers> <I<serverlist>>] >>> [B<-enable_peer_stats>]
  15     [B<-enable_process_stats>] [B<-rxbind>] [B<-crossrealm>] [B<-help>]
  16
  17 =for html
  18 </div>
  19
  20 =head1 DESCRIPTION
  21
  22 The B<kaserver> command initializes the Authentication Server, an obsolete
  23 way of providing authentication services to an AFS cell. It should no
  24 longer be used; instead, it should be replaced with a Kerberos version 5
  25 KDC. It is provided only for support of sites already running the
  26 Authentication Server and that have not yet migrated to Kerberos version
  27 5.
  28
  29 For a cell using the Authentication Server, it runs on every database
  30 server machine. In the conventional configuration, its binary file is
  31 located in the F</usr/afs/bin> directory on a file server machine.
  32
  33 The B<kaserver> command is not normally issued at the command shell prompt
  34 but rather placed into a file server machine's F</usr/afs/local/BosConfig>
  35 file with the B<bos create> command. If it is ever issued at the command
  36 shell prompt, the issuer must be logged onto a database server machine as
  37 the local superuser C<root>.
  38
  39 As it initializes, the Authentication Server process creates the two files
  40 that constitute the Authentication Database, F<kaserver.DB0> and
  41 F<kaserver.DBSYS1>, in the F</usr/afs/db> directory if they do not already
  42 exist. Use the commands in the B<kas> suite to administer the database.
  43
  44 The Authentication Server is responsible for several aspects of AFS
  45 security, including:
  46
  47 =over 4
  48
  49 =item *
  50
  51 Maintenance of all AFS server encryption keys and user passwords in the
  52 Authentication Database.
  53
  54 =item *
  55
  56 Creation of the tickets and tokens that users and servers use to establish
  57 secure connections. Its Ticket Granting Service (TGS) component performs
  58 this function.
  59
  60 =back
  61
  62 The Authentication Server records a trace of its activity in the
  63 F</usr/afs/logs/AuthLog> file. Use the B<bos getlog> command to display
  64 the contents of the file. Use the B<kdb> command to read the protected
  65 files associated with the F<AuthLog> file, F<AuthLog.dir> and
  66 F<AuthLog.pag>.
  67
  68 This command does not use the syntax conventions of the AFS command
  69 suites. Provide the command name and all option names in full.
  70
  71 =head1 CAUTIONS
  72
  73 The Authentication Server provides only Kerberos version 4, which is no
  74 longer considered sufficiently secure. It can only use DES encryption for
  75 user keys, is vulnerable to known flaws in the Kerberos version 4
  76 protocol, and is based on protocols that are obsolete and no longer
  77 developed. The Authentication Server is also not widely tested and is
  78 known to have problems on some platforms OpenAFS otherwise supports.
  79
  80 The Authentication Server should not be used for any new deployment. It is
  81 provided only for sites that need to use it while preparing for a
  82 migration to Kerberos KDC. No significant updates to the Authentication
  83 Server will be developed, and it will be removed from a future version of
  84 OpenAFS.
  85
  86 =head1 OPTIONS
  87
  88 =over 4
  89
  90 =item B<-noAuth>
  91
  92 Assigns the unprivileged identity C<anonymous> to the issuer. Thus, it
  93 establishes an unauthenticated connection between the issuer and the
  94 Authentication Server. It is useful only when authorization checking is
  95 disabled on the database server machine. In normal circumstances, the
  96 Authentication Server allows only authorized (privileged) users to issue
  97 commands that affect or contact the Authentication Database and will
  98 refuse to perform such an action even if the B<-noAuth> flag is used.
  99
 100 =item B<-database> <I<dbpath>>
 101
 102 Specifies the pathname of an alternate directory in which the
 103 Authentication Database files reside. Provide the complete pathname,
 104 ending in the base filename to which the C<.DB0> and C<.DBSYS1> extensions
 105 are appended. For example, the appropriate value for the default database
 106 files is F</usr/afs/db/kaserver>.
 107
 108 Provide the B<-localfiles> argument along with this one; otherwise, the
 109 B<-localfiles> argument is also set to the value of this argument, which
 110 is probably inappropriate.
 111
 112 =item B<-auditlog> [<I<interface name>>:]<I<path to log file>>[:<I<parameters to interface>>]
 113
 114 Turns on audit logging, and sets the path for the audit log.  The audit
 115 log records information about RPC calls, including the name of the RPC
 116 call, the host that submitted the call, the authenticated entity (user)
 117 that issued the call, the parameters for the call, and if the call
 118 succeeded or failed.  See L<fileserver(8)> for an explanation of the audit
 119 facility.
 120
 121 Note: kaserver supports only a single -auditlog.
 122
 123 =item B<-audit-interface> <I<interface name>>
 124
 125 Sets the default audit interface used by the B<-auditlog> option.  The
 126 initial default is the C<file> interface. See L<fileserver(8)> for
 127 an explanation of each interface.
 128
 129 =item B<-localfiles> <I<lclpath>>
 130
 131 Specifies the pathname of an alternate directory in which the auxiliary
 132 Authentication Database file resides. Provide the complete pathname,
 133 ending in the base filename to which the C<auxdb> suffix is appended. For
 134 example, the appropriate value for the default auxiliary database file is
 135 F</usr/afs/local/kaserver>.
 136
 137 =item B<-minhours> <I<n>>
 138
 139 Specifies the minimum number of hours that must pass between password
 140 changes made by any regular user. System administrators (with the C<ADMIN>
 141 flag in their Authentication Database entry) can change passwords as often
 142 as desired. Setting a minimum time between password changes is not
 143 recommended.
 144
 145 =item B<-servers> <I<authentication servers>>+
 146
 147 Names each database server machine running an Authentication Server with
 148 which the local Authentication Server is to synchronize its copy of the
 149 Authentication Database, rather than with the machines listed in the local
 150 F</usr/afs/etc/CellServDB> file.
 151
 152 =item B<-enable_peer_stats>
 153
 154 Activates the collection of Rx statistics and allocates memory for their
 155 storage. For each connection with a specific UDP port on another machine,
 156 a separate record is kept for each type of RPC (FetchFile, GetStatus, and
 157 so on) sent or received. To display or otherwise access the records, use
 158 the Rx Monitoring API.
 159
 160 =item B<-enable_process_stats>
 161
 162 Activates the collection of Rx statistics and allocates memory for their
 163 storage. A separate record is kept for each type of RPC (FetchFile,
 164 GetStatus, and so on) sent or received, aggregated over all connections to
 165 other machines. To display or otherwise access the records, use the Rx
 166 Monitoring API.
 167
 168 =item B<-rxbind>
 169
 170 Bind the Rx socket to the primary interface only. (If not specified, the Rx
 171 socket will listen on all interfaces.)
 172
 173 =item B<-crossrealm>
 174
 175 Enable cross-realm authentication. The use of this option is considered
 176 insecure, and thus strongly discouraged. See OPENAFS-SA-2003-001.
 177
 178 =item B<-help>
 179
 180 Prints the online help for this command. All other valid options are
 181 ignored.
 182
 183 =back
 184
 185 =head1 EXAMPLES
 186
 187 The following B<bos create> command creates a C<kaserver> process on
 188 C<fs3.example.com> (the command appears on two lines here only for
 189 legibility):
 190
 191    % bos create -server fs3.example.com -instance kaserver \
 192                 -type simple -cmd /usr/afs/bin/kaserver
 193
 194 =head1 PRIVILEGE REQUIRED
 195
 196 The issuer must be logged in as the superuser C<root> on a file server
 197 machine to issue the command at a command shell prompt. It is conventional
 198 instead to create and start the process by issuing the B<bos create>
 199 command.
 200
 201 =head1 SEE ALSO
 202
 203 L<AuthLog(5)>,
 204 L<BosConfig(5)>,
 205 L<CellServDB(5)>,
 206 L<kaserver.DB0(5)>,
 207 L<kaserverauxdb(5)>,
 208 L<bos(8)>,
 209 L<bos_create(8)>,
 210 L<bos_getlog(8)>,
 211 L<kas(8)>,
 212 L<kdb(8)>
 213
 214 =head1 COPYRIGHT
 215
 216 IBM Corporation 2000. <http://www.ibm.com/> All Rights Reserved.
 217
 218 This documentation is covered by the IBM Public License Version 1.0.  It was
 219 converted from HTML to POD by software written by Chas Williams and Russ
 220 Allbery, based on work by Alf Wachsmann and Elizabeth Cassell.