Update.
[kopensolaris-gnu/glibc.git] / 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 expects this
69 file to be found in the sysconfdir (`/usr/local/etc/hesiod.conf' by
70 default, see the installation notes on how to change this) or in the
71 location specified by the environment variable `HESIOD_CONFIG'.  If
72 there is no configuration file you will want to create your own.  It
73 should look something like:
74
75   rhs=.your.domain
76   lhs=.ns
77
78 The value of rhs can be overridden by the environment variable
79 HES_DOMAIN.
80
81 Configuring your name servers
82 -----------------------------
83
84 In addition, if you are not already running Hesiod in your network,
85 you need to create Hesiod information on your central name servers.
86 You need to run `named' from BIND 4.9 or higher on these servers, and
87 make them authoritative for the domain `ns.your.domain' with a line in
88 `/etc/named.boot' reading something like:
89
90   primary         ns.your.domain          named.hesiod
91
92 or if you are using the new BIND 8.1 or higher add something to
93 `/etc/named.conf' like:
94
95   zone "ns.your.domain" {
96           type master;
97           file "named.hesiod";
98   };
99
100 Then in the BIND working directory (usually `/var/named') create the
101 file `named.hesiod' containing data that looks something like:
102
103   ; SOA and NS records.
104   @       IN      SOA     server1.your.domain admin-address.your.domain (
105                   40000           ; serial - database version number
106                   1800            ; refresh - sec servers
107                   300             ; retry - for refresh
108                   3600000         ; expire - unrefreshed data
109                   7200 )          ; min
110                   NS      server1.your.domain
111                   NS      server2.your.domain
112
113   ; Actual Hesiod data.
114   libc.group      TXT     "libc:*:123:gnu,gnat"
115   123.gid         CNAME   libc.group
116   gnu.passwd      TXT     "gnu:*:4567:123:GNU:/home/gnu:/bin/bash"
117   456.uid         CNAME   mark.passwd
118   nss.service     TXT     "nss;tcp;789;switch sw "
119   nss.service     TXT     "nss;udp;789;switch sw"
120
121 where `libc' is an example of a group, `gnu' an example of an user,
122 and `nss' an example of a service.  Note that the format used to
123 describe services differs from the format used in `/etc/services'.
124 For more information on `named' refer to the `Name Server Operations
125 Guide for BIND' that is included in the BIND distribution.
126
127
128 Security
129 ========
130
131 Note that the information stored in the Hesiod database in principle
132 is publicly available.  Care should be taken with including vulnerable
133 information like encrypted passwords in the Hesiod database.  There
134 are some ways to improve security by using features provided by
135 `named' (see the discussion about `secure zones' in the BIND
136 documentation), but one should keep in mind that Hesiod was never
137 intended to distribute passwords.  In the origional design
138 authenticating users was the job of the Kerberos service.
139
140
141 More information
142 ================
143
144 For more information on the Hesiod name service take a look at some of
145 the papers in ftp://athena-dist.mit.edu:/pub/ATHENA/usenix and the
146 documentation that accompanies the source code for the Hesiod name
147 service library in ftp://athena-dist.mit.edu:/pub/ATHENA/hesiod.
148
149 There is a mailing list at MIT for Hesiod users, hesiod@mit.edu.  To
150 get yourself on or off the list, send mail to hesiod-request@mit.edu.