| 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 |
| 68 |
.Fl Fl config-file= Ns Ar string |
| 69 |
.Xc |
| 70 |
.Oc |
| 71 |
.Oo Fl r Ar string \*(Ba Xo |
| 72 |
.Fl Fl realm= Ns Ar string |
| 73 |
.Xc |
| 74 |
.Oc |
| 75 |
.Oo Fl k Ar kspec \*(Ba Xo |
| 76 |
.Fl Fl keytab= Ns Ar kspec |
| 77 |
.Xc |
| 78 |
.Oc |
| 79 |
.Op Fl Fl time-lost= Ns Ar time |
| 80 |
.Op Fl Fl detach |
| 81 |
.Op Fl Fl version |
| 82 |
.Op Fl Fl help |
| 83 |
.Ar master |
| 84 |
.Sh DESCRIPTION |
| 85 |
.Nm ipropd-master |
| 86 |
is used to propagate changes to a Heimdal Kerberos database from the |
| 87 |
master Kerberos server on which it runs to slave Kerberos servers |
| 88 |
running |
| 89 |
.Nm ipropd-slave . |
| 90 |
.Pp |
| 91 |
The slaves are specified by the contents of the |
| 92 |
.Pa slaves |
| 93 |
file in the KDC's database directory, e.g.\& |
| 94 |
.Pa /var/heimdal/slaves . |
| 95 |
This has principals one per-line of the form |
| 96 |
.Dl iprop/ Ns Ar slave Ns @ Ns Ar REALM |
| 97 |
where |
| 98 |
.Ar slave |
| 99 |
is the hostname of the slave server in the given |
| 100 |
.Ar REALM , |
| 101 |
e.g.\& |
| 102 |
.Dl iprop/[email protected] |
| 103 |
On a slave, the argument |
| 104 |
.Fa master |
| 105 |
specifies the hostname of the master server from which to receive updates. |
| 106 |
.Pp |
| 107 |
In contrast to |
| 108 |
.Xr hprop 8 , |
| 109 |
which sends the whole database to the slaves regularly, |
| 110 |
.Nm |
| 111 |
normally sends only the changes as they happen on the master. |
| 112 |
The master keeps track of all the changes by assigning a version |
| 113 |
number to every transaction to the database. |
| 114 |
The slaves know which was the latest version they saw, and in this |
| 115 |
way it can be determined if they are in sync or not. |
| 116 |
A log of all the transactions is kept on the master. |
| 117 |
When a slave is at an older version than the oldest one in the log, |
| 118 |
the whole database has to be sent. |
| 119 |
.Pp |
| 120 |
The log of transactions is also used to implement a two-phase commit |
| 121 |
(with roll-forward for recovery) method of updating the HDB. |
| 122 |
Transactions are first recorded in the log, then in the HDB, then |
| 123 |
the log is updated to mark the transaction as committed. |
| 124 |
.Pp |
| 125 |
The changes are propagated over a secure channel (on port 2121 by |
| 126 |
default). |
| 127 |
This should normally be defined as |
| 128 |
.Dq iprop/tcp |
| 129 |
in |
| 130 |
.Pa /etc/services |
| 131 |
or another source of the services database. |
| 132 |
The master and slaves |
| 133 |
must each have access to a keytab with keys for the |
| 134 |
.Nm iprop |
| 135 |
service principal on the local host. |
| 136 |
.Pp |
| 137 |
There is a keep-alive feature logged in the master's |
| 138 |
.Pa slave-stats |
| 139 |
file (e.g.\& |
| 140 |
.Pa /var/heimdal/slave-stats ) . |
| 141 |
.Pp |
| 142 |
Supported options for |
| 143 |
.Nm ipropd-master : |
| 144 |
.Bl -tag -width Ds |
| 145 |
.It Fl c Ar string , Fl Fl config-file= Ns Ar string |
| 146 |
.It Fl r Ar string , Fl Fl realm= Ns Ar string |
| 147 |
.It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec |
| 148 |
keytab to get authentication from |
| 149 |
.It Fl d Ar file , Fl Fl database= Ns Ar file |
| 150 |
Database (default per KDC) |
| 151 |
.It Fl Fl slave-stats-file= Ns Ar file |
| 152 |
file for slave status information |
| 153 |
.It Fl Fl time-missing= Ns Ar time |
| 154 |
time before slave is polled for presence (default 2 min) |
| 155 |
.It Fl Fl time-gone= Ns Ar time |
| 156 |
time of inactivity after which a slave is considered gone (default 5 min) |
| 157 |
.It Fl Fl detach |
| 158 |
detach from console |
| 159 |
.It Fl Fl version |
| 160 |
.It Fl Fl help |
| 161 |
.El |
| 162 |
.Pp |
| 163 |
Supported options for |
| 164 |
.Nm ipropd-slave : |
| 165 |
.Bl -tag -width Ds |
| 166 |
.It Fl c Ar string , Fl Fl config-file= Ns Ar string |
| 167 |
.It Fl r Ar string , Fl Fl realm= Ns Ar string |
| 168 |
.It Fl k Ar kspec , Fl Fl keytab= Ns Ar kspec |
| 169 |
keytab to get authentication from |
| 170 |
.It Fl Fl time-lost= Ns Ar time |
| 171 |
time before server is considered lost (default 5 min) |
| 172 |
.It Fl Fl detach |
| 173 |
detach from console |
| 174 |
.It Fl Fl version |
| 175 |
.It Fl Fl help |
| 176 |
.El |
| 177 |
Time arguments for the relevant options above may be specified in forms |
| 178 |
like 5 min, 300 s, or simply a number of seconds. |
| 179 |
.Sh FILES |
| 180 |
.Pa slaves , |
| 181 |
.Pa slave-stats |
| 182 |
in the database directory. |
| 183 |
.Pa ipropd-master.pid , |
| 184 |
.Pa ipropd-slave.pid |
| 185 |
in the database directory, or in the directory named by the |
| 186 |
.Ev HEIM_PIDFILE_DIR |
| 187 |
environment variable. |
| 188 |
.Sh SEE ALSO |
| 189 |
.Xr krb5.conf 5 , |
| 190 |
.Xr hprop 8 , |
| 191 |
.Xr hpropd 8 , |
| 192 |
.Xr iprop-log 8 , |
| 193 |
.Xr kdc 8 . |