1The GNU C library contains an NSS module for the Hesiod name service.
2Hesiod is a general name service for a variety of applications and is
3based on the Berkeley Internet Name Daemon (BIND).
4
5Introduction
6============
7
8The Hesiod NSS module implements access to all relevant standard
9Hesiod types, which means that Hesiod can be used for the `group',
10`passwd' and `services' databases.  There is however a restriction.
11In the same way that it is impossible to use `gethostent()' to iterate
12over all the data provided by DNS, it is not possible to scan the
13entire Hesiod database by means of `getgrent()', `getpwent()' and
14`getservent()'.  Besides, Hesiod only provides support for looking up
15services by name and not for looking them up by port.  In essence this
16means that the Hesiod name service is only consulted as a result of
17one of the following function calls:
18
19  * getgrname(), getgrgid()
20  * getpwname(), getpwuid()
21  * getservbyname()
22
23and their reentrant counterparts.
24
25
26Configuring your systems
27========================
28
29Configuring your systems to make use the Hesiod name service requires
30one or more of the following steps, depending on whether you are
31already running Hesiod in your network.
32
33Configuring NSS
34---------------
35
36First you should modify the file `/etc/nsswitch.conf' to tell
37NSS for which database you want to use the Hesiod name service.  If
38you want to use Hesiod for all databases it can handle your
39configuration 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
58For more information on NSS, please refer to the `The GNU C Library
59Reference Manual'.
60
61
62Configuring Hesiod
63------------------
64
65Next, you will have to configure Hesiod.  If you are already running
66Hesiod 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
70will want to create your own.  It should look something like:
71
72  rhs=.your.domain
73  lhs=.ns
74  classes=in,hs
75
76The optional classes settings specifies which DNS classes Hesiod
77should do lookups in.  Possible values are IN (the preferred class)
78and  HS (the deprecated class, still used by some sites).
79You may specify both classes separated by a comma to try one class
80first and then the other if no entry is available in the first
81class.  The default value of the classes variable is `IN,HS'.
82
83The value of rhs can be overridden by the environment variable
84`HES_DOMAIN'.
85
86Configuring your name servers
87-----------------------------
88
89In addition, if you are not already running Hesiod in your network,
90you need to create Hesiod information on your central name servers.
91You need to run `named' from BIND 4.9 or higher on these servers, and
92make 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
97or 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
105Then in the BIND working directory (usually `/var/named') create the
106file `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
126where `libc' is an example of a group, `gnu' an example of an user,
127and `nss' an example of a service.  Note that the format used to
128describe services differs from the format used in `/etc/services'.
129For more information on `named' refer to the `Name Server Operations
130Guide for BIND' that is included in the BIND distribution.
131
132
133Security
134========
135
136Note that the information stored in the Hesiod database in principle
137is publicly available.  Care should be taken with including vulnerable
138information like encrypted passwords in the Hesiod database.  There
139are some ways to improve security by using features provided by
140`named' (see the discussion about `secure zones' in the BIND
141documentation), but one should keep in mind that Hesiod was never
142intended to distribute passwords.  In the origional design
143authenticating users was the job of the Kerberos service.
144
145
146More information
147================
148
149For more information on the Hesiod name service take a look at some of
150the papers in ftp://athena-dist.mit.edu:/pub/ATHENA/usenix and the
151documentation that accompanies the source code for the Hesiod name
152service library in ftp://athena-dist.mit.edu:/pub/ATHENA/hesiod.
153
154There is a mailing list at MIT for Hesiod users, hesiod@mit.edu.  To
155get yourself on or off the list, send mail to hesiod-request@mit.edu.
156