crypto/dist/heimdal/lib/kadm5/iprop.8

   1 .\" $Heimdal: iprop.8 21940 2007-09-28 22:28:09Z lha $
   2 .\" $NetBSD: iprop.8,v 1.3 2009/10/25 01:52:04 reed Exp $
   3 .\"
   4 .\" Copyright (c) 2005 Kungliga Tekniska Högskolan
   5 .\" (Royal Institute of Technology, Stockholm, Sweden).
   6 .\" All rights reserved.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\"
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\"
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\"
  19 .\" 3. Neither the name of the Institute nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .Dd May 24, 2005
  36 .Dt IPROP 8
  37 .Os
  38 .Sh NAME
  39 .Nm iprop ,
  40 .Nm ipropd-master ,
  41 .Nm ipropd-slave
  42 .Nd 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 Fl config-file= Ns Ar string
  47 .Xc
  48 .Oc
  49 .Oo Fl r Ar string \*(Ba Xo
  50 .Fl Fl realm= Ns Ar string
  51 .Xc
  52 .Oc
  53 .Oo Fl k Ar kspec \*(Ba Xo
  54 .Fl Fl keytab= Ns Ar kspec
  55 .Xc
  56 .Oc
  57 .Oo Fl d Ar file \*(Ba Xo
  58 .Fl Fl database= Ns Ar file
  59 .Xc
  60 .Oc
  61 .Op Fl Fl slave-stats-file= Ns Ar file
  62 .Op Fl Fl time-missing= Ns Ar time
  63 .Op Fl Fl time-gone= Ns Ar time
  64 .Op Fl Fl detach
  65 .Op Fl Fl version
  66 .Op Fl Fl help
  67 .Nm ipropd-slave
  68 .Oo Fl c Ar string \*(Ba Xo
  69 .Fl Fl config-file= Ns Ar string
  70 .Xc
  71 .Oc
  72 .Oo Fl r Ar string \*(Ba Xo
  73 .Fl Fl realm= Ns Ar string
  74 .Xc
  75 .Oc
  76 .Oo Fl k Ar kspec \*(Ba Xo
  77 .Fl Fl keytab= Ns Ar kspec
  78 .Xc
  79 .Oc
  80 .Op Fl Fl time-lost= Ns Ar time
  81 .Op Fl Fl detach
  82 .Op Fl Fl version
  83 .Op Fl Fl help
  84 .Ar master
  85 .Sh DESCRIPTION
  86 .Nm ipropd-master
  87 is used to propagate changes to a Heimdal Kerberos database from the
  88 master Kerberos server on which it runs to slave Kerberos servers
  89 running
  90 .Nm ipropd-slave .
  91 .Pp
  92 The slaves are specified by the contents of the
  93 .Pa slaves
  94 file in the KDC's database directory, e.g.\&
  95 .Pa /var/heimdal/slaves .
  96 This has principals one per-line of the form
  97 .Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM
  98 where
  99 .Ar slave
 100 is the hostname of the slave server in the given
 101 .Ar REALM ,
 102 e.g.\&
 103 .Dl iprop/kerberos-1.example.com@EXAMPLE.COM
 104 On a slave, the argument
 105 .Fa master
 106 specifies the hostname of the master server from which to receive updates.
 107 .Pp
 108 In contrast to
 109 .Xr hprop 8 ,
 110 which sends the whole database to the slaves regularly,
 111 .Nm
 112 normally sends only the changes as they happen on the master.
 113 The master keeps track of all the changes by assigning a version
 114 number to every change to the database.
 115 The slaves know which was the latest version they saw, and in this
 116 way it can be determined if they are in sync or not.
 117 A log of all the changes is kept on the master.
 118 When a slave is at an older version than the oldest one in the log,
 119 the whole database has to be sent.
 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 Supported options for
 139 .Nm ipropd-master :
 140 .Bl -tag -width Ds
 141 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 142 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 143 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 144 keytab to get authentication from
 145 .It Fl d Ar file , Fl Fl database= Ns Ar file
 146 Database (default per KDC)
 147 .It Fl Fl slave-stats-file= Ns Ar file
 148 file for slave status information
 149 .It Fl Fl time-missing= Ns Ar time
 150 time before slave is polled for presence (default 2 min)
 151 .It Fl Fl time-gone= Ns Ar time
 152 time of inactivity after which a slave is considered gone (default 5 min)
 153 .It Fl Fl detach
 154 detach from console
 155 .It Fl Fl version
 156 .It Fl Fl help
 157 .El
 158 .Pp
 159 Supported options for
 160 .Nm ipropd-slave :
 161 .Bl -tag -width Ds
 162 .It Fl c Ar string , Fl Fl config-file= Ns Ar string
 163 .It Fl r Ar string , Fl Fl realm= Ns Ar string
 164 .It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec
 165 keytab to get authentication from
 166 .It Fl Fl time-lost= Ns Ar time
 167 time before server is considered lost (default 5 min)
 168 .It Fl Fl detach
 169 detach from console
 170 .It Fl Fl version
 171 .It Fl Fl help
 172 .El
 173 Time arguments for the relevant options above may be specified in forms
 174 like 5 min, 300 s, or simply a number of seconds.
 175 .Sh FILES
 176 .Pa slaves ,
 177 .Pa slave-stats
 178 in the database directory.
 179 .Sh SEE ALSO
 180 .Xr krb5.conf 5 ,
 181 .Xr hprop 8 ,
 182 .Xr hpropd 8 ,
 183 .Xr iprop-log 8 ,
 184 .Xr kdc 8