1@c $Id: setup.texi,v 1.21 2001/01/29 04:39:46 assar Exp $ 2 3@node Setting up a realm, Things in search for a better place, Building and Installing, Top 4 5@chapter Setting up a realm 6 7@menu 8* Configuration file:: 9* Creating the database:: 10* keytabs:: 11* Remote administration:: 12* Password changing:: 13* Testing clients and servers:: 14* Slave Servers:: 15* Incremental propagation:: 16* Salting:: 17@end menu 18 19A 20@cindex realm 21realm is an administrative domain. The name of a Kerberos realm is 22usually the Internet domain name in uppercase. Call your realm the same 23as your Internet domain name if you do not have strong reasons for not 24doing so. It will make life easier for you and everyone else. 25 26@node Configuration file, Creating the database, Setting up a realm, Setting up a realm 27@section Configuration file 28 29To setup a realm you will first have to create a configuration file: 30@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many 31configuration options, some of which are described here. 32 33There is a sample @file{krb5.conf} supplied with the distribution. 34 35The configuration file is a hierarchical structure consisting of 36sections, each containing a list of bindings (either variable 37assignments or subsections). A section starts with 38@samp{[section-name]}. A binding consists of a left hand side, an equal 39(@samp{=}) and a right hand side (the left hand side tag must be 40separated from the equal with some whitespace.) Subsections has a 41@samp{@{} as the first non-whitespace character after the equal. All 42other bindings are treated as variable assignments. The value of a 43variable extends to the end of the line. 44 45@example 46[section1] 47 a-subsection = @{ 48 var = value1 49 other-var = value with @{@} 50 sub-sub-section = @{ 51 var = 123 52 @} 53 @} 54 var = some other value 55[section2] 56 var = yet another value 57@end example 58 59In this manual, names of sections and bindings will be given as strings 60separated by slashes (@samp{/}). The @samp{other-var} variable will thus 61be @samp{section1/a-subsection/other-var}. 62 63For in-depth information about the contents of the config file, refer to 64the @file{krb5.conf} manual page. Some of the more important sections 65are briefly described here. 66 67The @samp{libdefaults} section contains a list of library configuration 68parameters, such as the default realm and the timeout for kdc 69responses. The @samp{realms} section contains information about specific 70realms, such as where they hide their KDC. This section serves the same 71purpose as the Kerberos 4 @file{krb.conf} file, but can contain more 72information. Finally the @samp{domain_realm} section contains a list of 73mappings from domains to realms, equivalent to the Kerberos 4 74@file{krb.realms} file. 75 76To continue with the realm setup, you will have to create a config file, 77with contents similar to the following. 78 79@example 80[libdefaults] 81 default_realm = MY.REALM 82[realms] 83 MY.REALM = @{ 84 kdc = my.kdc 85 @} 86[domain_realm] 87 .my.domain = MY.REALM 88 89@end example 90 91If you use a realm name equal to your domain name, you can omit the 92@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a 93SRV-record for your realm, or your kerberos server has CNAME called 94@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. 95 96@node Creating the database, keytabs, Configuration file, Setting up a realm 97@section Creating the database 98 99The database library will look for the database in @file{/var/heimdal}, 100so you should probably create that directory. 101 102The keys of all the principals are stored in the database. If you 103choose to, these can be encrypted with a master key. You do not have to 104remember this key (or password), but just to enter it once and it will 105be stored in a file (@file{/var/heimdal/m-key}). If you want to have a 106master key, run @samp{kstash} to create this master key: 107 108@example 109# kstash 110Master key: 111Verifying password - Master key: 112@end example 113 114To initialise the database use the @code{kadmin} program, with the 115@samp{-l} option (to enable local database mode). First issue a 116@kbd{init MY.REALM} command. This will create the database and insert 117default principals for that realm. You can have more than one realm in 118one database, so @samp{init} does not destroy any old database. 119 120Before creating the database, @samp{init} will ask you some questions 121about max ticket lifetimes. 122 123After creating the database you should probably add yourself to it. You 124do this with the @samp{add} command. It takes as argument the name of a 125principal. The principal should contain a realm, so if you haven't setup 126a default realm, you will need to explicitly include the realm. 127 128@example 129# kadmin -l 130kadmin> init MY.REALM 131Realm max ticket life [unlimited]: 132Realm max renewable ticket life [unlimited]: 133kadmin> add me 134Max ticket life [unlimited]: 135Max renewable life [unlimited]: 136Attributes []: 137Password: 138Verifying password - Password: 139@end example 140 141Now start the KDC and try getting a ticket. 142 143@example 144# kdc & 145# kinit me 146me@@MY.REALMS's Password: 147# klist 148Credentials cache: /tmp/krb5cc_0 149 Principal: me@@MY.REALM 150 151 Issued Expires Principal 152Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM 153@end example 154 155If you are curious you can use the @samp{dump} command to list all the 156entries in the database. It should look something similar to the 157following example (note that the entries here are truncated for 158typographical reasons): 159 160@smallexample 161kadmin> dump 162me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... 163kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... 164krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 165kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... 166@end smallexample 167 168@node keytabs, Remote administration, Creating the database, Setting up a realm 169@section keytabs 170 171To extract a service ticket from the database and put it in a keytab you 172need to first create the principal in the database with @samp{ank} 173(using the @kbd{--random-key} flag to get a random key) and then 174extract it with @samp{ext_keytab}. 175 176@example 177kadmin> add --random-key host/my.host.name 178Max ticket life [unlimited]: 179Max renewable life [unlimited]: 180Attributes []: 181kadmin> ext host/my.host.name 182# ktutil list 183Version Type Principal 184 1 des-cbc-md5 host/my.host.name@@MY.REALM 185 1 des-cbc-md4 host/my.host.name@@MY.REALM 186 1 des-cbc-crc host/my.host.name@@MY.REALM 187 1 des3-cbc-sha1 host/my.host.name@@MY.REALM 188@end example 189 190@node Remote administration, Password changing, keytabs, Setting up a realm 191@section Remote administration 192 193The administration server, @samp{kadmind}, can be started by 194@samp{inetd} (which isn't recommended) or run as a normal daemon. If you 195want to start it from @samp{inetd} you should add a line similar to the 196one below to your @file{/etc/inetd.conf}. 197 198@example 199kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind 200@end example 201 202You might need to add @samp{kerberos-adm} to your @file{/etc/services} 203as 749/tcp. 204 205Access to the admin server is controlled by an acl-file, (default 206@file{/var/heimdal/kadmind.acl}.) The lines in the access file, has the 207following syntax: 208@smallexample 209principal [priv1,priv2,...] [glob-pattern] 210@end smallexample 211 212The privileges you can assign to a principal are: @samp{add}, 213@samp{change-password} (or @samp{cpw} for short), @samp{delete}, 214@samp{get}, @samp{list}, and @samp{modify}, or the special privilege 215@samp{all}. All of these roughly corresponds to the different commands 216in @samp{kadmin}. 217 218If a @var{glob-pattern} is given on a line, it restricts the right for 219the principal to only apply for the subjects that match the pattern. 220The patters are of the same type as those used in shell globbing, see 221@url{none,,fnmatch(3)}. 222 223In the example below @samp{lha/admin} can change every principal in the 224database. @samp{jimmy/admin} can only modify principals that belong to 225the realm @samp{E.KTH.SE}. @samp{mille/admin} is working at the 226helpdesk, so he should only be able to change the passwords for single 227component principals (ordinary users). He will not be able to change any 228@samp{/admin} principal. 229 230@example 231lha/admin@@E.KTH.SE all 232jimmy/admin@@E.KTH.SE all *@@E.KTH.SE 233jimmy/admin@@E.KTH.SE all */*@@E.KTH.SE 234mille/admin@@E.KTH.SE change-password *@@E.KTH.SE 235@end example 236 237@node Password changing, Testing clients and servers, Remote administration, Setting up a realm 238@section Password changing 239 240To allow users to change their passwords, you should run @samp{kpasswdd}. 241It is not run from @samp{inetd}. 242 243You might need to add @samp{kpasswd} to your @file{/etc/services} as 244464/udp. 245 246@subsection Password quality assurance 247 248It is important that users have good passwords, both to make it harder 249to guess them and to avoid off-line attacks (pre-authentication provides 250some defense against off-line attacks). To ensure that the users choose 251good passwords, you can enable password quality controls in 252@samp{kpasswdd}. The controls themselves are done in a shared library 253that is used by @samp{kpasswdd}. To configure in these controls, add 254lines similar to the following to your @file{/etc/krb5.conf}: 255 256@example 257[password_quality] 258 check_library = @var{library} 259 check_function = @var{function} 260@end example 261 262The function @var{function} in the shared library @var{library} will be 263called for proposed new passwords. The function should be declared as: 264 265@example 266const char * 267function(krb5_context context, krb5_principal principal, krb5_data *pwd); 268@end example 269 270The function should verify that @var{pwd} is a good password for 271@var{principal} and if so return @code{NULL}. If it is deemed to be of 272low quality, it should return a string explaining why that password 273should not be used. 274 275Code for a password quality checking function that uses the cracklib 276library can be found in @file{kpasswd/sample_password_check.c} in the 277source code distribution. It requires the cracklib library built with 278the patch available at 279@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. 280 281If no password quality checking function is configured, it is only 282verified that it is at least six characters of length. 283 284@node Testing clients and servers, Slave Servers, Password changing, Setting up a realm 285@section Testing clients and servers 286 287Now you should be able to run all the clients and servers. Refer to the 288appropriate man pages for information on how to use them. 289 290@node Slave Servers, Incremental propagation, Testing clients and servers, Setting up a realm 291@section Slave servers, Incremental propagation, Testing clients and servers, Setting up a realm 292 293It is desirable to have at least one backup (slave) server in case the 294master server fails. It is possible to have any number of such slave 295servers but more than three usually doesn't buy much more redundancy. 296 297All Kerberos servers for a realm shall have the same database so that 298they present the same service to all the users. The 299@pindex hprop 300@code{hprop} program, running on the master, will propagate the database 301to the slaves, running 302@pindex hpropd 303@code{hpropd} processes. 304 305Every slave needs a keytab with a principal, 306@samp{hprop/@var{hostname}}. Add that with the 307@pindex ktutil 308@code{ktutil} command and start 309@pindex hpropd 310@code{propd}, as follows: 311 312@example 313slave# ktutil get -p foo/admin host/`hostname` 314slave# hpropd 315@end example 316 317The master will use the principal @samp{kadmin/hprop} to authenticate to 318the slaves. This principal should be added when running @kbd{kadmin -l 319init} but if you do not have it in your database for whatever reason, 320please add it with @kbd{kadmin -l add}. 321 322Then run 323@pindex hprop 324@code{hprop} on the master: 325 326@example 327master# hprop slave 328@end example 329 330This was just an on-hands example to make sure that everything was 331working properly. Doing it manually is of course the wrong way and to 332automate this you will want to start 333@pindex hpropd 334@code{hpropd} from @code{inetd} on the slave(s) and regularly run 335@pindex hprop 336@code{hprop} on the master to regularly propagate the database. 337Starting the propagation once an hour from @code{cron} is probably a 338good idea. 339 340@node Incremental propagation, Salting , Slave Servers, Setting up a realm 341@section Incremental propagation 342 343There is also a newer and still somewhat experimental mechanism for 344doing incremental propagation in Heimdal. Instead of sending the whole 345database regularly, it sends the changes as they happen on the master to 346the slaves. The master keeps track of all the changes by assigned a 347version number to every change to the database. The slaves know which 348was the latest version they saw and in this way it can be determined if 349they are in sync or not. A log of all the changes is kept on the master 350and when a slave is at an older versioner than the oldest one in the 351log, the whole database has to be sent. 352 353Protocol-wise, all the slaves connects to the master and as a greeting 354tell it the latest version that they have (@samp{IHAVE} message). The 355master then responds by sending all the changes between that version and 356the current version at the master (a series of @samp{FORYOU} messages) 357or the whole database in a @samp{TELLYOUEVERYTHING} message. 358 359@subsection Configuring incremental propagation 360 361The program that runs on the master is @code{ipropd-master} and all 362clients run @code{ipropd-slave}. 363 364Create the file @file{/var/heimdal/slaves} on the master containing all 365the slaves that the database should be propagated to. Each line contains 366the full name of the principal (for example 367@samp{iprop/hemligare.foo.se@@FOO.SE}). 368 369You should already have @samp{iprop/tcp} defined as 2121, in your 370@file{/etc/services}. Otherwise, or if you need to use a different port 371for some peculiar reason, you can use the @kbd{--port} option. This is 372useful when you have multiple realms to distribute from one server. 373 374Then you need to create these principals that you added in the 375configuration file. Create one @samp{iprop/hostname} for the master and 376for every slave. 377 378 379@example 380master# /usr/heimdal/sbin/ktutil get iprop/`hostname` 381@end example 382 383The next step is to start the @code{ipropd-master} process on the master 384server. The @code{ipropd-master} listens on the UNIX-socket 385@file{/var/heimdal/signal} to know when changes have been made to the 386database so they can be propagated to the slaves. There is also a 387safety feature of testing the version number regularly (every 30 388seconds) to see if it has been modified by some means that do not raise 389this signal. Then, start @code{ipropd-slave} on all the slaves: 390 391@example 392master# /usr/heimdal/libexec/ipropd-master & 393slave# /usr/heimdal/libexec/ipropd-slave master & 394@end example 395 396@node Salting, , Incremental propagation, Setting up a realm 397@section Salting 398@cindex Salting 399 400Salting is used to make it harder to precalculate all possible 401keys. Using a salt increases the search space to make it almost 402impossible to precalculate all keys. In salting you just append the salt 403to the password, or somehow merge the password with the salt. 404 405In Kerberos 5 the salting is determined by the encryption-type, except 406in case of @code{des}. In @code{des} there is the kerberos 4 salting 407(none at all) or the afs-salting (using the cell (realm in 408afs-lingo)). @code{[kadmin]default_keys} in @file{krb5.conf} controls 409what salting to use, 410 411The syntax of @code{[kadmin]default_keys} is 412@samp{[etype:]salt-type[:salt-string]}. @samp{etype} is the encryption 413type (des, des3, arcfour), @code{salt-type} is the type of salt (pw-salt 414or afs3-salt), and the salt-string is the string that will be used as 415salt (remember that if the salt is appened/prepended, the empty salt "" 416is the same thing as no salt at all). 417 418Common types of salting includes 419 420@itemize 421@item @code{v4} (or @code{des:pw-salt:}) 422 423The Kerberos 4 salting is using no salt att all. Reson there is colon 424that the end is that 425 426@item @code{v5} (or @code{pw-salt}) 427 428@code{pw-salt} means all regular encryption-types that is regular 429 430@item @code{afs3-salt} 431 432@code{afs3-salt} is the salting that is used with Transarc kaserver. Its 433the cell appended to the password. 434 435@end itemize 436