third_party/heimdal/lib/kadm5/iprop.8

   1 .\" $Id$
   2 .\"
   3 .\" Copyright (c) 2005 Kungliga Tekniska Högskolan
   4 .\" (Royal Institute of Technology, Stockholm, Sweden).
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\"
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\"
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" 3. Neither the name of the Institute nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .Dd May 24, 2005
  35 .Dt IPROP 8
  36 .Os
  37 .Sh NAME
  38 .Nm iprop ,
  39 .Nm ipropd-master ,
  40 .Nm ipropd-slave
  41 .Nd propagate transactions from a Heimdal Kerberos master KDC to slave KDCs
  42 .Sh SYNOPSIS
  43 .Nm ipropd-master
  44 .Oo Fl c Ar string \*(Ba Xo
  45 .Fl Fl config-file= Ns Ar string
  46 .Xc
  47 .Oc
  48 .Oo Fl r Ar string \*(Ba Xo
  49 .Fl Fl realm= Ns Ar string
  50 .Xc
  51 .Oc
  52 .Oo Fl k Ar kspec \*(Ba Xo
  53 .Fl Fl keytab= Ns Ar kspec
  54 .Xc
  55 .Oc
  56 .Oo Fl d Ar file \*(Ba Xo
  57 .Fl Fl database= Ns Ar file
  58 .Xc
  59 .Oc
  60 .Op Fl Fl slave-stats-file= Ns Ar file
  61 .Op Fl Fl time-missing= Ns Ar time
  62 .Op Fl Fl time-gone= Ns Ar time
  63 .Op Fl Fl detach
  64 .Op Fl Fl version
  65 .Op Fl Fl help
  66 .Nm ipropd-slave
  67 .Oo Fl c Ar string \*(Ba Xo Fl Fl config-file= Ns Ar string Xc Oc
  68 .Oo Fl r Ar string \*(Ba Xo Fl Fl realm= Ns Ar string Xc Oc
  69 .Oo Fl d Ar file \*(Ba Xo Fl Fl database= Ns Ar file Xc Oc
  70 .Oo Fl k Ar kspec \*(Ba Xo Fl Fl keytab= Ns Ar kspec Xc Oc
  71 .Op Fl Fl statusfile= Ns Ar file
  72 .Op Fl Fl hostname= Ns Ar hostname
  73 .Op Fl Fl port= Ns Ar port
  74 .Op Fl Fl time-lost= Ns Ar time
  75 .Op Fl Fl async-hdb
  76 .Op Fl Fl detach
  77 .Op Fl Fl version
  78 .Op Fl Fl help
  79 .Ar master
  80 .Sh DESCRIPTION
  81 .Nm ipropd-master
  82 is used to propagate changes to a Heimdal Kerberos database from the
  83 master Kerberos server on which it runs to slave Kerberos servers
  84 running
  85 .Nm ipropd-slave .
  86 .Pp
  87 The slaves are specified by the contents of the
  88 .Pa slaves
  89 file in the KDC's database directory, e.g.\&
  90 .Pa /var/heimdal/slaves .
  91 This has principals one per-line of the form
  92 .Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM
  93 where
  94 .Ar slave
  95 is the hostname of the slave server in the given
  96 .Ar REALM ,
  97 e.g.\&
  98 .Dl iprop/kerberos-1.example.com@EXAMPLE.COM
  99 On a slave, the argument
 100 .Fa master
 101 specifies the hostname of the master server from which to receive updates.
 102 .Pp
 103 In contrast to
 104 .Xr hprop 8 ,
 105 which sends the whole database to the slaves regularly,
 106 .Nm
 107 normally sends only the changes as they happen on the master.
 108 The master keeps track of all the changes by assigning a version
 109 number to every transaction to the database.
 110 The slaves know which was the latest version they saw, and in this
 111 way it can be determined if they are in sync or not.
 112 A log of all the transactions is kept on the master.
 113 When a slave is at an older version than the oldest one in the log,
 114 the whole database has to be sent.
 115 .Pp
 116 The log of transactions is also used to implement a two-phase commit
 117 (with roll-forward for recovery) method of updating the HDB.
 118 Transactions are first recorded in the log, then in the HDB, then
 119 the log is updated to mark the transaction as committed.
 120 .Pp
 121 The changes are propagated over a secure channel (on port 2121 by
 122 default).
 123 This should normally be defined as
 124 .Dq iprop/tcp
 125 in
 126 .Pa /etc/services
 127 or another source of the services database.
 128 The master and slaves
 129 must each have access to a keytab with keys for the
 130 .Nm iprop
 131 service principal on the local host.
 132 .Pp
 133 There is a keep-alive feature logged in the master's
 134 .Pa slave-stats
 135 file (e.g.\&
 136 .Pa /var/heimdal/slave-stats ) .
 137 .Pp
 138 Note that hierarchical replication is supported by running
 139 an
 140 .Nm ipropd-master
 141 on the same KDC as an
 142 .Nm ipropd-slave .
 143 .Pp
 144 Supported options for
 145 .Nm ipropd-master :
 146 .Bl -tag -width Ds
 147 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 148 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 149 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 150 Keytab for authenticating
 151 .Nm ipropd-slave
 152 clients.
 153 .It Fl d Ar file , Fl Fl database= Ns Ar file
 154 Database (default per KDC)
 155 .It Fl Fl slave-stats-file= Ns Ar file
 156 File for slave status information.
 157 .It Fl Fl time-missing= Ns Ar time
 158 Time before slave is polled for presence (default 2 min).
 159 .It Fl Fl time-gone= Ns Ar time
 160 Time of inactivity after which a slave is considered gone (default 5 min).
 161 .It Fl Fl detach
 162 Detach from console.
 163 .It Fl Fl version
 164 .It Fl Fl help
 165 .El
 166 .Pp
 167 Supported options for
 168 .Nm ipropd-slave :
 169 .Bl -tag -width Ds
 170 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 171 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 172 .It Fl d Ar file , Fl Fl database= Ns Ar file
 173 Database (default per KDC)
 174 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 175 Keytab with client credentials for authenticating to
 176 .Nm ipropd-master .
 177 .It Fl Fl status-file= Ns Ar file
 178 .It Fl Fl hostname= Ns Ar hostname
 179 Hostname for client principal if different from actual hostname.
 180 .It Fl Fl port= Ns Ar port
 181 .It Fl Fl time-lost= Ns Ar time
 182 time before server is considered lost (default 5 min)
 183 .It Fl Fl async-hdb
 184 Use asynchronous writes.
 185 This is very useful for very busy sites or sites with very large
 186 HDBs.
 187 .It Fl Fl detach
 188 Detach from console.
 189 .It Fl Fl version
 190 .It Fl Fl help
 191 .El
 192 Time arguments for the relevant options above may be specified in forms
 193 like 5 min, 300 s, or simply a number of seconds.
 194 .Sh FILES
 195 .Pa slaves ,
 196 .Pa slave-stats
 197 in the database directory.
 198 .Pa ipropd-master.pid ,
 199 .Pa ipropd-slave.pid
 200 in the database directory, or in the directory named by the
 201 .Ev HEIM_PIDFILE_DIR
 202 environment variable.
 203 .Sh SEE ALSO
 204 .Xr krb5.conf 5 ,
 205 .Xr hprop 8 ,
 206 .Xr hpropd 8 ,
 207 .Xr iprop-log 8 ,
 208 .Xr kdc 8 .