sys/man/6/ndb

   1 .TH NDB 6
   2 .SH NAME
   3 ndb \- Network database
   4 .SH DESCRIPTION
   5 .PP
   6 The network database consists of files
   7 describing machines known to the local
   8 installation and machines known publicly.
   9 The files comprise multi-line tuples made up of
  10 attribute/value pairs of the form
  11 .IB attr = value
  12 or sometimes just
  13 .IR attr .
  14 Each line starting without white space starts a new tuple.
  15 Lines starting with
  16 .B #
  17 are comments.
  18 .PP
  19 The file
  20 .B /lib/ndb/local
  21 is the root of the database.
  22 Other files are included in the
  23 database if a tuple with an
  24 attribute-value pair of attribute
  25 .B database
  26 and no value exists in
  27 .BR /lib/ndb/local \r.
  28 Within the
  29 .B database
  30 tuple,
  31 each pair with attribute
  32 .B file
  33 identifies a file to be included in the database.  The files are searched
  34 in the order they appear.
  35 For example:
  36 .IP
  37 .EX
  38 database=
  39         file=/lib/ndb/common
  40         file=/lib/ndb/local
  41         file=/lib/ndb/global
  42 .EE
  43 .PP
  44 declares the database to be composed of the three files
  45 .BR /lib/ndb/common ,
  46 .BR /lib/ndb/local ,
  47 and
  48 .BR /lib/ndb/global .
  49 By default,
  50 .B /lib/ndb/local
  51 is searched before the others.
  52 However,
  53 .B /lib/ndb/local
  54 may be included in the
  55 .B database
  56 to redefine its ordering.
  57 .PP
  58 Within tuples, pairs on the same line bind tighter than
  59 pairs on different lines.
  60 .PP
  61 Programs search the database directly using the routines in
  62 .IR ndb (2)
  63 or indirectly using
  64 .B ndb/cs
  65 and
  66 .B ndb/dns
  67 (see
  68 .IR ndb (8)).
  69 Both
  70 .B ndb/cs
  71 and the routine
  72 .I ndbipinfo
  73 impose structure on the otherwise flat database by using
  74 knowledge specific to the network.
  75 The internet is made up of networks which can be subnetted
  76 multiple times.  A network must have an
  77 .B ipnet
  78 attribute and is uniquely identified by the values of its
  79 .B ip
  80 and
  81 .B ipmask
  82 attributes.  If the
  83 .B ipmask
  84 is missing, the relevant Class A, B or C one is used.
  85 .LP
  86 A search for an attribute associated with a network or host starts
  87 at the lowest level, the entry for the host or network itself,
  88 and works its way up, bit by bit, looking at entries for nets/subnets
  89 that include the network or host.  The search ends when the attribute
  90 is found.
  91 For example, consider the following entries:
  92 .IP
  93 .EX
  94 ipnet=murray-hill ip=135.104.0.0 ipmask=255.255.0.0
  95         dns=135.104.10.1
  96         ntp=ntp.cs.bell-labs.com
  97 ipnet=plan9 ip=135.104.9.0 ipmask=255.255.255.0
  98         ntp=oncore.cs.bell-labs.com
  99         smtp=smtp1.cs.bell-labs.com
 100 ip=135.104.9.6 sys=anna dom=anna.cs.bell-labs.com
 101         smtp=smtp2.cs.bell-labs.com
 102 .EE
 103 .LP
 104 Here
 105 .B anna
 106 is on the subnet
 107 .B plan9
 108 which is in turn on the class B net
 109 .BR murray-hill .
 110 Assume that we're searching for
 111 .BR anna 's
 112 .B NTP
 113 and
 114 .B SMTP
 115 servers.
 116 The search starts by looking for an entry with
 117 .BR sys=anna .
 118 We find the anna entry.  Since it has an
 119 .B smtp=smtp2.cs.bell-labs.com
 120 pair,
 121 we're done looking for that attribute.
 122 To fulfill the NTP request, we continue by looking for networks
 123 that include anna's IP address.
 124 We lop off the right most one bit from anna's address and
 125 look for an
 126 .B ipnet=
 127 entry with
 128 .BR ip=135.104.9.4 .
 129 Not finding one, we drop another bit and look for an
 130 .B ipnet=
 131 entry with
 132 .BR ip=135.104.9.0 .
 133 There is
 134 such an entry and it has the pair,
 135 .BR ntp=oncore.cs.bell-labs.com ,
 136 ending our search.
 137 .PP
 138 .I Ndb/cs
 139 can be made to perform such network aware
 140 searches by using metanames in the dialstring.
 141 A metaname is a
 142 .I $
 143 followed by an attribute name.
 144 .I Ndb/cs
 145 looks up the attribute relative to the system it is running
 146 on.  Thus, with the above example, if a program called
 147 .IP
 148 .EX
 149         dial("tcp!$smtp!smtp", 0, 0, 0);
 150 .EE
 151 .LP
 152 the dial would connect to the SMTP port of
 153 .BR smtp2.cs.bell-labs.com .
 154 .PP
 155 A number of attributes are meaningful to programs and thus
 156 reserved.
 157 They are:
 158 .TF rootserver
 159 .TP
 160 .B sys
 161 system name (a short name)
 162 .TP
 163 .B dom
 164 Internet fully-qualified domain name
 165 .TP
 166 .B ip
 167 Internet address,
 168 v4 or v6.
 169 .TP
 170 .B ipv6
 171 IPv6 Internet address.
 172 For DNS, an
 173 .L AAAA
 174 record.
 175 .TP
 176 .B ipnet
 177 Internet network name
 178 .TP
 179 .B ipmask
 180 Internet network mask
 181 .TP
 182 .B ipgw
 183 Internet gateway (ip address)
 184 .TP
 185 .B ether
 186 Ethernet address
 187 (must be lower-case hex)
 188 .TP
 189 .B vendor
 190 Specific vendor attribute for dhcp and bootp
 191 .TP
 192 .B bootf
 193 file to download for initial bootstrap;
 194 .B /386/9bootpxe
 195 to boot a PC via PXE.
 196 .TP
 197 .B tftp
 198 an TFTP server to use for PXE bootstrap
 199 .TP
 200 .B fs
 201 Plan 9 file server to be used
 202 .TP
 203 .B auth
 204 Plan 9 authentication server to be used
 205 .TP
 206 .B authdom
 207 Plan 9 authentication domain.
 208 To specify an authentication server for a particular domain,
 209 add a tuple containing both
 210 .B auth
 211 and
 212 .B authdom
 213 attributes and values.
 214 .TP
 215 .B rootpath
 216 the NFS root for unix machines
 217 .TP
 218 .B rootserver
 219 the NFS server used with rootpath
 220 .TP
 221 .B dnsdomain
 222 a domain name that
 223 .I ndb/dns
 224 adds onto any unrooted names when doing a search.
 225 There may be multiple
 226 .B dnsdomain
 227 pairs.
 228 .TP
 229 .B dns
 230 a DNS server to use (for DNS and DHCP)
 231 .TP
 232 .B ntp
 233 an NTP server to use (for DHCP)
 234 .TP
 235 .B smtp
 236 an SMTP server to use (for DHCP)
 237 .TP
 238 .B time
 239 a time server to use (for DHCP)
 240 .TP
 241 .B wins
 242 a Windows name server (for DHCP)
 243 .TP
 244 .B mx
 245 mail exchanger (for DNS and DHCP);
 246 also
 247 .BR pref .
 248 .TP
 249 .B srv
 250 service location (for DNS);
 251 also
 252 .BR pri ,
 253 .B weight
 254 and
 255 .BR port .
 256 .TP
 257 .B soa
 258 start of area (for DNS)
 259 .TP
 260 .B tcp
 261 a TCP service name
 262 .TP
 263 .B udp
 264 a UDP service name
 265 .TP
 266 .B port
 267 a TCP or UDP port number
 268 .TP
 269 .B restricted
 270 a TCP service that can be called only by ports numbered
 271 less than 1024
 272 .TP
 273 .B proto
 274 a protocol supported by a host.
 275 The pair
 276 .B proto=il
 277 was needed by
 278 .I cs
 279 (see
 280 .IR ndb (8))
 281 in tuples for hosts that supported the IL protocol
 282 .PD
 283 .PP
 284 .I Cs
 285 defers to
 286 .I dns
 287 to translate dotted names to IP addresses,
 288 only consulting the database files if
 289 .I dns
 290 cannot translate the name.
 291 .PP
 292 .I Cs
 293 allows network entries with
 294 .B sys
 295 and
 296 .B dom
 297 attributes but no
 298 .B ip
 299 attribute.
 300 Searches for the system name are resolved
 301 by looking up the domain name with
 302 .IR dns .
 303 .PP
 304 The file
 305 .B /lib/ndb/auth
 306 is used during authentication to decide who has the power to `speak for' other
 307 users; see
 308 .IR authsrv (6).
 309 .SH EXAMPLES
 310 .LP
 311 A tuple for the CPU server, spindle.
 312 .LP
 313 .EX
 314 sys=spindle
 315         dom=spindle.research.bell-labs.com
 316         bootf=/mips/9powerboot
 317         ip=135.104.117.32 ether=080069020677
 318 .EE
 319 .LP
 320 Entries for the network
 321 .B mh-astro-net
 322 and its subnets.
 323 .LP
 324 .EX
 325 ipnet=mh-astro-net ip=135.104.0.0 ipmask=255.255.255.0
 326         ipgw=r70.research.bell-labs.com
 327         fs=bootes.research.bell-labs.com
 328         auth=p9auth.research.bell-labs.com
 329 ipnet=unix-room ip=135.104.117.0
 330         ipgw=135.104.117.1
 331 ipnet=third-floor ip=135.104.51.0
 332         ipgw=135.104.51.1
 333 .EE
 334 .LP
 335 Mappings between TCP service names and port numbers.
 336 .LP
 337 .EX
 338 .ta \w'\fLtcp=sysmonxxxxx'u \w'\fLtcp=sysmonxxxxxport=512xxx'u
 339 tcp=sysmon      port=401
 340 tcp=rexec       port=512        restricted
 341 tcp=9fs port=564
 342 .EE
 343 .SH FILES
 344 .TF /lib/ndb/local
 345 .TP
 346 .B /lib/ndb/local
 347 first database file searched
 348 .SH "SEE ALSO"
 349 .IR con (1),
 350 .IR dial (2),
 351 .IR ndb (2),
 352 .IR booting (8),
 353 .IR dhcpd (8),
 354 .IR ipconfig (8),
 355 .IR ndb (8)