named(1m) - osol9

1named(1M)               System Administration Commands               named(1M)
2
3
4

NAME

6       named, in.named - Internet domain name server
7

SYNOPSIS

9       named [-fgsv] [-c config-file] [-d debug-level] [-m flag] [-n #cpus]
10            [-p port] [-t directory] [-u user] [-x cache-file] [-4 | -6]
11
12

DESCRIPTION

14       The  named  utility  is  a Domain Name System (DNS) server, part of the
15       BIND 9 distribution from ISC. For more information on the DNS, see RFCs
16       1033, 1034, and 1035.
17
18
19       When  invoked  without arguments, named reads the default configuration
20       file /etc/named.conf, reads any initial data, and listens for queries.
21
22
23       in.named is a link to named.
24

OPTIONS

26       The following options are supported:
27
28       -4
29
30           Use only IPv4 transport. By default, both IPv4 and IPv6  transports
31           can be used. Options -4 and -6 are mutually exclusive.
32
33
34       -6
35
36           Use  only IPv6 transport. By default, both IPv4 and IPv6 transports
37           can be used. Options -4 and -6 are mutually exclusive.
38
39
40       -c config-file
41
42           Use config-file as the configuration file instead  of  the  default
43           /etc/named.conf.  To  ensure  that reloading the configuration file
44           continues to work after the server has changed its  working  direc‐
45           tory  due  to  to  a possible directory option in the configuration
46           file, config-file should be an absolute pathname.
47
48
49       -d debug-level
50
51           Set the daemon's debug level to debug-level. Debugging traces  from
52           named become more verbose as the debug level increases.
53
54
55       -f
56
57           Run the server in the foreground (that is, do not daemonize).
58
59
60       -g
61
62           Run the server in the foreground and force all logging to stderr.
63
64
65       -m flag
66
67           Turn  on  memory usage debugging flags. Possible flags are "usage",
68           "trace", and "record". These correspond  to  the  ISC_MEM_DEBUGXXXX
69           flags.
70
71
72       -n #cpus
73
74           Create  #cpus worker threads to take advantage of multiple CPUs. If
75           not specified, named will try  to  determine  the  number  of  CPUs
76           present and create one thread per CPU. If it is unable to determine
77           the number of CPUs, a single worker thread will be created.
78
79
80       -p port
81
82           Listen for queries on port port. If not specified, the  default  is
83           port 53.
84
85
86       -s
87
88           Write memory usage statistics to stdout on exit.
89
90           This option is mainly of interest to BIND 9 developers and might be
91           removed or changed in a future release.
92
93
94       -t directory
95
96           Change the root directory using chroot(2) to directory  after  pro‐
97           cessing the command line arguments, but before reading the configu‐
98           ration file.
99
100           This option should be used in conjunction with the  -u  option,  as
101           chrooting  a  process  running  as root doesn't enhance security on
102           most systems; the way chroot() is defined  allows  a  process  with
103           root privileges to escape a chroot jail.
104
105
106       -u user
107
108           Set the real user ID using setuid(2) to user after completing priv‐
109           ileged operations, such as creating sockets that listen  on  privi‐
110           leged ports.
111
112           On  Linux, named uses the kernel's capability mechanism to drop all
113           root privileges except the ability to use bind(3SOCKET) to bind  to
114           a  privileged  port and set process resource limits. Unfortunately,
115           this means that the -u option works only when named is run on  ker‐
116           nel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since previous
117           kernels did not allow privileges to be retained after setuid().
118
119
120       -v
121
122           Report the version number and exit.
123
124
125       -x cache-file
126
127           Load data from cache-file into the cache of the default view.
128
129           This option must not be used. It is of  interest  only  to  BIND  9
130           developers and might be removed or changed in a future release.
131
132

EXTENDED DESCRIPTION

134       This section describes additional attributes of named.
135
136   SMF Properties
137       When starting named from the service management facility, smf(5), named
138       configuration is read from the service  configuration  repository.  Use
139       svcprop(1) to list the properties and svccfg(1M) to make changes.
140
141
142       The  following  application  configuration  properties are available to
143       administrators:
144
145       options/server
146
147           Specifies the server executable to be used instead of  the  default
148           server, /usr/sbin/named.
149
150
151       options/configuration_file
152
153           Specifies the configuration file to be used instead of the default,
154           /etc/named.conf. A directory option might be specified in the  con‐
155           figuration  file.  To  ensure that reloading the configuration file
156           continues to work in such a situation, configuration_file should be
157           specified as an absolute pathname. This pathname should not include
158           the chroot_dir pathname. This property is the equivalent of the  -c
159           option.
160
161
162       options/ip_interfaces
163
164           Specifies  over  which IP transport, IPv4 or IPv6, BIND will trans‐
165           mit. Possible values are IPv4 or IPv6. Any  other  setting  assumes
166           all,  the  default. This property is the equivalent of command line
167           option -4 or -6
168
169
170       options/listen_on_port
171
172           Specifies the default UDP and TCP port to be used for listening  to
173           DNS  requests.  This property is the equivalent of the command line
174           option -p port.
175
176
177       options/debug_level
178
179           Specifies the default debug level. The default is 0, which means no
180           debugging. The higher the number the more verbose debug information
181           becomes. Equivalent of the command line option -d debug_level.
182
183
184       options/threads
185
186           Specifies the number of CPU worker threads to create.  The  default
187           of  0  causes named to try and determine the number of CPUs present
188           and create one thread per CPU. Equivalent of command line option -n
189           #cpus.
190
191
192       options/chroot_dir
193
194           Specifies the directory to be used as the root directory after pro‐
195           cessing SMF properties and the command line  arguments  but  before
196           reading  the  configuration  file.  Use  this property when using a
197           chroot(2) environment. Synonymous to command line option  -t  path‐
198           name.
199
200           When  using  chroot(2),  named  is  unable  to  disable itself when
201           receiving rndc(1M) stop or halt commands. Instead, you must use the
202           svcadm(1M) disable command.
203
204
205
206       In  the  event of a configuration error originating in one of the above
207       SMF application options, named displays a message providing information
208       about  the  error  and the parameters that need correcting. The process
209       then exits with exit code SMF_EXIT_ERR_CONFIG.
210
211
212       At startup, in the event of an error other than a configuration  error,
213       named  exits  with  exit code SMF_EXIT_ERR_FATAL. Both of this code and
214       SMF_EXIT_ERR_CONFIG cause the start method, smf_method(5), to place the
215       service  in  the  maintenance  state,  which  can  be observed with the
216       svcs(1) command svcs -x.
217
218
219       In addition to the properties listed above, the following property  can
220       be used to invoke named as a user other than root:
221
222       start/user
223
224           Specifies  the  identity  of  the  user that is invoking named. See
225           smf_method(5)  and  chroot(2).  Note  that  the  user   must   have
226           solaris.smf.manage.bind  authorization. Without this role the named
227           will be unable to manage its SMF FMRI and named will  automatically
228           be restarted by the SMF after an rndc(1M) stop or halt command. See
229           EXAMPLES for a sequence of commands that  establishes  the  correct
230           authorization.
231
232
233   SIGNALS
234       In  routine  operation, signals should not be used to control the name‐
235       server; rndc(1M) should be used instead.
236
237       SIGHUP
238
239           Force a reload of the server.
240
241
242       SIGINT, SIGTERM
243
244           Shut down the server.
245
246
247
248       The result of sending any other signals to the server is undefined.
249
250   Configuration
251       The named configuration file is too complex to describe in detail here.
252       A  list of configuration options is provided in the named.conf man page
253       shipped with the BIND 9 distribution. A complete  description  is  pro‐
254       vided in the BIND 9 Administrator Reference Manual. See SEE ALSO.
255

EXAMPLES

257       Example 1 Configuring named to Transmit Only over IPv4 Networks
258
259
260       The  following  command  sequence  configures  named  such that it will
261       transmit only over IPv4 networks.
262
263
264         # svccfg -s svc:network/dns/server:default setprop \
265         > options/ip_interfaces=IPv4
266         # svcadm refresh svc:network/dns/server:default
267         #
268
269
270
271       Example 2 Listing Current Configuration File and Setting an Alternative
272       File
273
274
275       The  following  sequence of commands lists the current named configura‐
276       tion file and sets an alternative file.
277
278
279         # svcprop -p options/configuration_file dns/server:default
280         /etc/named.conf
281         # svccfg -s dns/server:default setprop \
282         > options/configuration_file=/var/named/named.conf
283         # svcadm refresh dns/server:default
284         # svcprop -p options/configuration_file dns/server:default
285         /var/named/named.conf
286
287
288
289       Example 3 Establishing Appropriate Authorization for named
290
291
292       To have named start  with  the  solaris.smf.manage.bind  authorization,
293       perform the steps shown below.
294
295
296
297       Add the user dnsadmin to the solaris.smf.manage.bind role:
298
299
300         # usermod -A solaris.smf.manage.bind dnsadmin
301         Observe effect of command:
302         # tail -1 /etc/user_attr
303         dnsadmin::::type=normal;auths=solaris.smf.manage.bind
304
305
306
307
308       Modify the service properties:
309
310
311         # svccfg
312         svc:> select svc:/network/dns/server:default
313         svc:/network/dns/server:default> setprop start/user = dnsadmin
314         svc:/network/dns/server:default> setprop start/group = dnsadmin
315         svc:/network/dns/server:default> exit
316         # svcadm refresh svc:/network/dns/server:default
317         # svcadm restart svc:/network/dns/server:default
318
319
320
321
322       Because  only  root  has  write access to create the default process-ID
323       file,  /var/run/named.pid, named must be configured to use an  alterna‐
324       tive  path  for  the user dnsadmin. Here is an example of how to accom‐
325       plish this:
326
327
328         # mkdir /var/named/tmp
329         # chown dnsadmin /var/named/tmp
330
331
332
333
334       Shown below is what you must add to  named.conf  to  make  use  of  the
335       directory created above.
336
337
338         # head /etc/named.conf
339         options {
340         directory "/var/named";
341         pid-file "/var/named/tmp/named.pid";
342         };
343
344
345

FILES

347       /etc/named.conf
348
349           default configuration file
350
351
352       /var/run/named.pid
353
354           default process-ID file
355
356

ATTRIBUTES

358       See attributes(5) for descriptions of the following attributes:
359
360
361
362
363       ┌─────────────────────────────┬─────────────────────────────┐
364       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
365       ├─────────────────────────────┼─────────────────────────────┤
366       │Availability                 │SUNWbind                     │
367       ├─────────────────────────────┼─────────────────────────────┤
368       │Interface Stability          │Standard                     │
369       └─────────────────────────────┴─────────────────────────────┘
370

BUGS

387       By default, named attempts to contact remote  name  servers  by  either
388       their  IPv4  or IPv6 address, even though the host system does not have
389       either IPv4 or IPv6 connectivity (that  is,  a  configured  and  active
390       interface).  To  address this issue, either provide the missing connec‐
391       tivity or use the relevant -4 or -6 command  line  option.  When  using
392       svccfg(1M),  set  application  property options/ip_interfaces to either
393       IPv4 or IPv6.
394
395
396
397SunOS 5.11                        6 Mar 2009                         named(1M)