hesiod/README.hesiod

   1 The GNU C library contains an NSS module for the Hesiod name service.
   2 Hesiod is a general name service for a variety of applications and is
   3 based on the Berkeley Internet Name Daemon (BIND).
   4
   5 Introduction
   6 ============
   7
   8 The Hesiod NSS module implements access to all relevant standard
   9 Hesiod types, which means that Hesiod can be used for the `group',
  10 `passwd' and `services' databases.  There is however a restriction.
  11 In the same way that it is impossible to use `gethostent()' to iterate
  12 over all the data provided by DNS, it is not possible to scan the
  13 entire Hesiod database by means of `getgrent()', `getpwent()' and
  14 `getservent()'.  Besides, Hesiod only provides support for looking up
  15 services by name and not for looking them up by port.  In essence this
  16 means that the Hesiod name service is only consulted as a result of
  17 one of the following function calls:
  18
  19   * getgrname(), getgrgid()
  20   * getpwname(), getpwuid()
  21   * getservbyname()
  22
  23 and their reentrant counterparts.
  24
  25
  26 Configuring your systems
  27 ========================
  28
  29 Configuring your systems to make use the Hesiod name service requires
  30 one or more of the following steps, depending on whether you are
  31 already running Hesiod in your network.
  32
  33 Configuring NSS
  34 ---------------
  35
  36 First you should modify the file `/etc/nsswitch.conf' to tell
  37 NSS for which database you want to use the Hesiod name service.  If
  38 you want to use Hesiod for all databases it can handle your
  39 configuration file could look like this:
  40
  41   # /etc/nsswitch.conf
  42   #
  43   # Example configuration of GNU Name Service Switch functionality.
  44   #
  45
  46   passwd:         db files hesiod
  47   group:          db files hesiod
  48   shadow:         db files
  49
  50   hosts:          files dns
  51   networks:       files dns
  52
  53   protocols:      db files
  54   services:       db files hesiod
  55   ethers:         db files
  56   rpc:            db files
  57
  58 For more information on NSS, please refer to the `The GNU C Library
  59 Reference Manual'.
  60
  61
  62 Configuring Hesiod
  63 ------------------
  64
  65 Next, you will have to configure Hesiod.  If you are already running
  66 Hesiod in your network, you probably already have a file named
  67 `hesiod.conf' on your machines (probably as `/etc/hesiod.conf' or
  68 `/usr/local/etc/hesiod.conf').  The Hesiod NSS module looks for
  69 `/etc/hesiod.conf' by default.  If there is no configuration file you
  70 will want to create your own.  It should look something like:
  71
  72   rhs=.your.domain
  73   lhs=.ns
  74   classes=in,hs
  75
  76 The optional classes settings specifies which DNS classes Hesiod
  77 should do lookups in.  Possible values are IN (the preferred class)
  78 and  HS (the deprecated class, still used by some sites).
  79 You may specify both classes separated by a comma to try one class
  80 first and then the other if no entry is available in the first
  81 class.  The default value of the classes variable is `IN,HS'.
  82
  83 The value of rhs can be overridden by the environment variable
  84 `HES_DOMAIN'.
  85
  86 Configuring your name servers
  87 -----------------------------
  88
  89 In addition, if you are not already running Hesiod in your network,
  90 you need to create Hesiod information on your central name servers.
  91 You need to run `named' from BIND 4.9 or higher on these servers, and
  92 make them authoritative for the domain `ns.your.domain' with a line in
  93 `/etc/named.boot' reading something like:
  94
  95   primary         ns.your.domain          named.hesiod
  96
  97 or if you are using the new BIND 8.1 or higher add something to
  98 `/etc/named.conf' like:
  99
 100   zone "ns.your.domain" {
 101           type master;
 102           file "named.hesiod";
 103   };
 104
 105 Then in the BIND working directory (usually `/var/named') create the
 106 file `named.hesiod' containing data that looks something like:
 107
 108   ; SOA and NS records.
 109   @       IN      SOA     server1.your.domain admin-address.your.domain (
 110                   40000           ; serial - database version number
 111                   1800            ; refresh - sec servers
 112                   300             ; retry - for refresh
 113                   3600000         ; expire - unrefreshed data
 114                   7200 )          ; min
 115                   NS      server1.your.domain
 116                   NS      server2.your.domain
 117
 118   ; Actual Hesiod data.
 119   libc.group      TXT     "libc:*:123:gnu,gnat"
 120   123.gid         CNAME   libc.group
 121   gnu.passwd      TXT     "gnu:*:4567:123:GNU:/home/gnu:/bin/bash"
 122   456.uid         CNAME   mark.passwd
 123   nss.service     TXT     "nss tcp 789 switch sw "
 124   nss.service     TXT     "nss udp 789 switch sw"
 125
 126 where `libc' is an example of a group, `gnu' an example of an user,
 127 and `nss' an example of a service.  Note that the format used to
 128 describe services differs from the format used in `/etc/services'.
 129 For more information on `named' refer to the `Name Server Operations
 130 Guide for BIND' that is included in the BIND distribution.
 131
 132
 133 Security
 134 ========
 135
 136 Note that the information stored in the Hesiod database in principle
 137 is publicly available.  Care should be taken with including vulnerable
 138 information like encrypted passwords in the Hesiod database.  There
 139 are some ways to improve security by using features provided by
 140 `named' (see the discussion about `secure zones' in the BIND
 141 documentation), but one should keep in mind that Hesiod was never
 142 intended to distribute passwords.  In the original design
 143 authenticating users was the job of the Kerberos service.
 144
 145
 146 More information
 147 ================
 148
 149 For more information on the Hesiod name service take a look at some of
 150 the papers in ftp://athena-dist.mit.edu:/pub/ATHENA/usenix and the
 151 documentation that accompanies the source code for the Hesiod name
 152 service library in ftp://athena-dist.mit.edu:/pub/ATHENA/hesiod.
 153
 154 There is a mailing list at MIT for Hesiod users, hesiod@mit.edu.  To
 155 get yourself on or off the list, send mail to hesiod-request@mit.edu.