~cyphermox/ubuntu/precise/dnsmasq/dbus : revision 3

1

.TH DNSMASQ 8

2

.SH NAME

3

dnsmasq \- A lightweight DHCP and caching DNS server.

4

.SH SYNOPSIS

5

.B dnsmasq

6

.I [OPTION]...

7

.SH "DESCRIPTION"

8

.BR dnsmasq

9

is a lightweight DNS and DHCP server. It is intended to provide coupled DNS and DHCP service to a

10

LAN.

11

.PP

12

Dnsmasq accepts DNS queries and either answers them from a small, local,

13

cache or forwards them to a real, recursive, DNS server. It loads the

14

contents of /etc/hosts so that local hostnames

15

which do not appear in the global DNS can be resolved and also answers

16

DNS queries for DHCP configured hosts.

17

.PP

18

The dnsmasq DHCP server supports static address assignments, multiple

19

networks, DHCP-relay and RFC3011 subnet specifiers. It automatically

20

sends a sensible default set of DHCP options, and can be configured to

21

send any desired set of DHCP options. It also supports BOOTP.

22

.PP

23

Dnsmasq

24

supports IPv6.

25

.SH OPTIONS

26

Note that in general missing parameters are allowed and switch off

27

functions, for instance "--pid-file=" disables writing a PID file. On

28

BSD, unless the GNU getopt library is linked, the long form of the

29

options does not work on the command line; it is still recognised in

30

the configuration file.

31

.TP

32

.B \-h, --no-hosts

33

Don't read the hostnames in /etc/hosts.

34

.TP

35

.B \-H, --addn-hosts=<file>

36

Additional hosts file. Read the specified file as well as /etc/hosts. If -h is given, read

37

only the specified file. This option may be repeated for more than one

38

additional hosts file.

39

.TP

40

.B \-T, --local-ttl=<time>

41

When replying with information from /etc/hosts or the DHCP leases

42

file dnsmasq by default sets the time-to-live field to zero, meaning

43

that the requestor should not itself cache the information. This is

44

the correct thing to do in almost all situations. This option allows a

45

time-to-live (in seconds) to be given for these replies. This will

46

reduce the load on the server at the expense of clients using stale

47

data under some circumstances.

48

.TP

49

.B \-k, --keep-in-foreground

50

Do not go into the background at startup but otherwise run as

51

normal. This is intended for use when dnsmasq is run under daemontools

52

or launchd.

53

.TP

54

.B \-d, --no-daemon

55

Debug mode: don't fork to the background, don't write a pid file,

56

don't change user id, generate a complete cache dump on receipt on

57

SIGUSR1, log to stderr as well as syslog, don't fork new processes

58

to handle TCP queries.

59

.TP

60

.B \-q, --log-queries

61

Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1.

62

.TP

63

.B \-x, --pid-file=<path>

64

Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid.

65

.TP

66

.B \-u, --user=<username>

67

Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root

68

privileges after startup by changing id to another user. Normally this user is "nobody" but that

69

can be over-ridden with this switch.

70

.TP

71

.B \-g, --group=<groupname>

72

Specify the group which dnsmasq will run

73

as. The defaults to "dip", if available, to facilitate access to

74

/etc/ppp/resolv.conf which is not normally world readable.

75

.TP

76

.B \-v, --version

77

Print the version number.

78

.TP

79

.B \-p, --port=<port>

80

Listen on <port> instead of the standard DNS port (53). Useful mainly for

81

debugging.

82

.TP

83

.B \-P, --edns-packet-max=<size>

84

Specify the largest EDNS.0 UDP packet which is supported by the DNS

85

forwarder. Defaults to 1280, which is the RFC2671-recommended maximum

86

for ethernet.

87

.TP

88

.B \-Q, --query-port=<query_port>

89

Send outbound DNS queries from, and listen for their replies on, the specific UDP port <query_port> instead of using one chosen at runtime. Useful to simplify your

90

firewall rules; without this, your firewall would have to allow connections from outside DNS servers to a range of UDP ports, or dynamically adapt to the

91

port being used by the current dnsmasq instance.

92

.TP

93

.B \-i, --interface=<interface name>

94

Listen only on the specified interface(s). Dnsmasq automatically adds

95

the loopback (local) interface to the list of interfaces to use when

96

the

97

.B \--interface

98

option is used. If no

99

.B \--interface

100

or

101

.B \--listen-address

102

options are given dnsmasq listens on all available interfaces except any

103

given in

104

.B \--except-interface

105

options. If IP alias interfaces (eg "eth1:0") are used with

106

.B --interface

107

or

108

.B --except-interface

109

options, then the

110

.B --bind-interfaces

111

option will be automatically set. This is required for deeply boring

112

sockets-API reasons.

113

.TP

114

.B \-I, --except-interface=<interface name>

115

Do not listen on the specified interface. Note that the order of

116

.B \--listen-address

117

.B --interface

118

and

119

.B --except-interface

120

options does not matter and that

121

.B --except-interface

122

options always override the others.

123

.TP

124

.B \-2, --no-dhcp-interface=<interface name>

125

Do not provide DHCP on the specified interface, but do provide DNS service.

126

.TP

127

.B \-a, --listen-address=<ipaddr>

128

Listen on the given IP address(es). Both

129

.B \--interface

130

and

131

.B \--listen-address

132

options may be given, in which case the set of both interfaces and

133

addresses is used. Note that if no

134

.B \--interface

135

option is given, but

136

.B \--listen-address

137

is, dnsmasq will not automatically listen on the loopback

138

interface. To achieve this, its IP address, 127.0.0.1, must be

139

explicitly given as a

140

.B \--listen-address

141

option.

142

.TP

143

.B \-z, --bind-interfaces

144

On systems which support it, dnsmasq binds the wildcard address,

145

even when it is listening on only some interfaces. It then discards

146

requests that it shouldn't reply to. This has the advantage of

147

working even when interfaces come and go and change address. This

148

option forces dnsmasq to really bind only the interfaces it is

149

listening on. About the only time when this is useful is when

150

running another nameserver (or another instance of dnsmasq) on the

151

same machine or when using IP

152

alias. Specifying interfaces with IP alias automatically turns this

153

option on. Setting this option also enables multiple instances of

154

dnsmasq which provide DHCP service to run in the same machine.

155

.TP

156

.B \-y, --localise-queries

157

Return answers to DNS queries from /etc/hosts which depend on the interface over which the query was

158

received. If a name in /etc/hosts has more than one address associated with

159

it, and at least one of those addresses is on the same subnet as the

160

interface to which the query was sent, then return only the

161

address(es) on that subnet. This allows for a server to have multiple

162

addresses in /etc/hosts corresponding to each of its interfaces, and

163

hosts will get the correct address based on which network they are

164

attached to. Currently this facility is limited to IPv4.

165

.TP

166

.B \-b, --bogus-priv

167

Bogus private reverse lookups. All reverse lookups for private IP ranges (ie 192.168.x.x, etc)

168

which are not found in /etc/hosts or the DHCP leases file are answered

169

with "no such domain" rather than being forwarded upstream.

170

.TP

171

.B \-V, --alias=<old-ip>,<new-ip>[,<mask>]

172

Modify IPv4 addresses returned from upstream nameservers; old-ip is

173

replaced by new-ip. If the optional mask is given then any address

174

which matches the masked old-ip will be re-written. So, for instance

175

.B --alias=1.2.3.0,6.7.8.0,255.255.255.0

176

will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what

177

Cisco PIX routers call "DNS doctoring".

178

.TP

179

.B \-B, --bogus-nxdomain=<ipaddr>

180

Transform replies which contain the IP address given into "No such

181

domain" replies. This is intended to counteract a devious move made by

182

Verisign in September 2003 when they started returning the address of

183

an advertising web page in response to queries for unregistered names,

184

instead of the correct NXDOMAIN response. This option tells dnsmasq to

185

fake the correct response when it sees this behaviour. As at Sept 2003

186

the IP address being returned by Verisign is 64.94.110.11

187

.TP

188

.B \-f, --filterwin2k

189

Later versions of windows make periodic DNS requests which don't get sensible answers from

190

the public DNS and can cause problems by triggering dial-on-demand links. This flag turns on an option

191

to filter such requests. The requests blocked are for records of types SOA and SRV, and type ANY where the

192

requested name has underscores, to catch LDAP requests.

193

.TP

194

.B \-r, --resolv-file=<file>

195

Read the IP addresses of the upstream nameservers from <file>, instead of

196

/etc/resolv.conf. For the format of this file see

197

.BR resolv.conf (5)

198

the only lines relevant to dnsmasq are nameserver ones. Dnsmasq can

199

be told to poll more than one resolv.conf file, the first file name specified

200

overrides the default, subsequent ones add to the list. This is only

201

allowed when polling; the file with the currently latest modification

202

time is the one used.

203

.TP

204

.B \-R, --no-resolv

205

Don't read /etc/resolv.conf. Get upstream servers only from the command

206

line or the dnsmasq configuration file.

207

.TP

208

.B \-1, --enable-dbus

209

Allow dnsmasq configuration to be updated via DBus method calls. The

210

configuration which can be changed is upstream DNS servers (and

211

corresponding domains) and cache clear. Requires that dnsmasq has

212

been built with DBus support.

213

.TP

214

.B \-o, --strict-order

215

By default, dnsmasq will send queries to any of the upstream servers

216

it knows about and tries to favour servers to are known to

217

be up. Setting this flag forces dnsmasq to try each query with each

218

server strictly in the order they appear in /etc/resolv.conf

219

.TP

220

.B \-n, --no-poll

221

Don't poll /etc/resolv.conf for changes.

222

.TP

223

.B \-D, --domain-needed

224

Tells dnsmasq to never forward queries for plain names, without dots

225

or domain parts, to upstream nameservers. If the name is not known

226

from /etc/hosts or DHCP then a "not found" answer is returned.

227

.TP

228

.B \-S, --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source>[#<port>]]]

229

Specify IP address of upstream severs directly. Setting this flag does

230

not suppress reading of /etc/resolv.conf, use -R to do that. If one or

231

more

232

optional domains are given, that server is used only for those domains

233

and they are queried only using the specified server. This is

234

intended for private nameservers: if you have a nameserver on your

235

network which deals with names of the form

236

xxx.internal.thekelleys.org.uk at 192.168.1.1 then giving the flag

237

.B -S /internal.thekelleys.org.uk/192.168.1.1

238

will send all queries for

239

internal machines to that nameserver, everything else will go to the

240

servers in /etc/resolv.conf. An empty domain specification,

241

.B //

242

has the special meaning of "unqualified names only" ie names without any

243

dots in them. A non-standard port may be specified as

244

part of the IP

245

address using a # character.

246

More than one -S flag is allowed, with

247

repeated domain or ipaddr parts as required.

248

249

Also permitted is a -S

250

flag which gives a domain but no IP address; this tells dnsmasq that

251

a domain is local and it may answer queries from /etc/hosts or DHCP

252

but should never forward queries on that domain to any upstream

253

servers.

254

.B local

255

is a synonym for

256

.B server

257

to make configuration files clearer in this case.

258

259

The optional second IP address after the @ character tells

260

dnsmasq how to set the source address of the queries to this

261

nameserver. It should be an address belonging to the machine on which

262

dnsmasq is running otherwise this server line will be logged and then

263

ignored. The query-port flag is ignored for any servers which have a

264

source address specified but the port may be specified directly as

265

part of the source address.

266

.TP

267

.B \-A, --address=/<domain>/[domain/]<ipaddr>

268

Specify an IP address to return for any host in the given domains.

269

Queries in the domains are never forwarded and always replied to

270

with the specified IP address which may be IPv4 or IPv6. To give

271

both IPv4 and IPv6 addresses for a domain, use repeated -A flags.

272

Note that /etc/hosts and DHCP leases override this for individual

273

names. A common use of this is to redirect the entire doubleclick.net

274

domain to some friendly local web server to avoid banner ads. The

275

domain specification works in the same was as for --server, with the

276

additional facility that /#/ matches any domain. Thus

277

--address=/#/1.2.3.4 will always return 1.2.3.4 for any query not

278

answered from /etc/hosts or DHCP and not sent to an upstream

279

nameserver by a more specific --server directive.

280

.TP

281

.B \-m, --mx-host=<mx name>[[,<hostname>],<preference>]

282

Return an MX record named <mx name> pointing to the given hostname (if

283

given), or

284

the host specified in the --mx-target switch

285

or, if that switch is not given, the host on which dnsmasq

286

is running. The default is useful for directing mail from systems on a LAN

287

to a central server. The preference value is optional, and defaults to

288

1 if not given. More than one MX record may be given for a host.

289

.TP

290

.B \-t, --mx-target=<hostname>

291

Specify the default target for the MX record returned by dnsmasq. See

292

--mx-host. If --mx-target is given, but not --mx-host, then dnsmasq

293

returns a MX record containing the MX target for MX queries on the

294

hostname of the machine on which dnsmasq is running.

295

.TP

296

.B \-e, --selfmx

297

Return an MX record pointing to itself for each local

298

machine. Local machines are those in /etc/hosts or with DHCP leases.

299

.TP

300

.B \-L, --localmx

301

Return an MX record pointing to the host given by mx-target (or the

302

machine on which dnsmasq is running) for each

303

local machine. Local machines are those in /etc/hosts or with DHCP

304

leases.

305

.TP

306

.B \-W, --srv-host=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]

307

Return a SRV DNS record. See RFC2782 for details. If not supplied, the

308

domain defaults to that given by

309

.B --domain.

310

The default for the target domain is empty, and the default for port

311

is one and the defaults for

312

weight and priority are zero. Be careful if transposing data from BIND

313

zone files: the port, weight and priority numbers are in a different

314

order. More than one SRV record for a given service/domain is allowed,

315

all that match are returned.

316

.TP

317

.B \-Y, --txt-record=<name>[[,<text>],<text>]

318

Return a TXT DNS record. The value of TXT record is a set of strings,

319

so any number may be included, split by commas.

320

.TP

321

.B \-c, --cache-size=<cachesize>

322

Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching.

323

.TP

324

.B \-N, --no-negcache

325

Disable negative caching. Negative caching allows dnsmasq to remember

326

"no such domain" answers from upstream nameservers and answer

327

identical queries without forwarding them again. This flag disables

328

negative caching.

329

.TP

330

.B \-F, --dhcp-range=[[net:]network-id,]<start-addr>,<end-addr>[[,<netmask>],<broadcast>][,<default lease time>]

331

Enable the DHCP server. Addresses will be given out from the range

332

<start-addr> to <end-addr> and from statically defined addresses given

333

in

334

.B dhcp-host

335

options. If the lease time is given, then leases

336

will be given for that length of time. The lease time is in seconds,

337

or minutes (eg 45m) or hours (eg 1h) or the literal "infinite". This

338

option may be repeated, with different addresses, to enable DHCP

339

service to more than one network. For directly connected networks (ie,

340

networks on which the machine running dnsmasq has an interface) the

341

netmask is optional. It is, however, required for networks which

342

receive DHCP service via a relay agent. The broadcast address is

343

always optional. On some broken systems, dnsmasq can listen on only

344

one interface when using DHCP, and the name of that interface must be

345

given using the

346

.B interface

347

option. This limitation currently affects OpenBSD. It is always

348

allowed to have more than one dhcp-range in a single subnet. The optional

349

network-id is a alphanumeric label which marks this network so that

350

dhcp options may be specified on a per-network basis.

351

When it is prefixed with 'net:' then its meaning changes from setting

352

a tag to matching it.

353

The end address may be replaced by the keyword

354

.B static

355

which tells dnsmasq to enable DHCP for the network specified, but not

356

to dynamically allocate IP addresses. Only hosts which have static

357

addresses given via

358

.B dhcp-host

359

or from /etc/ethers will be served.

360

.TP

361

.B \-G, --dhcp-host=[[<hwaddr>]|[id:[<client_id>][*]]][net:<netid>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]

362

Specify per host parameters for the DHCP server. This allows a machine

363

with a particular hardware address to be always allocated the same

364

hostname, IP address and lease time. A hostname specified like this

365

overrides any supplied by the DHCP client on the machine. It is also

366

allowable to ommit the hardware address and include the hostname, in

367

which case the IP address and lease times will apply to any machine

368

claiming that name. For example

369

.B --dhcp-host=00:20:e0:3b:13:af,wap,infinite

370

tells dnsmasq to give

371

the machine with ethernet address 00:20:e0:3b:13:af the name wap, and

372

an infinite DHCP lease.

373

.B --dhcp-host=lap,192.168.0.199

374

tells

375

dnsmasq to always allocate the machine lap the IP address

376

192.168.0.199. Addresses allocated like this are not constrained to be

377

in the range given by the --dhcp-range option, but they must be on the

378

network being served by the DHCP server. It is allowed to use client identifiers rather than

379

hardware addresses to identify hosts by prefixing with 'id:'. Thus:

380

.B --dhcp-host=id:01:02:03:04,.....

381

refers to the host with client identifier 01:02:03:04. It is also

382

allowed to specify the client ID as text, like this:

383

.B --dhcp-host=id:clientidastext,.....

384

The special option id:* means "ignore any client-id

385

and use MAC addresses only." This is useful when a client presents a client-id sometimes

386

but not others.

387

If a name appears in /etc/hosts, the associated address can be

388

allocated to a DHCP lease, but only if a

389

.B --dhcp-host

390

option specifying the name also exists. The special keyword "ignore"

391

tells dnsmasq to never offer a DHCP lease to a machine. The machine

392

can be specified by hardware address, client ID or hostname, for

393

instance

394

.B --dhcp-host=00:20:e0:3b:13:af,ignore

395

This is

396

useful when there is another DHCP server on the network which should

397

be used by some machines. The net:<network-id> sets the network-id tag

398

whenever this dhcp-host directive is in use.

399

This can be used to selectively send DHCP options just

400

for this host.

401

Ethernet addresses (but not client-ids) may have

402

wildcard bytes, so for example

403

.B --dhcp-host=00:20:e0:3b:13:*,ignore

404

will cause dnsmasq to ignore a range of ethernet addresses. Note that

405

the "*" will need to be escaped or quoted on a command line, but not

406

in the configuration file.

407

.TP

408

.B \-Z, --read-ethers

409

Read /etc/ethers for information about hosts for the DHCP server. The

410

format of /etc/ethers is a hardware address, followed by either a

411

hostname or dotted-quad IP address. When read by dnsmasq these lines

412

have exactly the same effect as

413

.B --dhcp-host

414

options containing the same information.

415

.TP

416

.B \-O, --dhcp-option=[<network-id>,[<network-id>,]][vendor:<vendor-class>]<opt>,[<value>[,<value>]]

417

Specify different or extra options to DHCP clients. By default,

418

dnsmasq sends some standard options to DHCP clients, the netmask and

419

broadcast address are set to the same as the host running dnsmasq, and

420

the DNS server and default route are set to the address of the machine

421

running dnsmasq. If the domain name option has been set, that is sent.

422

This option allows these defaults to be overridden,

423

or other options specified. The <opt> is the number of the option, as

424

specified in RFC2132. For example, to set the default route option to

425

192.168.4.4, do

426

.B --dhcp-option=3,192.168.4.4

427

and to set the time-server address to 192.168.0.4, do

428

.B --dhcp-option=42,192.168.0.4

429

The special address 0.0.0.0 is taken to mean "the address of the

430

machine running dnsmasq". Data types allowed are comma separated

431

dotted-quad IP addresses, a decimal number, colon-separated hex digits

432

and a text string. If the optional network-ids are given then

433

this option is only sent when all the network-ids are matched.

434

435

Be careful: no checking is done that the correct type of data for the

436

option number is sent, it is quite possible to

437

persuade dnsmasq to generate illegal DHCP packets with injudicious use

438

of this flag. When the value is a decimal number, dnsmasq must determine how

439

large the data item is. It does this by examining the option number and/or the

440

value, but can be overridden by appending a single letter flag as follows:

441

b = one byte, s = two bytes, i = four bytes. This is mainly useful with

442

encapsulated vendor class options (see below) where dnsmasq cannot

443

determine data size from the option number. Option data which

444

consists solely of periods and digits will be interpreted by dnsmasq

445

as an IP address, and inserted into an option as such. To force a

446

literal string, use quotes. For instance when using option 66 to send

447

a literal IP address as TFTP server name, it is necessary to do

448

.B --dhcp-option=66,"1.2.3.4"

449

450

Encapsulated Vendor-class options may also be specified using

451

--dhcp-option: for instance

452

.B --dhcp-option=vendor:PXEClient,1,0.0.0.0

453

sends the vendor class "PXEClient" and the encapsulated vendor class-specific option "mftp-address=0.0.0.0" Only one vendor class is allowed for any

454

host, but multiple options are allowed, provided they all have

455

the same vendor class. The address 0.0.0.0 is not treated specially in

456

encapsulated vendor class options.

457

.TP

458

.B \-U, --dhcp-vendorclass=<network-id>,<vendor-class>

459

Map from a vendor-class string to a network id. Most DHCP clients provide a

460

"vendor class" which represents, in some sense, the type of host. This option

461

maps vendor classes to network ids, so that DHCP options may be selectively delivered

462

to different classes of hosts. For example

463

.B dhcp-vendorclass=printers,Hewlett-Packard JetDirect

464

will allow options to be set only for HP printers like so:

465

.B --dhcp-option=printers,3,192.168.4.4

466

The vendor-class string is

467

substring matched against the vendor-class supplied by the client, to

468

allow fuzzy matching.

469

.TP

470

.B \-j, --dhcp-userclass=<network-id>,<user-class>

471

Map from a user-class string to a network id (with substring

472

matching, like vendor classes). Most DHCP clients provide a

473

"user class" which is configurable. This option

474

maps user classes to network ids, so that DHCP options may be selectively delivered

475

to different classes of hosts. It is possible, for instance to use

476

this to set a different printer server for hosts in the class

477

"accounts" than for hosts in the class "engineering".

478

.TP

479

.B \ -J, --dhcp-ignore=<network-id>[,<network-id>]

480

When all the given network-ids match the set of network-ids derived

481

from the net, host, vendor and user classes, ignore the host and do

482

not allocate it a DHCP lease.

483

.TP

484

.B \-M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server address>]]

485

Set BOOTP options to be returned by the DHCP server. These are needed

486

for machines which network boot, and tell the machine where to collect

487

its initial configuration. If the optional network-id(s) are given,

488

they must match for this configuration to be sent. Note that

489

network-ids are prefixed by "net:" to distinguish them.

490

.TP

491

.B \-X, --dhcp-lease-max=<number>

492

Limits dnsmasq to the specified maximum number of DHCP leases. The

493

default is 150. This limit is to prevent DoS attacks from hosts which

494

create thousands of leases and use lots of memory in the dnsmasq

495

process.

496

.TP

497

.B \-K, --dhcp-authoritative

498

Should be set when dnsmasq is definately the only DHCP server on a network.

499

It changes the behaviour from strict RFC compliance so that DHCP requests on

500

unknown leases from unknown hosts are not ignored. This allows new hosts

501

to get a lease without a tedious timeout under all circumstances.

502

.TP

503

.B \-3, --bootp-dynamic

504

Enable dynamic allocation of IP addresses to BOOTP clients. Use this

505

with care, since each address allocated to a BOOTP client is leased

506

forever, and therefore becomes permanently unavailable for re-use by

507

other hosts.

508

.TP

509

.B \-l, --dhcp-leasefile=<path>

510

Use the specified file to store DHCP lease information. If this option

511

is given but no dhcp-range option is given then dnsmasq version 1

512

behaviour is activated. The file given is assumed to be an ISC dhcpd

513

lease file and parsed for leases which are then added to the DNS

514

system if they have a hostname. This functionality may have been

515

excluded from dnsmasq at compile time, in which case an error will occur.

516

.TP

517

.B \-s, --domain=<domain>

518

Specifies the domain for the DHCP server. This has two effects;

519

firstly it causes the DHCP server to return the domain to any hosts

520

which request it, and secondly it sets the domain which it is legal

521

for DHCP-configured hosts to claim. The intention is to constrain hostnames so that an untrusted host on the LAN cannot advertise it's name via dhcp as e.g. "microsoft.com" and capture traffic not meant for it. If no domain suffix is specified, then any DHCP hostname with a domain part (ie with a period) will be disallowed and logged. If suffix is specified, then hostnames with a domain part are allowed, provided the domain part matches the suffix. In addition, when a suffix is set then hostnames without a domain part have the suffix added as an optional domain part. Eg on my network I can set

522

.B --domain=thekelleys.org.uk

523

and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from

524

.B dnsmasq

525

both as "laptop" and "laptop.thekelleys.org.uk". If the domain is

526

given as "#" then the domain is read from the first "search" directive

527

in /etc/resolv.conf (or equivalent).

528

.TP

529

.B \-E, --expand-hosts

530

Add the domain to simple names (without a period) in /etc/hosts

531

in the same way as for DHCP-derived names.

532

.TP

533

.B \-C, --conf-file=<file>

534

Specify a different configuration file. The conf-file option is also allowed in

535

configuration files, to include multiple configuration files. Only one

536

level of nesting is allowed.

537

.SH CONFIG FILE

538

At startup, dnsmasq reads

539

.I /etc/dnsmasq.conf,

540

if it exists. (On

541

FreeBSD, the file is

542

.I /usr/local/etc/dnsmasq.conf

543

) (but see the

544

.B \-C

545

option.) The format of this

546

file consists of one option per line, exactly as the long options detailed

547

in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For

548

options which may only be specified once, the configuration file overrides

549

the command line. Quoting is allowed in a config file:

550

between " quotes the special meanings of ,:. and # are removed and the

551

following escapes are allowed: \\\\ \\" \\t \\a \\b \\r and \\n. The later

552

corresponding to tab, bell, backspace, return and newline.

553

.SH NOTES

554

When it receives a SIGHUP,

555

.B dnsmasq

556

clears its cache and then re-loads

557

.I /etc/hosts.

558

If

559

.B

560

--no-poll

561

is set SIGHUP also re-reads

562

.I /etc/resolv.conf.

563

SIGHUP

564

does NOT re-read the configuration file.

565

.PP

566

When it receives a SIGUSR1,

567

.B dnsmasq

568

writes cache statistics to the system log. It writes the cache size,

569

the number of names which have had to removed from the cache before

570

they expired in order to make room for new names and the total number

571

of names that have been inserted into the cache. In

572

.B --no-daemon

573

mode or when full logging is enabled (-q), a complete dump of the contents of the cache is made.

574

.PP

575

Dnsmasq is a DNS query forwarder: it it not capable of recursively

576

answering arbitrary queries starting from the root servers but

577

forwards such queries to a fully recursive upstream DNS server which is

578

typically provided by an ISP. By default, dnsmasq reads

579

.I /etc/resolv.conf

580

to discover the IP

581

addresses of the upstream nameservers it should use, since the

582

information is typically stored there. Unless

583

.B --no-poll

584

is used,

585

.B dnsmasq

586

checks the modification time of

587

.I /etc/resolv.conf

588

(or equivalent if

589

.B \--resolv-file

590

is used) and re-reads it if it changes. This allows the DNS servers to

591

be set dynamically by PPP or DHCP since both protocols provide the

592

information.

593

Absence of

594

.I /etc/resolv.conf

595

is not an error

596

since it may not have been created before a PPP connection exists. Dnsmasq

597

simply keeps checking in case

598

.I /etc/resolv.conf

599

is created at any

600

time. Dnsmasq can be told to parse more than one resolv.conf

601

file. This is useful on a laptop, where both PPP and DHCP may be used:

602

dnsmasq can be set to poll both

603

.I /etc/ppp/resolv.conf

604

and

605

.I /etc/dhcpc/resolv.conf

606

and will use the contents of whichever changed

607

last, giving automatic switching between DNS servers.

608

.PP

609

Upstream servers may also be specified on the command line or in

610

the configuration file. These server specifications optionally take a

611

domain name which tells dnsmasq to use that server only to find names

612

in that particular domain.

613

.PP

614

In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in

615

.I /etc/resolv.conf

616

to force local processes to send queries to

617

dnsmasq. Then either specify the upstream servers directly to dnsmasq

618

using

619

.B \--server

620

options or put their addresses real in another file, say

621

.I /etc/resolv.dnsmasq

622

and run dnsmasq with the

623

.B \-r /etc/resolv.dnsmasq

624

option. This second technique allows for dynamic update of the server

625

addresses by PPP or DHCP.

626

.PP

627

Addresses in /etc/hosts will "shadow" different addresses for the same

628

names in the upstream DNS, so "mycompany.com 1.2.3.4" in /etc/hosts will ensure that

629

queries for "mycompany.com" always return 1.2.3.4 even if queries in

630

the upstream DNS would otherwise return a different address. There is

631

one exception to this: if the upstream DNS contains a CNAME which

632

points to a shadowed name, then looking up the CNAME through dnsmasq

633

will result in the unshadowed address associated with the target of

634

the CNAME. To work around this, add the CNAME to /etc/hosts so that

635

the CNAME is shadowed too.

636

637

.PP

638

The network-id system works as follows: For each DHCP request, dnsmasq

639

collects a set of valid network-id tags, one from the

640

.B dhcp-range

641

used to allocate the address, one from any matching

642

.B dhcp-host

643

and possibly many from matching vendor classes and user

644

classes sent by the DHCP client. Any

645

.B dhcp-option

646

which has network-id tags will be used in preference to an untagged

647

.B dhcp-option,

648

provided that _all_ the tags match somewhere in the

649

set collected as described above. The prefix '#' on a tag means 'not'

650

so --dhcp=option=#purple,3,1.2.3.4 sends the option when the

651

network-id tag purple is not in the set of valid tags.

652

.PP

653

If the network-id in a

654

.B dhcp-range

655

is prefixed with 'net:' then its meaning changes from setting a

656

tag to matching it. Thus if there is more than dhcp-range on a subnet,

657

and one is tagged with a network-id which is set (for instance

658

from a vendorclass option) then hosts which set the netid tag will be

659

allocated addresses in the tagged range.

660

.PP

661

The DHCP server in dnsmasq will function as a BOOTP server also,

662

provided that the MAC address and IP address for clients are given,

663

either using

664

.B dhcp-host

665

configurations or in

666

.I /etc/ethers

667

, and a

668

.B dhcp-range

669

configuration option is present to activate the DHCP server

670

on a particular network. (Setting --bootp-dynamic removes the need for

671

static address mappings.) The filename

672

parameter in a BOOTP request is matched against netids in

673

.B dhcp-option

674

configurations, allowing some control over the options returned to

675

different classes of hosts.

676

677

.SH FILES

678

.IR /etc/dnsmasq.conf

679

680

.IR /usr/local/etc/dnsmasq.conf

681

682

.IR /etc/resolv.conf

683

684

.IR /etc/hosts

685

686

.IR /etc/ethers

687

688

.IR /var/lib/misc/dnsmasq.leases

689

690

.IR /var/db/dnsmasq.leases

691

692

.IR /var/run/dnsmasq.pid

693

.SH SEE ALSO

694

.BR hosts (5),

695

.BR resolver (5)

696

.SH AUTHOR

697

This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.

698

699