1@node Setting up a realm, Things in search for a better place, Building and Installing, Top 2@chapter Setting up a realm 3 4A 5@cindex realm 6realm is an administrative domain. The name of a Kerberos realm is 7usually the Internet domain name in uppercase. Call your realm the same 8as your Internet domain name if you do not have strong reasons for not 9doing so. It will make life easier for you and everyone else. 10 11@section Configuration file 12 13To setup a realm you will first have to create a configuration file: 14@file{/etc/krb5.conf}. The @file{krb5.conf} file can contain many 15configuration options, some of which are described here. 16 17There is a sample @file{krb5.conf} supplied with the distribution. 18 19The configuration file is a hierarchical structure consisting of 20sections, each containing a list of bindings (either variable 21assignments or subsections). A section starts with 22@samp{[section-name]}. A binding consists of a left hand side, an equal 23(@samp{=}) and a right hand side (the left hand side tag must be 24separated from the equal with some whitespace.) Subsections has a 25@samp{@{} as the first non-whitespace character after the equal. All 26other bindings are treated as variable assignments. The value of a 27variable extends to the end of the line. 28 29@example 30[section1] 31 a-subsection = @{ 32 var = value1 33 other-var = value with @{@} 34 sub-sub-section = @{ 35 var = 123 36 @} 37 @} 38 var = some other value 39[section2] 40 var = yet another value 41@end example 42 43In this manual, names of sections and bindings will be given as strings 44separated by slashes (@samp{/}). The @samp{other-var} variable will thus 45be @samp{section1/a-subsection/other-var}. 46 47For in-depth information about the contents of the config file, refer to 48the @file{krb5.conf} manual page. Some of the more important sections 49are briefly described here. 50 51The @samp{libdefaults} section contains a list of library configuration 52parameters, such as the default realm and the timeout for kdc 53responses. The @samp{realms} section contains information about specific 54realms, such as where they hide their KDC. This section serves the same 55purpose as the Kerberos 4 @file{krb.conf} file, but can contain more 56information. Finally the @samp{domain_realm} section contains a list of 57mappings from domains to realms, equivalent to the Kerberos 4 58@file{krb.realms} file. 59 60To continue with the realm setup, you will have to create a config file, 61with contents similar to the following. 62 63@example 64[libdefaults] 65 default_realm = MY.REALM 66[realms] 67 MY.REALM = @{ 68 kdc = my.kdc 69 @} 70[domain_realm] 71 .my.domain = MY.REALM 72 73@end example 74 75If you use a realm name equal to your domain name, you can omit the 76@samp{libdefaults}, and @samp{domain_realm}, sections. If you have a 77SRV-record for your realm, or your kerberos server has CNAME called 78@samp{kerberos.my.realm}, you can omit the @samp{realms} section too. 79 80@section Creating the database 81 82The database library will look for the database in @file{/var/heimdal}, 83so you should probably create that directory. 84 85The keys of all the principals are stored in the database. If you 86choose to, these can be encrypted with a master key. You do not have to 87remember this key (or password), but just to enter it once and it will 88be stored in a file (@file{/var/heimdal/m-key}). If you want to have a 89master key, run @samp{kstash} to create this master key: 90 91@example 92# kstash 93Master key: 94Verifying password - Master key: 95@end example 96 97To initialise the database use the @code{kadmin} program, with the 98@samp{-l} option (to enable local database mode). First issue a 99@kbd{init MY.REALM} command. This will create the database and insert 100default principals for that realm. You can have more than one realm in 101one database, so @samp{init} does not destroy any old database. 102 103Before creating the database, @samp{init} will ask you some questions 104about max ticket lifetimes. 105 106After creating the database you should probably add yourself to it. You 107do this with the @samp{add} command. It takes as argument the name of a 108principal. The principal should contain a realm, so if you haven't setup 109a default realm, you will need to explicitly include the realm. 110 111@example 112# kadmin -l 113kadmin> init MY.REALM 114Realm max ticket life [unlimited]: 115Realm max renewable ticket life [unlimited]: 116kadmin> add me 117Max ticket life [unlimited]: 118Max renewable life [unlimited]: 119Attributes []: 120Password: 121Verifying password - Password: 122@end example 123 124Now start the KDC and try getting a ticket. 125 126@example 127# kdc & 128# kinit me 129me@@MY.REALMS's Password: 130# klist 131Credentials cache: /tmp/krb5cc_0 132 Principal: me@@MY.REALM 133 134 Issued Expires Principal 135Aug 25 07:25:55 Aug 25 17:25:55 krbtgt/MY.REALM@@MY.REALM 136@end example 137 138If you are curious you can use the @samp{dump} command to list all the 139entries in the database. It should look something similar to the 140following example (note that the entries here are truncated for 141typographical reasons): 142 143@smallexample 144kadmin> dump 145me@@MY.REALM 1:0:1:0b01d3cb7c293b57:-:0:7:8aec316b9d1629e3baf8 ... 146kadmin/admin@@MY.REALM 1:0:1:e5c8a2675b37a443:-:0:7:cb913ebf85 ... 147krbtgt/MY.REALM@@MY.REALM 1:0:1:52b53b61c875ce16:-:0:7:c8943be ... 148kadmin/changepw@@MY.REALM 1:0:1:f48c8af2b340e9fb:-:0:7:e3e6088 ... 149@end smallexample 150 151@section keytabs 152 153To extract a service ticket from the database and put it in a keytab you 154need to first create the principal in the database with @samp{ank} 155(using the @kbd{--random} flag to get a random password) and then 156extract it with @samp{ext_keytab}. 157 158@example 159kadmin> add --random host/my.host.name 160Max ticket life [unlimited]: 161Max renewable life [unlimited]: 162Attributes []: 163kadmin> ext host/my.host.name 164# ktutil list 165Version Type Principal 166 1 des-cbc-md5 host/my.host.name@@MY.REALM 167 1 des-cbc-md4 host/my.host.name@@MY.REALM 168 1 des-cbc-crc host/my.host.name@@MY.REALM 169 1 des3-cbc-sha1 host/my.host.name@@MY.REALM 170@end example 171 172@section Remote administration 173 174The administration server, @samp{kadmind}, is started by @samp{inetd} 175and you should add a line similar to the one below to your 176@file{/etc/inetd.conf}. 177 178@example 179kerberos-adm stream tcp nowait root /usr/heimdal/libexec/kadmind kadmind 180@end example 181 182You might need to add @samp{kerberos-adm} to your @file{/etc/services} 183as 749/tcp. 184 185Access to the admin server is controlled by an acl-file, (default 186@file{/var/heimdal/kadmind.acl}.) The lines in the access file, has the 187following syntax: 188@smallexample 189principal [priv1,priv2,...] 190@end smallexample 191 192The privileges you can assign to a principal are: @samp{add}, 193@samp{change-password} (or @samp{cpw} for short), @samp{delete}, 194@samp{get}, @samp{list}, and @samp{modify}, or the special privilege 195@samp{all}. All of these roughly corresponds to the different commands 196in @samp{kadmin}. 197 198@section Password changing 199 200To allow users to change their passwords, you should run @samp{kpasswdd}. 201It is not run from @samp{inetd}. 202 203You might need to add @samp{kpasswd} to your @file{/etc/services} as 204464/udp. 205 206@subsection Password quality assurance 207 208It is important that users have good passwords, both to make it harder 209to guess them and to avoid off-line attacks (pre-authentication provides 210some defense against off-line attacks). To ensure that the users choose 211good passwords, you can enable password quality controls in 212@samp{kpasswdd}. The controls themselves are done in a shared library 213that is used by @samp{kpasswdd}. To configure in these controls, add 214lines similar to the following to your @file{/etc/krb5.conf}: 215 216@example 217[password_quality] 218 check_library = @var{library} 219 check_function = @var{function} 220@end example 221 222The function @var{function} in the shared library @var{library} will be 223called for proposed new passwords. The function should be declared as: 224 225@example 226const char * 227function(krb5_context context, krb5_principal principal, krb5_data *pwd); 228@end example 229 230The function should verify that @var{pwd} is a good password for 231@var{principal} and if so return @code{NULL}. If it is deemed to be of 232low quality, it should return a string explaining why that password 233should not be used. 234 235Code for a password quality checking function that uses the cracklib 236library can be found in @file{kpasswd/sample_password_check.c} in the 237source code distribution. It requires the cracklib library built with 238the patch available at 239@url{ftp://ftp.pdc.kth.se/pub/krb/src/cracklib.patch}. 240 241If no password quality checking function is configured, it is only 242verified that it is at least six characters of length. 243 244@section Testing clients and servers 245 246Now you should be able to run all the clients and servers. Refer to the 247appropriate man pages for information on how to use them. 248