crypto/heimdal/lib/kadm5/iprop.8

   1 .\" $Id: iprop.8 21940 2007-09-28 22:28:09Z lha $
   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 Heimdal
  37 .Sh NAME
  38 .Nm iprop ,
  39 .Nm ipropd-master ,
  40 .Nm ipropd-slave
  41 .Nd
  42 propagate changes to a Heimdal Kerberos master KDC to slave KDCs
  43 .Sh SYNOPSIS
  44 .Nm ipropd-master
  45 .Oo Fl c Ar string \*(Ba Xo
  46 .Fl -config-file= Ns Ar string
  47 .Xc
  48 .Oc
  49 .Oo Fl r Ar string \*(Ba Xo
  50 .Fl -realm= Ns Ar string
  51 .Xc
  52 .Oc
  53 .Oo Fl k Ar kspec \*(Ba Xo
  54 .Fl -keytab= Ns Ar kspec
  55 .Xc
  56 .Oc
  57 .Oo Fl d Ar file \*(Ba Xo
  58 .Fl -database= Ns Ar file
  59 .Xc
  60 .Oc
  61 .Op Fl -slave-stats-file= Ns Ar file
  62 .Op Fl -time-missing= Ns Ar time
  63 .Op Fl -time-gone= Ns Ar time
  64 .Op Fl -detach
  65 .Op Fl -version
  66 .Op Fl -help
  67 .Nm ipropd-slave
  68 .Oo Fl c Ar string \*(Ba Xo
  69 .Fl -config-file= Ns Ar string
  70 .Xc
  71 .Oc
  72 .Oo Fl r Ar string \*(Ba Xo
  73 .Fl -realm= Ns Ar string
  74 .Xc
  75 .Oc
  76 .Oo Fl k Ar kspec \*(Ba Xo
  77 .Fl -keytab= Ns Ar kspec
  78 .Xc
  79 .Oc
  80 .Op Fl -time-lost= Ns Ar time
  81 .Op Fl -detach
  82 .Op Fl -version
  83 .Op Fl -help
  84 .Ar master
  85 .Pp
  86 .Sh DESCRIPTION
  87 .Nm ipropd-master
  88 is used to propagate changes to a Heimdal Kerberos database from the
  89 master Kerberos server on which it runs to slave Kerberos servers
  90 running
  91 .Nm ipropd-slave .
  92 .Pp
  93 The slaves are specified by the contents of the
  94 .Pa slaves
  95 file in the KDC's database directory, e.g.\&
  96 .Pa /var/heimdal/slaves .
  97 This has principals one per-line of the form
  98 .Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM
  99 where
 100 .Ar slave
 101 is the hostname of the slave server in the given
 102 .Ar REALM ,
 103 e.g.\&
 104 .Dl iprop/kerberos-1.example.com@EXAMPLE.COM
 105 On a slave, the argument
 106 .Fa master
 107 specifies the hostname of the master server from which to receive updates.
 108 .Pp
 109 In contrast to
 110 .Xr hprop 8 ,
 111 which sends the whole database to the slaves regularly,
 112 .Nm
 113 normally sends only the changes as they happen on the master.  The
 114 master keeps track of all the changes by assigning a version number to
 115 every change to the database.  The slaves know which was the latest
 116 version they saw, and in this way it can be determined if they are in
 117 sync or not.  A log of all the changes is kept on the master.  When a
 118 slave is at an older version than the oldest one in the log, the whole
 119 database has to be sent.
 120 .Pp
 121 The changes are propagated over a secure channel (on port 2121 by
 122 default).  This should normally be defined as
 123 .Dq iprop/tcp
 124 in
 125 .Pa /etc/services
 126 or another source of the services database.  The master and slaves
 127 must each have access to a keytab with keys for the
 128 .Nm iprop
 129 service principal on the local host.
 130 .Pp
 131 There is a keep-alive feature logged in the master's
 132 .Pa slave-stats
 133 file (e.g.\&
 134 .Pa /var/heimdal/slave-stats ) .
 135 .Pp
 136 Supported options for
 137 .Nm ipropd-master :
 138 .Bl -tag -width Ds
 139 .It Xo
 140 .Fl c Ar string ,
 141 .Fl -config-file= Ns Ar string
 142 .Xc
 143 .It Xo
 144 .Fl r Ar string ,
 145 .Fl -realm= Ns Ar string
 146 .Xc
 147 .It Xo
 148 .Fl k Ar kspec ,
 149 .Fl -keytab= Ns Ar kspec
 150 .Xc
 151 keytab to get authentication from
 152 .It Xo
 153 .Fl d Ar file ,
 154 .Fl -database= Ns Ar file
 155 .Xc
 156 Database (default per KDC)
 157 .It Xo
 158 .Fl -slave-stats-file= Ns Ar file
 159 .Xc
 160 file for slave status information
 161 .It Xo
 162 .Fl -time-missing= Ns Ar time
 163 .Xc
 164 time before slave is polled for presence (default 2 min)
 165 .It Xo
 166 .Fl -time-gone= Ns Ar time
 167 .Xc
 168 time of inactivity after which a slave is considered gone (default 5 min)
 169 .It Xo
 170 .Fl -detach
 171 .Xc
 172 detach from console
 173 .It Xo
 174 .Fl -version
 175 .Xc
 176 .It Xo
 177 .Fl -help
 178 .Xc
 179 .El
 180 .Pp
 181 Supported options for
 182 .Nm ipropd-slave :
 183 .Bl -tag -width Ds
 184 .It Xo
 185 .Fl c Ar string ,
 186 .Fl -config-file= Ns Ar string
 187 .Xc
 188 .It Xo
 189 .Fl r Ar string ,
 190 .Fl -realm= Ns Ar string
 191 .Xc
 192 .It Xo
 193 .Fl k Ar kspec ,
 194 .Fl -keytab= Ns Ar kspec
 195 .Xc
 196 keytab to get authentication from
 197 .It Xo
 198 .Fl -time-lost= Ns Ar time
 199 .Xc
 200 time before server is considered lost (default 5 min)
 201 .It Xo
 202 .Fl -detach
 203 .Xc
 204 detach from console
 205 .It Xo
 206 .Fl -version
 207 .Xc
 208 .It Xo
 209 .Fl -help
 210 .Xc
 211 .El
 212 Time arguments for the relevant options above may be specified in forms
 213 like 5 min, 300 s, or simply a number of seconds.
 214 .Sh FILES
 215 .Pa slaves ,
 216 .Pa slave-stats
 217 in the database directory.
 218 .Sh SEE ALSO
 219 .Xr hpropd 8 ,
 220 .Xr hprop 8 ,
 221 .Xr krb5.conf 8 ,
 222 .Xr kdc 8 ,
 223 .Xr iprop-log 8 .