~tj/ubuntu/saucy/isc-dhcp/fix-for-lp1235298 : revision 85

1

.\" dhcpd.conf.5

2

.\"

3

4

5

.\"

6

.\" Permission to use, copy, modify, and distribute this software for any

7

.\" purpose with or without fee is hereby granted, provided that the above

8

.\" copyright notice and this permission notice appear in all copies.

9

.\"

10

.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES

11

.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

12

.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR

13

.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

14

.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

15

.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT

16

.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

17

.\"

18

.\" Internet Systems Consortium, Inc.

19

.\" 950 Charter Street

20

.\" Redwood City, CA 94063

21

.\" <info@isc.org>

22

.\" https://www.isc.org/

23

.\"

24

.\" This software has been written for Internet Systems Consortium

25

.\" by Ted Lemon in cooperation with Vixie Enterprises and Nominum, Inc.

26

.\"

27

.\" Support and other services are available for ISC products - see

28

.\" https://www.isc.org for more information or to learn more about ISC.

29

.\"

30

.\" $Id: dhcpd.conf.5,v 1.106.18.8 2012-04-02 22:51:02 sar Exp $

31

.\"

32

.TH dhcpd.conf 5

33

.SH NAME

34

dhcpd.conf - dhcpd configuration file

35

.SH DESCRIPTION

36

The dhcpd.conf file contains configuration information for

37

.IR dhcpd,

38

the Internet Systems Consortium DHCP Server.

39

.PP

40

The dhcpd.conf file is a free-form ASCII text file. It is parsed by

41

the recursive-descent parser built into dhcpd. The file may contain

42

extra tabs and newlines for formatting purposes. Keywords in the file

43

are case-insensitive. Comments may be placed anywhere within the

44

file (except within quotes). Comments begin with the # character and

45

end at the end of the line.

46

.PP

47

The file essentially consists of a list of statements. Statements

48

fall into two broad categories - parameters and declarations.

49

.PP

50

Parameter statements either say how to do something (e.g., how long a

51

lease to offer), whether to do something (e.g., should dhcpd provide

52

addresses to unknown clients), or what parameters to provide to the

53

client (e.g., use gateway 220.177.244.7).

54

.PP

55

Declarations are used to describe the topology of the

56

network, to describe clients on the network, to provide addresses that

57

can be assigned to clients, or to apply a group of parameters to a

58

group of declarations. In any group of parameters and declarations,

59

all parameters must be specified before any declarations which depend

60

on those parameters may be specified.

61

.PP

62

Declarations about network topology include the \fIshared-network\fR

63

and the \fIsubnet\fR declarations. If clients on a subnet are to be

64

assigned addresses

65

dynamically, a \fIrange\fR declaration must appear within the

66

\fIsubnet\fR declaration. For clients with statically assigned

67

addresses, or for installations where only known clients will be

68

served, each such client must have a \fIhost\fR declaration. If

69

parameters are to be applied to a group of declarations which are not

70

related strictly on a per-subnet basis, the \fIgroup\fR declaration

71

can be used.

72

.PP

73

For every subnet which will be served, and for every subnet

74

to which the dhcp server is connected, there must be one \fIsubnet\fR

75

declaration, which tells dhcpd how to recognize that an address is on

76

that subnet. A \fIsubnet\fR declaration is required for each subnet

77

even if no addresses will be dynamically allocated on that subnet.

78

.PP

79

Some installations have physical networks on which more than one IP

80

subnet operates. For example, if there is a site-wide requirement

81

that 8-bit subnet masks be used, but a department with a single

82

physical ethernet network expands to the point where it has more than

83

254 nodes, it may be necessary to run two 8-bit subnets on the same

84

ethernet until such time as a new physical network can be added. In

85

this case, the \fIsubnet\fR declarations for these two networks must be

86

enclosed in a \fIshared-network\fR declaration.

87

.PP

88

Note that even when the \fIshared-network\fR declaration is absent, an

89

empty one is created by the server to contain the \fIsubnet\fR (and any scoped

90

parameters included in the \fIsubnet\fR). For practical purposes, this means

91

that "stateless" DHCP clients, which are not tied to addresses (and therefore

92

subnets) will receive the same configuration as stateful ones.

93

.PP

94

Some sites may have departments which have clients on more than one

95

subnet, but it may be desirable to offer those clients a uniform set

96

of parameters which are different than what would be offered to

97

clients from other departments on the same subnet. For clients which

98

will be declared explicitly with \fIhost\fR declarations, these

99

declarations can be enclosed in a \fIgroup\fR declaration along with

100

the parameters which are common to that department. For clients

101

whose addresses will be dynamically assigned, class declarations and

102

conditional declarations may be used to group parameter assignments

103

based on information the client sends.

104

.PP

105

When a client is to be booted, its boot parameters are determined by

106

consulting that client's \fIhost\fR declaration (if any), and then

107

consulting any \fIclass\fR declarations matching the client,

108

followed by the \fIpool\fR, \fIsubnet\fR and \fIshared-network\fR

109

declarations for the IP address assigned to the client. Each of

110

these declarations itself appears within a lexical scope, and all

111

declarations at less specific lexical scopes are also consulted for

112

client option declarations. Scopes are never considered

113

twice, and if parameters are declared in more than one scope, the

114

parameter declared in the most specific scope is the one that is

115

used.

116

.PP

117

When dhcpd tries to find a \fIhost\fR declaration for a client, it

118

first looks for a \fIhost\fR declaration which has a

119

\fIfixed-address\fR declaration that lists an IP address that is valid

120

for the subnet or shared network on which the client is booting. If

121

it doesn't find any such entry, it tries to find an entry which has

122

no \fIfixed-address\fR declaration.

123

.SH EXAMPLES

124

.PP

125

A typical dhcpd.conf file will look something like this:

126

.nf

127

128

.I global parameters...

129

130

subnet 204.254.239.0 netmask 255.255.255.224 {

131

\fIsubnet-specific parameters...\fR

132

range 204.254.239.10 204.254.239.30;

133

}

134

135

subnet 204.254.239.32 netmask 255.255.255.224 {

136

\fIsubnet-specific parameters...\fR

137

range 204.254.239.42 204.254.239.62;

138

}

139

140

subnet 204.254.239.64 netmask 255.255.255.224 {

141

\fIsubnet-specific parameters...\fR

142

range 204.254.239.74 204.254.239.94;

143

}

144

145

group {

146

\fIgroup-specific parameters...\fR

147

host zappo.test.isc.org {

148

\fIhost-specific parameters...\fR

149

}

150

host beppo.test.isc.org {

151

\fIhost-specific parameters...\fR

152

}

153

host harpo.test.isc.org {

154

\fIhost-specific parameters...\fR

155

}

156

}

157

158

.ce 1

159

Figure 1

160

161

.fi

162

.PP

163

Notice that at the beginning of the file, there's a place

164

for global parameters. These might be things like the organization's

165

domain name, the addresses of the name servers (if they are common to

166

the entire organization), and so on. So, for example:

167

.nf

168

169

option domain-name "isc.org";

170

option domain-name-servers ns1.isc.org, ns2.isc.org;

171

172

.ce 1

173

Figure 2

174

.fi

175

.PP

176

As you can see in Figure 2, you can specify host addresses in

177

parameters using their domain names rather than their numeric IP

178

addresses. If a given hostname resolves to more than one IP address

179

(for example, if that host has two ethernet interfaces), then where

180

possible, both addresses are supplied to the client.

181

.PP

182

The most obvious reason for having subnet-specific parameters as

183

shown in Figure 1 is that each subnet, of necessity, has its own

184

router. So for the first subnet, for example, there should be

185

something like:

186

.nf

187

188

option routers 204.254.239.1;

189

.fi

190

.PP

191

Note that the address here is specified numerically. This is not

192

required - if you have a different domain name for each interface on

193

your router, it's perfectly legitimate to use the domain name for that

194

interface instead of the numeric address. However, in many cases

195

there may be only one domain name for all of a router's IP addresses, and

196

it would not be appropriate to use that name here.

197

.PP

198

In Figure 1 there is also a \fIgroup\fR statement, which provides

199

common parameters for a set of three hosts - zappo, beppo and harpo.

200

As you can see, these hosts are all in the test.isc.org domain, so it

201

might make sense for a group-specific parameter to override the domain

202

name supplied to these hosts:

203

.nf

204

205

option domain-name "test.isc.org";

206

.fi

207

.PP

208

Also, given the domain they're in, these are probably test machines.

209

If we wanted to test the DHCP leasing mechanism, we might set the

210

lease timeout somewhat shorter than the default:

211

212

.nf

213

max-lease-time 120;

214

default-lease-time 120;

215

.fi

216

.PP

217

You may have noticed that while some parameters start with the

218

\fIoption\fR keyword, some do not. Parameters starting with the

219

\fIoption\fR keyword correspond to actual DHCP options, while

220

parameters that do not start with the option keyword either control

221

the behavior of the DHCP server (e.g., how long a lease dhcpd will

222

give out), or specify client parameters that are not optional in the

223

DHCP protocol (for example, server-name and filename).

224

.PP

225

In Figure 1, each host had \fIhost-specific parameters\fR. These

226

could include such things as the \fIhostname\fR option, the name of a

227

file to upload (the \fIfilename\fR parameter) and the address of the

228

server from which to upload the file (the \fInext-server\fR

229

parameter). In general, any parameter can appear anywhere that

230

parameters are allowed, and will be applied according to the scope in

231

which the parameter appears.

232

.PP

233

Imagine that you have a site with a lot of NCD X-Terminals. These

234

terminals come in a variety of models, and you want to specify the

235

boot files for each model. One way to do this would be to have host

236

declarations for each server and group them by model:

237

.nf

238

239

group {

240

filename "Xncd19r";

241

next-server ncd-booter;

242

243

host ncd1 { hardware ethernet 0:c0:c3:49:2b:57; }

244

host ncd4 { hardware ethernet 0:c0:c3:80:fc:32; }

245

host ncd8 { hardware ethernet 0:c0:c3:22:46:81; }

246

}

247

248

group {

249

filename "Xncd19c";

250

next-server ncd-booter;

251

252

host ncd2 { hardware ethernet 0:c0:c3:88:2d:81; }

253

host ncd3 { hardware ethernet 0:c0:c3:00:14:11; }

254

}

255

256

group {

257

filename "XncdHMX";

258

next-server ncd-booter;

259

260

host ncd1 { hardware ethernet 0:c0:c3:11:90:23; }

261

host ncd4 { hardware ethernet 0:c0:c3:91:a7:8; }

262

host ncd8 { hardware ethernet 0:c0:c3:cc:a:8f; }

263

}

264

.fi

265

.SH ADDRESS POOLS

266

.PP

267

The

268

.B pool

269

declaration can be used to specify a pool of addresses that will be

270

treated differently than another pool of addresses, even on the same

271

network segment or subnet. For example, you may want to provide a

272

large set of addresses that can be assigned to DHCP clients that are

273

registered to your DHCP server, while providing a smaller set of

274

addresses, possibly with short lease times, that are available for

275

unknown clients. If you have a firewall, you may be able to arrange

276

for addresses from one pool to be allowed access to the Internet,

277

while addresses in another pool are not, thus encouraging users to

278

register their DHCP clients. To do this, you would set up a pair of

279

pool declarations:

280

.PP

281

.nf

282

subnet 10.0.0.0 netmask 255.255.255.0 {

283

option routers 10.0.0.254;

284

285

# Unknown clients get this pool.

286

pool {

287

option domain-name-servers bogus.example.com;

288

max-lease-time 300;

289

range 10.0.0.200 10.0.0.253;

290

allow unknown-clients;

291

}

292

293

# Known clients get this pool.

294

pool {

295

option domain-name-servers ns1.example.com, ns2.example.com;

296

max-lease-time 28800;

297

range 10.0.0.5 10.0.0.199;

298

deny unknown-clients;

299

}

300

}

301

.fi

302

.PP

303

It is also possible to set up entirely different subnets for known and

304

unknown clients - address pools exist at the level of shared networks,

305

so address ranges within pool declarations can be on different

306

subnets.

307

.PP

308

As you can see in the preceding example, pools can have permit lists

309

that control which clients are allowed access to the pool and which

310

aren't. Each entry in a pool's permit list is introduced with the

311

.I allow

312

or \fIdeny\fR keyword. If a pool has a permit list, then only those

313

clients that match specific entries on the permit list will be

314

eligible to be assigned addresses from the pool. If a pool has a

315

deny list, then only those clients that do not match any entries on

316

the deny list will be eligible. If both permit and deny lists exist

317

for a pool, then only clients that match the permit list and do not

318

match the deny list will be allowed access.

319

.SH DYNAMIC ADDRESS ALLOCATION

320

Address allocation is actually only done when a client is in the INIT

321

state and has sent a DHCPDISCOVER message. If the client thinks it

322

has a valid lease and sends a DHCPREQUEST to initiate or renew that

323

lease, the server has only three choices - it can ignore the

324

DHCPREQUEST, send a DHCPNAK to tell the client it should stop using

325

the address, or send a DHCPACK, telling the client to go ahead and use

326

the address for a while.

327

.PP

328

If the server finds the address the client is requesting, and that

329

address is available to the client, the server will send a DHCPACK.

330

If the address is no longer available, or the client isn't permitted

331

to have it, the server will send a DHCPNAK. If the server knows

332

nothing about the address, it will remain silent, unless the address

333

is incorrect for the network segment to which the client has been

334

attached and the server is authoritative for that network segment, in

335

which case the server will send a DHCPNAK even though it doesn't know

336

about the address.

337

.PP

338

There may be a host declaration matching the client's identification.

339

If that host declaration contains a fixed-address declaration that

340

lists an IP address that is valid for the network segment to which the

341

client is connected. In this case, the DHCP server will never do

342

dynamic address allocation. In this case, the client is \fIrequired\fR

343

to take the address specified in the host declaration. If the

344

client sends a DHCPREQUEST for some other address, the server will respond

345

with a DHCPNAK.

346

.PP

347

When the DHCP server allocates a new address for a client (remember,

348

this only happens if the client has sent a DHCPDISCOVER), it first

349

looks to see if the client already has a valid lease on an IP address,

350

or if there is an old IP address the client had before that hasn't yet

351

been reassigned. In that case, the server will take that address and

352

check it to see if the client is still permitted to use it. If the

353

client is no longer permitted to use it, the lease is freed if the

354

server thought it was still in use - the fact that the client has sent

355

a DHCPDISCOVER proves to the server that the client is no longer using

356

the lease.

357

.PP

358

If no existing lease is found, or if the client is forbidden to

359

receive the existing lease, then the server will look in the list of

360

address pools for the network segment to which the client is attached

361

for a lease that is not in use and that the client is permitted to

362

have. It looks through each pool declaration in sequence (all

363

.I range

364

declarations that appear outside of pool declarations are grouped into

365

a single pool with no permit list). If the permit list for the pool

366

allows the client to be allocated an address from that pool, the pool

367

is examined to see if there is an address available. If so, then the

368

client is tentatively assigned that address. Otherwise, the next

369

pool is tested. If no addresses are found that can be assigned to

370

the client, no response is sent to the client.

371

.PP

372

If an address is found that the client is permitted to have, and that

373

has never been assigned to any client before, the address is

374

immediately allocated to the client. If the address is available for

375

allocation but has been previously assigned to a different client, the

376

server will keep looking in hopes of finding an address that has never

377

before been assigned to a client.

378

.PP

379

The DHCP server generates the list of available IP addresses from a

380

hash table. This means that the addresses are not sorted in any

381

particular order, and so it is not possible to predict the order in

382

which the DHCP server will allocate IP addresses. Users of previous

383

versions of the ISC DHCP server may have become accustomed to the DHCP

384

server allocating IP addresses in ascending order, but this is no

385

longer possible, and there is no way to configure this behavior with

386

version 3 of the ISC DHCP server.

387

.SH IP ADDRESS CONFLICT PREVENTION

388

The DHCP server checks IP addresses to see if they are in use before

389

allocating them to clients. It does this by sending an ICMP Echo

390

request message to the IP address being allocated. If no ICMP Echo

391

reply is received within a second, the address is assumed to be free.

392

This is only done for leases that have been specified in range

393

statements, and only when the lease is thought by the DHCP server to

394

be free - i.e., the DHCP server or its failover peer has not listed

395

the lease as in use.

396

.PP

397

If a response is received to an ICMP Echo request, the DHCP server

398

assumes that there is a configuration error - the IP address is in use

399

by some host on the network that is not a DHCP client. It marks the

400

address as abandoned, and will not assign it to clients.

401

.PP

402

If a DHCP client tries to get an IP address, but none are available,

403

but there are abandoned IP addresses, then the DHCP server will

404

attempt to reclaim an abandoned IP address. It marks one IP address

405

as free, and then does the same ICMP Echo request check described

406

previously. If there is no answer to the ICMP Echo request, the

407

address is assigned to the client.

408

.PP

409

The DHCP server does not cycle through abandoned IP addresses if the

410

first IP address it tries to reclaim is free. Rather, when the next

411

DHCPDISCOVER comes in from the client, it will attempt a new

412

allocation using the same method described here, and will typically

413

try a new IP address.

414

.SH DHCP FAILOVER

415

This version of the ISC DHCP server supports the DHCP failover

416

protocol as documented in draft-ietf-dhc-failover-12.txt. This is

417

not a final protocol document, and we have not done interoperability

418

testing with other vendors' implementations of this protocol, so you

419

must not assume that this implementation conforms to the standard.

420

If you wish to use the failover protocol, make sure that both failover

421

peers are running the same version of the ISC DHCP server.

422

.PP

423

The failover protocol allows two DHCP servers (and no more than two)

424

to share a common address pool. Each server will have about half of

425

the available IP addresses in the pool at any given time for

426

allocation. If one server fails, the other server will continue to

427

renew leases out of the pool, and will allocate new addresses out of

428

the roughly half of available addresses that it had when

429

communications with the other server were lost.

430

.PP

431

It is possible during a prolonged failure to tell the remaining server

432

that the other server is down, in which case the remaining server will

433

(over time) reclaim all the addresses the other server had available

434

for allocation, and begin to reuse them. This is called putting the

435

server into the PARTNER-DOWN state.

436

.PP

437

You can put the server into the PARTNER-DOWN state either by using the

438

.B omshell (1)

439

command or by stopping the server, editing the last failover state

440

declaration in the lease file, and restarting the server. If you use

441

this last method, change the "my state" line to:

442

.PP

443

.nf

444

.B failover peer "\fIname\fB" state {

445

.B my state partner-down;

446

.B peer state \fIstate\fB at \fIdate\fB;

447

.B }

448

.fi

449

.PP

450

It is only required to change "my state" as shown above.

451

.PP

452

When the other server comes back online, it should automatically

453

detect that it has been offline and request a complete update from the

454

server that was running in the PARTNER-DOWN state, and then both

455

servers will resume processing together.

456

.PP

457

It is possible to get into a dangerous situation: if you put one

458

server into the PARTNER-DOWN state, and then *that* server goes down,

459

and the other server comes back up, the other server will not know

460

that the first server was in the PARTNER-DOWN state, and may issue

461

addresses previously issued by the other server to different clients,

462

resulting in IP address conflicts. Before putting a server into

463

PARTNER-DOWN state, therefore, make

464

.I sure

465

that the other server will not restart automatically.

466

.PP

467

The failover protocol defines a primary server role and a secondary

468

server role. There are some differences in how primaries and

469

secondaries act, but most of the differences simply have to do with

470

providing a way for each peer to behave in the opposite way from the

471

other. So one server must be configured as primary, and the other

472

must be configured as secondary, and it doesn't matter too much which

473

one is which.

474

.SH FAILOVER STARTUP

475

When a server starts that has not previously communicated with its

476

failover peer, it must establish communications with its failover peer

477

and synchronize with it before it can serve clients. This can happen

478

either because you have just configured your DHCP servers to perform

479

failover for the first time, or because one of your failover servers

480

has failed catastrophically and lost its database.

481

.PP

482

The initial recovery process is designed to ensure that when one

483

failover peer loses its database and then resynchronizes, any leases

484

that the failed server gave out before it failed will be honored.

485

When the failed server starts up, it notices that it has no saved

486

failover state, and attempts to contact its peer.

487

.PP

488

When it has established contact, it asks the peer for a complete copy

489

its peer's lease database. The peer then sends its complete database,

490

and sends a message indicating that it is done. The failed server

491

then waits until MCLT has passed, and once MCLT has passed both

492

servers make the transition back into normal operation. This waiting

493

period ensures that any leases the failed server may have given out

494

while out of contact with its partner will have expired.

495

.PP

496

While the failed server is recovering, its partner remains in the

497

partner-down state, which means that it is serving all clients. The

498

failed server provides no service at all to DHCP clients until it has

499

made the transition into normal operation.

500

.PP

501

In the case where both servers detect that they have never before

502

communicated with their partner, they both come up in this recovery

503

state and follow the procedure we have just described. In this case,

504

no service will be provided to DHCP clients until MCLT has expired.

505

.SH CONFIGURING FAILOVER

506

In order to configure failover, you need to write a peer declaration

507

that configures the failover protocol, and you need to write peer

508

references in each pool declaration for which you want to do

509

failover. You do not have to do failover for all pools on a given

510

network segment. You must not tell one server it's doing failover

511

on a particular address pool and tell the other it is not. You must

512

not have any common address pools on which you are not doing

513

failover. A pool declaration that utilizes failover would look like this:

514

.PP

515

.nf

516

pool {

517

failover peer "foo";

518

\fIpool specific parameters\fR

519

};

520

.fi

521

.PP

522

The server currently does very little sanity checking, so if you

523

configure it wrong, it will just fail in odd ways. I would recommend

524

therefore that you either do failover or don't do failover, but don't

525

do any mixed pools. Also, use the same master configuration file for

526

both servers, and have a separate file that contains the peer

527

declaration and includes the master file. This will help you to avoid

528

configuration mismatches. As our implementation evolves, this will

529

become less of a problem. A basic sample dhcpd.conf file for a

530

primary server might look like this:

531

.PP

532

.nf

533

failover peer "foo" {

534

primary;

535

address anthrax.rc.vix.com;

536

port 519;

537

peer address trantor.rc.vix.com;

538

peer port 520;

539

max-response-delay 60;

540

max-unacked-updates 10;

541

mclt 3600;

542

split 128;

543

load balance max seconds 3;

544

}

545

546

include "/etc/dhcpd.master";

547

.fi

548

.PP

549

The statements in the peer declaration are as follows:

550

.PP

551

The

552

.I primary

553

and

554

.I secondary

555

statements

556

.RS 0.25i

557

.PP

558

[ \fBprimary\fR | \fBsecondary\fR ]\fB;\fR

559

.PP

560

This determines whether the server is primary or secondary, as

561

described earlier under DHCP FAILOVER.

562

.RE

563

.PP

564

The

565

.I address

566

statement

567

.RS 0.25i

568

.PP

569

.B address \fIaddress\fR\fB;\fR

570

.PP

571

The \fBaddress\fR statement declares the IP address or DNS name on which the

572

server should listen for connections from its failover peer, and also the

573

value to use for the DHCP Failover Protocol server identifier. Because this

574

value is used as an identifier, it may not be omitted.

575

.RE

576

.PP

577

The

578

.I peer address

579

statement

580

.RS 0.25i

581

.PP

582

.B peer address \fIaddress\fR\fB;\fR

583

.PP

584

The \fBpeer address\fR statement declares the IP address or DNS name to

585

which the server should connect to reach its failover peer for failover

586

messages.

587

.RE

588

.PP

589

The

590

.I port

591

statement

592

.RS 0.25i

593

.PP

594

.B port \fIport-number\fR\fB;\fR

595

.PP

596

The \fBport\fR statement declares the TCP port on which the server

597

should listen for connections from its failover peer. This statement

598

may be omitted, in which case the IANA assigned port number 647 will be

599

used by default.

600

.RE

601

.PP

602

The

603

.I peer port

604

statement

605

.RS 0.25i

606

.PP

607

.B peer port \fIport-number\fR\fB;\fR

608

.PP

609

The \fBpeer port\fR statement declares the TCP port to which the

610

server should connect to reach its failover peer for failover

611

messages. This statement may be omitted, in which case the IANA

612

assigned port number 647 will be used by default.

613

.RE

614

.PP

615

The

616

.I max-response-delay

617

statement

618

.RS 0.25i

619

.PP

620

.B max-response-delay \fIseconds\fR\fB;\fR

621

.PP

622

The \fBmax-response-delay\fR statement tells the DHCP server how

623

many seconds may pass without receiving a message from its failover

624

peer before it assumes that connection has failed. This number

625

should be small enough that a transient network failure that breaks

626

the connection will not result in the servers being out of

627

communication for a long time, but large enough that the server isn't

628

constantly making and breaking connections. This parameter must be

629

specified.

630

.RE

631

.PP

632

The

633

.I max-unacked-updates

634

statement

635

.RS 0.25i

636

.PP

637

.B max-unacked-updates \fIcount\fR\fB;\fR

638

.PP

639

The \fBmax-unacked-updates\fR statement tells the remote DHCP server how

640

many BNDUPD messages it can send before it receives a BNDACK

641

from the local system. We don't have enough operational experience

642

to say what a good value for this is, but 10 seems to work. This

643

parameter must be specified.

644

.RE

645

.PP

646

The

647

.I mclt

648

statement

649

.RS 0.25i

650

.PP

651

.B mclt \fIseconds\fR\fB;\fR

652

.PP

653

The \fBmclt\fR statement defines the Maximum Client Lead Time. It

654

must be specified on the primary, and may not be specified on the

655

secondary. This is the length of time for which a lease may be

656

renewed by either failover peer without contacting the other. The

657

longer you set this, the longer it will take for the running server to

658

recover IP addresses after moving into PARTNER-DOWN state. The

659

shorter you set it, the more load your servers will experience when

660

they are not communicating. A value of something like 3600 is

661

probably reasonable, but again bear in mind that we have no real

662

operational experience with this.

663

.RE

664

.PP

665

The

666

.I split

667

statement

668

.RS 0.25i

669

.PP

670

.B split \fIindex\fR\fB;\fR

671

.PP

672

The split statement specifies the split between the primary and

673

secondary for the purposes of load balancing. Whenever a client

674

makes a DHCP request, the DHCP server runs a hash on the client

675

identification, resulting in value from 0 to 255. This is used as

676

an index into a 256 bit field. If the bit at that index is set,

677

the primary is responsible. If the bit at that index is not set,

678

the secondary is responsible. The \fBsplit\fR value determines

679

how many of the leading bits are set to one. So, in practice, higher

680

split values will cause the primary to serve more clients than the

681

secondary. Lower split values, the converse. Legal values are between

682

0 and 255, of which the most reasonable is 128.

683

.RE

684

.PP

685

The

686

.I hba

687

statement

688

.RS 0.25i

689

.PP

690

.B hba \fIcolon-separated-hex-list\fB;\fR

691

.PP

692

The hba statement specifies the split between the primary and

693

secondary as a bitmap rather than a cutoff, which theoretically allows

694

for finer-grained control. In practice, there is probably no need

695

for such fine-grained control, however. An example hba statement:

696

.PP

697

.nf

698

hba ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:ff:

699

00:00:00:00:00:00:00:00:00:00:00:00:00:00:00:00;

700

.fi

701

.PP

702

This is equivalent to a \fBsplit 128;\fR statement, and identical. The

703

following two examples are also equivalent to a \fBsplit\fR of 128, but

704

are not identical:

705

.PP

706

.nf

707

hba aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:

708

aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa:aa;

709

710

hba 55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:

711

55:55:55:55:55:55:55:55:55:55:55:55:55:55:55:55;

712

.fi

713

.PP

714

They are equivalent, because half the bits are set to 0, half are set to

715

1 (0xa and 0x5 are 1010 and 0101 binary respectively) and consequently this

716

would roughly divide the clients equally between the servers. They are not

717

identical, because the actual peers this would load balance to each server

718

are different for each example.

719

.PP

720

You must only have \fBsplit\fR or \fBhba\fR defined, never both. For most

721

cases, the fine-grained control that \fBhba\fR offers isn't necessary, and

722

\fBsplit\fR should be used.

723

.RE

724

.PP

725

The

726

.I load balance max seconds

727

statement

728

.RS 0.25i

729

.PP

730

.B load balance max seconds \fIseconds\fR\fB;\fR

731

.PP

732

This statement allows you to configure a cutoff after which load

733

balancing is disabled. The cutoff is based on the number of seconds

734

since the client sent its first DHCPDISCOVER or DHCPREQUEST message,

735

and only works with clients that correctly implement the \fIsecs\fR

736

field - fortunately most clients do. We recommend setting this to

737

something like 3 or 5. The effect of this is that if one of the

738

failover peers gets into a state where it is responding to failover

739

messages but not responding to some client requests, the other

740

failover peer will take over its client load automatically as the

741

clients retry.

742

.RE

743

.PP

744

The

745

.I auto-partner-down

746

statement

747

.RS 0.25i

748

.PP

749

.B auto-partner-down \fIseconds\fR\fB;\fR

750

.PP

751

This statement instructs the server to initiate a timed delay upon entering

752

the communications-interrupted state (any situation of being out-of-contact

753

with the remote failover peer). At the conclusion of the timer, the server

754

will automatically enter the partner-down state. This permits the server

755

to allocate leases from the partner's free lease pool after an STOS+MCLT

756

timer expires, which can be dangerous if the partner is in fact operating

757

at the time (the two servers will give conflicting bindings).

758

.PP

759

Think very carefully before enabling this feature. The partner-down and

760

communications-interrupted states are intentionally segregated because

761

there do exist situations where a failover server can fail to communicate

762

with its peer, but still has the ability to receive and reply to requests

763

from DHCP clients. In general, this feature should only be used in those

764

deployments where the failover servers are directly connected to one

765

another, such as by a dedicated hardwired link ("a heartbeat cable").

766

.PP

767

A zero value disables the auto-partner-down feature (also the default), and

768

any positive value indicates the time in seconds to wait before automatically

769

entering partner-down.

770

.RE

771

.PP

772

The Failover pool balance statements.

773

.RS 0.25i

774

.PP

775

\fBmax-lease-misbalance \fIpercentage\fR\fB;\fR

776

\fBmax-lease-ownership \fIpercentage\fR\fB;\fR

777

\fBmin-balance \fIseconds\fR\fB;\fR

778

\fBmax-balance \fIseconds\fR\fB;\fR

779

.PP

780

This version of the DHCP Server evaluates pool balance on a schedule,

781

rather than on demand as leases are allocated. The latter approach

782

proved to be slightly klunky when pool misbalanced reach total

783

saturation...when any server ran out of leases to assign, it also lost

784

its ability to notice it had run dry.

785

.PP

786

In order to understand pool balance, some elements of its operation

787

first need to be defined. First, there are \'free\' and \'backup\' leases.

788

Both of these are referred to as \'free state leases\'. \'free\' and

789

\'backup\'

790

are \'the free states\' for the purpose of this document. The difference

791

is that only the primary may allocate from \'free\' leases unless under

792

special circumstances, and only the secondary may allocate \'backup\' leases.

793

.PP

794

When pool balance is performed, the only plausible expectation is to

795

provide a 50/50 split of the free state leases between the two servers.

796

This is because no one can predict which server will fail, regardless

797

of the relative load placed upon the two servers, so giving each server

798

half the leases gives both servers the same amount of \'failure endurance\'.

799

Therefore, there is no way to configure any different behaviour, outside of

800

some very small windows we will describe shortly.

801

.PP

802

The first thing calculated on any pool balance run is a value referred to

803

as \'lts\', or "Leases To Send". This, simply, is the difference in the

804

count of free and backup leases, divided by two. For the secondary,

805

it is the difference in the backup and free leases, divided by two.

806

The resulting value is signed: if it is positive, the local server is

807

expected to hand out leases to retain a 50/50 balance. If it is negative,

808

the remote server would need to send leases to balance the pool. Once

809

the lts value reaches zero, the pool is perfectly balanced (give or take

810

one lease in the case of an odd number of total free state leases).

811

.PP

812

The current approach is still something of a hybrid of the old approach,

813

marked by the presence of the \fBmax-lease-misbalance\fR statement. This

814

parameter configures what used to be a 10% fixed value in previous versions:

815

if lts is less than free+backup * \fBmax-lease-misbalance\fR percent, then

816

the server will skip balancing a given pool (it won't bother moving any

817

leases, even if some leases "should" be moved). The meaning of this value

818

is also somewhat overloaded, however, in that it also governs the estimation

819

of when to attempt to balance the pool (which may then also be skipped over).

820

The oldest leases in the free and backup states are examined. The time

821

they have resided in their respective queues is used as an estimate to

822

indicate how much time it is probable it would take before the leases at

823

the top of the list would be consumed (and thus, how long it would take

824

to use all leases in that state). This percentage is directly multiplied

825

by this time, and fit into the schedule if it falls within

826

the \fBmin-balance\fR and \fBmax-balance\fR configured values. The

827

scheduled pool check time is only moved in a downwards direction, it is

828

never increased. Lastly, if the lts is more than double this number in

829

the negative direction, the local server will \'panic\' and transmit a

830

Failover protocol POOLREQ message, in the hopes that the remote system

831

will be woken up into action.

832

.PP

833

Once the lts value exceeds the \fBmax-lease-misbalance\fR percentage of

834

total free state leases as described above, leases are moved to the remote

835

server. This is done in two passes.

836

.PP

837

In the first pass, only leases whose most recent bound client would have

838

been served by the remote server - according to the Load Balance Algorithm

839

(see above \fBsplit\fR and \fBhba\fR configuration statements) - are given

840

away to the peer. This first pass will happily continue to give away leases,

841

decrementing the lts value by one for each, until the lts value has reached

842

the negative of the total number of leases multiplied by

843

the \fBmax-lease-ownership\fR percentage. So it is through this value that

844

you can permit a small misbalance of the lease pools - for the purpose of

845

giving the peer more than a 50/50 share of leases in the hopes that their

846

clients might some day return and be allocated by the peer (operating

847

normally). This process is referred to as \'MAC Address Affinity\', but this

848

is somewhat misnamed: it applies equally to DHCP Client Identifier options.

849

Note also that affinity is applied to leases when they enter the state

850

\'free\' from \'expired\' or \'released\'. In this case also, leases will not

851

be moved from free to backup if the secondary already has more than its

852

share.

853

.PP

854

The second pass is only entered into if the first pass fails to reduce

855

the lts underneath the total number of free state leases multiplied by

856

the \fBmax-lease-ownership\fR percentage. In this pass, the oldest

857

leases are given over to the peer without second thought about the Load

858

Balance Algorithm, and this continues until the lts falls under this

859

value. In this way, the local server will also happily keep a small

860

percentage of the leases that would normally load balance to itself.

861

.PP

862

So, the \fBmax-lease-misbalance\fR value acts as a behavioural gate.

863

Smaller values will cause more leases to transition states to balance

864

the pools over time, higher values will decrease the amount of change

865

(but may lead to pool starvation if there's a run on leases).

866

.PP

867

The \fBmax-lease-ownership\fR value permits a small (percentage) skew

868

in the lease balance of a percentage of the total number of free state

869

leases.

870

.PP

871

Finally, the \fBmin-balance\fR and \fBmax-balance\fR make certain that a

872

scheduled rebalance event happens within a reasonable timeframe (not

873

to be thrown off by, for example, a 7 year old free lease).

874

.PP

875

Plausible values for the percentages lie between 0 and 100, inclusive, but

876

values over 50 are indistinguishable from one another (once lts exceeds

877

50% of the free state leases, one server must therefore have 100% of the

878

leases in its respective free state). It is recommended to select

879

a \fBmax-lease-ownership\fR value that is lower than the value selected

880

for the \fBmax-lease-misbalance\fR value. \fBmax-lease-ownership\fR

881

defaults to 10, and \fBmax-lease-misbalance\fR defaults to 15.

882

.PP

883

Plausible values for the \fBmin-balance\fR and \fBmax-balance\fR times also

884

range from 0 to (2^32)-1 (or the limit of your local time_t value), but

885

default to values 60 and 3600 respectively (to place balance events between

886

1 minute and 1 hour).

887

.RE

888

.SH CLIENT CLASSING

889

Clients can be separated into classes, and treated differently

890

depending on what class they are in. This separation can be done

891

either with a conditional statement, or with a match statement within

892

the class declaration. It is possible to specify a limit on the

893

total number of clients within a particular class or subclass that may

894

hold leases at one time, and it is possible to specify automatic

895

subclassing based on the contents of the client packet.

896

.PP

897

To add clients to classes based on conditional evaluation, you can

898

specify a matching expression in the class statement:

899

.PP

900

.nf

901

class "ras-clients" {

902

match if substring (option dhcp-client-identifier, 1, 3) = "RAS";

903

}

904

.fi

905

.PP

906

Note that whether you use matching expressions or add statements (or

907

both) to classify clients, you must always write a class declaration

908

for any class that you use. If there will be no match statement and

909

no in-scope statements for a class, the declaration should look like

910

this:

911

.PP

912

.nf

913

class "ras-clients" {

914

}

915

.fi

916

.SH SUBCLASSES

917

.PP

918

In addition to classes, it is possible to declare subclasses. A

919

subclass is a class with the same name as a regular class, but with a

920

specific submatch expression which is hashed for quick matching.

921

This is essentially a speed hack - the main difference between five

922

classes with match expressions and one class with five subclasses is

923

that it will be quicker to find the subclasses. Subclasses work as

924

follows:

925

.PP

926

.nf

927

class "allocation-class-1" {

928

match pick-first-value (option dhcp-client-identifier, hardware);

929

}

930

931

class "allocation-class-2" {

932

match pick-first-value (option dhcp-client-identifier, hardware);

933

}

934

935

subclass "allocation-class-1" 1:8:0:2b:4c:39:ad;

936

subclass "allocation-class-2" 1:8:0:2b:a9:cc:e3;

937

subclass "allocation-class-1" 1:0:0:c4:aa:29:44;

938

939

subnet 10.0.0.0 netmask 255.255.255.0 {

940

pool {

941

allow members of "allocation-class-1";

942

range 10.0.0.11 10.0.0.50;

943

}

944

pool {

945

allow members of "allocation-class-2";

946

range 10.0.0.51 10.0.0.100;

947

}

948

}

949

.fi

950

.PP

951

The data following the class name in the subclass declaration is a

952

constant value to use in matching the match expression for the class.

953

When class matching is done, the server will evaluate the match

954

expression and then look the result up in the hash table. If it

955

finds a match, the client is considered a member of both the class and

956

the subclass.

957

.PP

958

Subclasses can be declared with or without scope. In the above

959

example, the sole purpose of the subclass is to allow some clients

960

access to one address pool, while other clients are given access to

961

the other pool, so these subclasses are declared without scopes. If

962

part of the purpose of the subclass were to define different parameter

963

values for some clients, you might want to declare some subclasses

964

with scopes.

965

.PP

966

In the above example, if you had a single client that needed some

967

configuration parameters, while most didn't, you might write the

968

following subclass declaration for that client:

969

.PP

970

.nf

971

subclass "allocation-class-2" 1:08:00:2b:a1:11:31 {

972

option root-path "samsara:/var/diskless/alphapc";

973

filename "/tftpboot/netbsd.alphapc-diskless";

974

}

975

.fi

976

.PP

977

In this example, we've used subclassing as a way to control address

978

allocation on a per-client basis. However, it's also possible to use

979

subclassing in ways that are not specific to clients - for example, to

980

use the value of the vendor-class-identifier option to determine what

981

values to send in the vendor-encapsulated-options option. An example

982

of this is shown under the VENDOR ENCAPSULATED OPTIONS head in the

983

.B dhcp-options(5)

984

manual page.

985

.SH PER-CLASS LIMITS ON DYNAMIC ADDRESS ALLOCATION

986

.PP

987

You may specify a limit to the number of clients in a class that can

988

be assigned leases. The effect of this will be to make it difficult

989

for a new client in a class to get an address. Once a class with

990

such a limit has reached its limit, the only way a new client in that

991

class can get a lease is for an existing client to relinquish its

992

lease, either by letting it expire, or by sending a DHCPRELEASE

993

packet. Classes with lease limits are specified as follows:

994

.PP

995

.nf

996

class "limited-1" {

997

lease limit 4;

998

}

999

.fi

1000

.PP

1001

This will produce a class in which a maximum of four members may hold

1002

a lease at one time.

1003

.SH SPAWNING CLASSES

1004

.PP

1005

It is possible to declare a

1006

.I spawning class\fR.

1007

A spawning class is a class that automatically produces subclasses

1008

based on what the client sends. The reason that spawning classes

1009

were created was to make it possible to create lease-limited classes

1010

on the fly. The envisioned application is a cable-modem environment

1011

where the ISP wishes to provide clients at a particular site with more

1012

than one IP address, but does not wish to provide such clients with

1013

their own subnet, nor give them an unlimited number of IP addresses

1014

from the network segment to which they are connected.

1015

.PP

1016

Many cable modem head-end systems can be configured to add a Relay

1017

Agent Information option to DHCP packets when relaying them to the

1018

DHCP server. These systems typically add a circuit ID or remote ID

1019

option that uniquely identifies the customer site. To take advantage

1020

of this, you can write a class declaration as follows:

1021

.PP

1022

.nf

1023

class "customer" {

1024

spawn with option agent.circuit-id;

1025

lease limit 4;

1026

}

1027

.fi

1028

.PP

1029

Now whenever a request comes in from a customer site, the circuit ID

1030

option will be checked against the class's hash table. If a subclass

1031

is found that matches the circuit ID, the client will be classified in

1032

that subclass and treated accordingly. If no subclass is found

1033

matching the circuit ID, a new one will be created and logged in the

1034

.B dhcpd.leases

1035

file, and the client will be classified in this new class. Once the

1036

client has been classified, it will be treated according to the rules

1037

of the class, including, in this case, being subject to the per-site

1038

limit of four leases.

1039

.PP

1040

The use of the subclass spawning mechanism is not restricted to relay

1041

agent options - this particular example is given only because it is a

1042

fairly straightforward one.

1043

.SH COMBINING MATCH, MATCH IF AND SPAWN WITH

1044

.PP

1045

In some cases, it may be useful to use one expression to assign a

1046

client to a particular class, and a second expression to put it into a

1047

subclass of that class. This can be done by combining the \fBmatch

1048

if\fR and \fBspawn with\fR statements, or the \fBmatch if\fR and

1049

\fBmatch\fR statements. For example:

1050

.PP

1051

.nf

1052

class "jr-cable-modems" {

1053

match if option dhcp-vendor-identifier = "jrcm";

1054

spawn with option agent.circuit-id;

1055

lease limit 4;

1056

}

1057

1058

class "dv-dsl-modems" {

1059

match if option dhcp-vendor-identifier = "dvdsl";

1060

spawn with option agent.circuit-id;

1061

lease limit 16;

1062

}

1063

.fi

1064

.PP

1065

This allows you to have two classes that both have the same \fBspawn

1066

with\fR expression without getting the clients in the two classes

1067

confused with each other.

1068

.SH DYNAMIC DNS UPDATES

1069

.PP

1070

The DHCP server has the ability to dynamically update the Domain Name

1071

System. Within the configuration files, you can define how you want

1072

the Domain Name System to be updated. These updates are RFC 2136

1073

compliant so any DNS server supporting RFC 2136 should be able to

1074

accept updates from the DHCP server.

1075

.PP

1076

Two DNS update schemes are currently implemented, and another is

1077

planned. The two that are currently implemented are the ad-hoc DNS

1078

update mode and the interim DHCP-DNS interaction draft update mode.

1079

In the future we plan to add a third mode which will be the standard

1080

DNS update method based on the RFCS for DHCP-DNS interaction and DHCID

1081

The DHCP server must be configured to use one of the two

1082

currently-supported methods, or not to do dns updates.

1083

This can be done with the

1084

.I ddns-update-style

1085

configuration parameter.

1086

.SH THE AD-HOC DNS UPDATE SCHEME

1087

The ad-hoc Dynamic DNS update scheme is

1088

.B now deprecated

1089

and

1090

.B

1091

does not work.

1092

In future releases of the ISC DHCP server, this scheme will not likely be

1093

available. The interim scheme works, allows for failover, and should now be

1094

used. The following description is left here for informational purposes

1095

only.

1096

.PP

1097

The ad-hoc Dynamic DNS update scheme implemented in this version of

1098

the ISC DHCP server is a prototype design, which does not

1099

have much to do with the standard update method that is being

1100

standardized in the IETF DHC working group, but rather implements some

1101

very basic, yet useful, update capabilities. This mode

1102

.B does not work

1103

with the

1104

.I failover protocol

1105

because it does not account for the possibility of two different DHCP

1106

servers updating the same set of DNS records.

1107

.PP

1108

For the ad-hoc DNS update method, the client's FQDN is derived in two

1109

parts. First, the hostname is determined. Then, the domain name is

1110

determined, and appended to the hostname.

1111

.PP

1112

The DHCP server determines the client's hostname by first looking for

1113

a \fIddns-hostname\fR configuration option, and using that if it is

1114

present. If no such option is present, the server looks for a

1115

valid hostname in the FQDN option sent by the client. If one is

1116

found, it is used; otherwise, if the client sent a host-name option,

1117

that is used. Otherwise, if there is a host declaration that applies

1118

to the client, the name from that declaration will be used. If none

1119

of these applies, the server will not have a hostname for the client,

1120

and will not be able to do a DNS update.

1121

.PP

1122

The domain name is determined from the

1123

.I ddns-domainname

1124

configuration option. The default configuration for this option is:

1125

.nf

1126

.sp 1

1127

option server.ddns-domainname = config-option domain-name;

1128

1129

.fi

1130

So if this configuration option is not configured to a different

1131

value (over-riding the above default), or if a domain-name option

1132

has not been configured for the client's scope, then the server will

1133

not attempt to perform a DNS update.

1134

.PP

1135

The client's fully-qualified domain name, derived as we have

1136

described, is used as the name on which an "A" record will be stored.

1137

The A record will contain the IP address that the client was assigned

1138

in its lease. If there is already an A record with the same name in

1139

the DNS server, no update of either the A or PTR records will occur -

1140

this prevents a client from claiming that its hostname is the name of

1141

some network server. For example, if you have a fileserver called

1142

"fs.sneedville.edu", and the client claims its hostname is "fs", no

1143

DNS update will be done for that client, and an error message will be

1144

logged.

1145

.PP

1146

If the A record update succeeds, a PTR record update for the assigned

1147

IP address will be done, pointing to the A record. This update is

1148

unconditional - it will be done even if another PTR record of the same

1149

name exists. Since the IP address has been assigned to the DHCP

1150

server, this should be safe.

1151

.PP

1152

Please note that the current implementation assumes clients only have

1153

a single network interface. A client with two network interfaces

1154

will see unpredictable behavior. This is considered a bug, and will

1155

be fixed in a later release. It may be helpful to enable the

1156

.I one-lease-per-client

1157

parameter so that roaming clients do not trigger this same behavior.

1158

.PP

1159

The DHCP protocol normally involves a four-packet exchange - first the

1160

client sends a DHCPDISCOVER message, then the server sends a

1161

DHCPOFFER, then the client sends a DHCPREQUEST, then the server sends

1162

a DHCPACK. In the current version of the server, the server will do

1163

a DNS update after it has received the DHCPREQUEST, and before it has

1164

sent the DHCPACK. It only sends the DNS update if it has not sent

1165

one for the client's address before, in order to minimize the impact

1166

on the DHCP server.

1167

.PP

1168

When the client's lease expires, the DHCP server (if it is operating

1169

at the time, or when next it operates) will remove the client's A and

1170

PTR records from the DNS database. If the client releases its lease

1171

by sending a DHCPRELEASE message, the server will likewise remove the

1172

A and PTR records.

1173

.SH THE INTERIM DNS UPDATE SCHEME

1174

The interim DNS update scheme operates mostly according to several

1175

drafts considered by the IETF. While the drafts have since become

1176

RFCs the code was written before they were finalized and there are

1177

some differences between our code and the final RFCs. We plan to

1178

update our code, probably adding a standard DNS update option, at

1179

some time. The basic framework is similar with the main material

1180

difference being that a DHCID RR was assigned in the RFCs whereas

1181

our code continues to use an experimental TXT record. The format

1182

of the TXT record bears a resemblance to the DHCID RR but it is not

1183

equivalent (MD5 vs SHA1, field length differences etc).

1184

The standard RFCs are:

1185

.PP

1186

.nf

1187

.ce 3

1188

RFC 4701 (updated by RF5494)

1189

RFC 4702

1190

RFC 4703

1191

.fi

1192

.PP

1193

And the corresponding drafts were:

1194

.PP

1195

.nf

1196

.ce 3

1197

draft-ietf-dnsext-dhcid-rr-??.txt

1198

draft-ietf-dhc-fqdn-option-??.txt

1199

draft-ietf-dhc-ddns-resolution-??.txt

1200

.fi

1201

.PP

1202

Because our implementation is slightly different than the standard, we

1203

will briefly document the operation of this update style here.

1204

.PP

1205

The first point to understand about this style of DNS update is that

1206

unlike the ad-hoc style, the DHCP server does not necessarily

1207

always update both the A and the PTR records. The FQDN option

1208

includes a flag which, when sent by the client, indicates that the

1209

client wishes to update its own A record. In that case, the server

1210

can be configured either to honor the client's intentions or ignore

1211

them. This is done with the statement \fIallow client-updates;\fR or

1212

the statement \fIignore client-updates;\fR. By default, client

1213

updates are allowed.

1214

.PP

1215

If the server is configured to allow client updates, then if the

1216

client sends a fully-qualified domain name in the FQDN option, the

1217

server will use that name the client sent in the FQDN option to update

1218

the PTR record. For example, let us say that the client is a visitor

1219

from the "radish.org" domain, whose hostname is "jschmoe". The

1220

server is for the "example.org" domain. The DHCP client indicates in

1221

the FQDN option that its FQDN is "jschmoe.radish.org.". It also

1222

indicates that it wants to update its own A record. The DHCP server

1223

therefore does not attempt to set up an A record for the client, but

1224

does set up a PTR record for the IP address that it assigns the

1225

client, pointing at jschmoe.radish.org. Once the DHCP client has an

1226

IP address, it can update its own A record, assuming that the

1227

"radish.org" DNS server will allow it to do so.

1228

.PP

1229

If the server is configured not to allow client updates, or if the

1230

client doesn't want to do its own update, the server will simply

1231

choose a name for the client from either the fqdn option (if present)

1232

or the hostname option (if present). It will use its own

1233

domain name for the client, just as in the ad-hoc update scheme.

1234

It will then update both the A and PTR record, using the name that it

1235

chose for the client. If the client sends a fully-qualified domain

1236

name in the fqdn option, the server uses only the leftmost part of the

1237

domain name - in the example above, "jschmoe" instead of

1238

"jschmoe.radish.org".

1239

.PP

1240

Further, if the \fIignore client-updates;\fR directive is used, then

1241

the server will in addition send a response in the DHCP packet, using

1242

the FQDN Option, that implies to the client that it should perform its

1243

own updates if it chooses to do so. With \fIdeny client-updates;\fR, a

1244

response is sent which indicates the client may not perform updates.

1245

.PP

1246

Also, if the

1247

.I use-host-decl-names

1248

configuration option is enabled, then the host declaration's

1249

.I hostname

1250

will be used in place of the

1251

.I hostname

1252

option, and the same rules will apply as described above.

1253

.PP

1254

The other difference between the ad-hoc scheme and the interim

1255

scheme is that with the interim scheme, a method is used that

1256

allows more than one DHCP server to update the DNS database without

1257

accidentally deleting A records that shouldn't be deleted nor failing

1258

to add A records that should be added. The scheme works as follows:

1259

.PP

1260

When the DHCP server issues a client a new lease, it creates a text

1261

string that is an MD5 hash over the DHCP client's identification (see

1262

draft-ietf-dnsext-dhcid-rr-??.txt for details). The update adds an A

1263

record with the name the server chose and a TXT record containing the

1264

hashed identifier string (hashid). If this update succeeds, the

1265

server is done.

1266

.PP

1267

If the update fails because the A record already exists, then the DHCP

1268

server attempts to add the A record with the prerequisite that there

1269

must be a TXT record in the same name as the new A record, and that

1270

TXT record's contents must be equal to hashid. If this update

1271

succeeds, then the client has its A record and PTR record. If it

1272

fails, then the name the client has been assigned (or requested) is in

1273

use, and can't be used by the client. At this point the DHCP server

1274

gives up trying to do a DNS update for the client until the client

1275

chooses a new name.

1276

.PP

1277

The interim DNS update scheme is called interim for two reasons.

1278

First, it does not quite follow the RFCs. The RFCs call for a

1279

new DHCID RRtype while he interim DNS update scheme uses a TXT record.

1280

The ddns-resolution draft called for the DHCP server to put a DHCID RR

1281

on the PTR record, but the \fIinterim\fR update method does not do this.

1282

In the final RFC this requirement was relaxed such that a server may

1283

add a DHCID RR to the PTR record.

1284

.PP

1285

In addition to these differences, the server also does not update very

1286

aggressively. Because each DNS update involves a round trip to the

1287

DNS server, there is a cost associated with doing updates even if they

1288

do not actually modify the DNS database. So the DHCP server tracks

1289

whether or not it has updated the record in the past (this information

1290

is stored on the lease) and does not attempt to update records that it

1291

thinks it has already updated.

1292

.PP

1293

This can lead to cases where the DHCP server adds a record, and then

1294

the record is deleted through some other mechanism, but the server

1295

never again updates the DNS because it thinks the data is already

1296

there. In this case the data can be removed from the lease through

1297

operator intervention, and once this has been done, the DNS will be

1298

updated the next time the client renews.

1299

.SH DYNAMIC DNS UPDATE SECURITY

1300

.PP

1301

When you set your DNS server up to allow updates from the DHCP server,

1302

you may be exposing it to unauthorized updates. To avoid this, you

1303

should use TSIG signatures - a method of cryptographically signing

1304

updates using a shared secret key. As long as you protect the

1305

secrecy of this key, your updates should also be secure. Note,

1306

however, that the DHCP protocol itself provides no security, and that

1307

clients can therefore provide information to the DHCP server which the

1308

DHCP server will then use in its updates, with the constraints

1309

described previously.

1310

.PP

1311

The DNS server must be configured to allow updates for any zone that

1312

the DHCP server will be updating. For example, let us say that

1313

clients in the sneedville.edu domain will be assigned addresses on the

1314

10.10.17.0/24 subnet. In that case, you will need a key declaration

1315

for the TSIG key you will be using, and also two zone declarations -

1316

one for the zone containing A records that will be updates and one for

1317

the zone containing PTR records - for ISC BIND, something like this:

1318

.PP

1319

.nf

1320

key DHCP_UPDATER {

1321

algorithm HMAC-MD5.SIG-ALG.REG.INT;

1322

secret pRP5FapFoJ95JEL06sv4PQ==;

1323

};

1324

1325

zone "example.org" {

1326

type master;

1327

file "example.org.db";

1328

allow-update { key DHCP_UPDATER; };

1329

};

1330

1331

zone "17.10.10.in-addr.arpa" {

1332

type master;

1333

file "10.10.17.db";

1334

allow-update { key DHCP_UPDATER; };

1335

};

1336

.fi

1337

.PP

1338

You will also have to configure your DHCP server to do updates to

1339

these zones. To do so, you need to add something like this to your

1340

dhcpd.conf file:

1341

.PP

1342

.nf

1343

key DHCP_UPDATER {

1344

algorithm HMAC-MD5.SIG-ALG.REG.INT;

1345

secret pRP5FapFoJ95JEL06sv4PQ==;

1346

};

1347

1348

zone EXAMPLE.ORG. {

1349

primary 127.0.0.1;

1350

key DHCP_UPDATER;

1351

}

1352

1353

zone 17.127.10.in-addr.arpa. {

1354

primary 127.0.0.1;

1355

key DHCP_UPDATER;

1356

}

1357

.fi

1358

.PP

1359

The \fIprimary\fR statement specifies the IP address of the name

1360

server whose zone information is to be updated. In addition to

1361

the \fIprimary\fR statement there are also the \fIprimary6\fR ,

1362

\fIsecondary\fR and \fIsecondary6\fR statements. The \fIprimary6\fR

1363

statement specifies an IPv6 address for the name server. The

1364

secondaries provide for additional addresses for name servers

1365

to be used if the primary does not respond. The number of name

1366

servers the DDNS code will attempt to use before giving up

1367

is limited and is currently set to three.

1368

.PP

1369

Note that the zone declarations have to correspond to authority

1370

records in your name server - in the above example, there must be an

1371

SOA record for "example.org." and for "17.10.10.in-addr.arpa.". For

1372

example, if there were a subdomain "foo.example.org" with no separate

1373

SOA, you could not write a zone declaration for "foo.example.org."

1374

Also keep in mind that zone names in your DHCP configuration should end in a

1375

"."; this is the preferred syntax. If you do not end your zone name in a

1376

".", the DHCP server will figure it out. Also note that in the DHCP

1377

configuration, zone names are not encapsulated in quotes where there are in

1378

the DNS configuration.

1379

.PP

1380

You should choose your own secret key, of course. The ISC BIND 8 and

1381

9 distributions come with a program for generating secret keys called

1382

dnssec-keygen. The version that comes with BIND 9 is likely to produce a

1383

substantially more random key, so we recommend you use that one even

1384

if you are not using BIND 9 as your DNS server. If you are using BIND 9's

1385

dnssec-keygen, the above key would be created as follows:

1386

.PP

1387

.nf

1388

dnssec-keygen -a HMAC-MD5 -b 128 -n USER DHCP_UPDATER

1389

.fi

1390

.PP

1391

If you are using the BIND 8 dnskeygen program, the following command will

1392

generate a key as seen above:

1393

.PP

1394

.nf

1395

dnskeygen -H 128 -u -c -n DHCP_UPDATER

1396

.fi

1397

.PP

1398

You may wish to enable logging of DNS updates on your DNS server.

1399

To do so, you might write a logging statement like the following:

1400

.PP

1401

.nf

1402

logging {

1403

channel update_debug {

1404

file "/var/log/update-debug.log";

1405

severity debug 3;

1406

print-category yes;

1407

print-severity yes;

1408

print-time yes;

1409

};

1410

channel security_info {

1411

file "/var/log/named-auth.info";

1412

severity info;

1413

print-category yes;

1414

print-severity yes;

1415

print-time yes;

1416

};

1417

1418

category update { update_debug; };

1419

category security { security_info; };

1420

};

1421

.fi

1422

.PP

1423

You must create the /var/log/named-auth.info and

1424

/var/log/update-debug.log files before starting the name server. For

1425

more information on configuring ISC BIND, consult the documentation

1426

that accompanies it.

1427

.SH REFERENCE: EVENTS

1428

.PP

1429

There are three kinds of events that can happen regarding a lease, and

1430

it is possible to declare statements that occur when any of these

1431

events happen. These events are the commit event, when the server

1432

has made a commitment of a certain lease to a client, the release

1433

event, when the client has released the server from its commitment,

1434

and the expiry event, when the commitment expires.

1435

.PP

1436

To declare a set of statements to execute when an event happens, you

1437

must use the \fBon\fR statement, followed by the name of the event,

1438

followed by a series of statements to execute when the event happens,

1439

enclosed in braces. Events are used to implement DNS

1440

updates, so you should not define your own event handlers if you are

1441

using the built-in DNS update mechanism.

1442

.PP

1443

The built-in version of the DNS update mechanism is in a text

1444

string towards the top of server/dhcpd.c. If you want to use events

1445

for things other than DNS updates, and you also want DNS updates, you

1446

will have to start out by copying this code into your dhcpd.conf file

1447

and modifying it.

1448

.SH REFERENCE: DECLARATIONS

1449

.PP

1450

.B The

1451

.I include

1452

.B statement

1453

.PP

1454

.nf

1455

\fBinclude\fR \fI"filename"\fR\fB;\fR

1456

.fi

1457

.PP

1458

The \fIinclude\fR statement is used to read in a named file, and process

1459

the contents of that file as though it were entered in place of the

1460

include statement.

1461

.PP

1462

.B The

1463

.I shared-network

1464

.B statement

1465

.PP

1466

.nf

1467

\fBshared-network\fR \fIname\fR \fB{\fR

1468

[ \fIparameters\fR ]

1469

[ \fIdeclarations\fR ]

1470

\fB}\fR

1471

.fi

1472

.PP

1473

The \fIshared-network\fR statement is used to inform the DHCP server

1474

that some IP subnets actually share the same physical network. Any

1475

subnets in a shared network should be declared within a

1476

\fIshared-network\fR statement. Parameters specified in the

1477

\fIshared-network\fR statement will be used when booting clients on

1478

those subnets unless parameters provided at the subnet or host level

1479

override them. If any subnet in a shared network has addresses

1480

available for dynamic allocation, those addresses are collected into a

1481

common pool for that shared network and assigned to clients as needed.

1482

There is no way to distinguish on which subnet of a shared network a

1483

client should boot.

1484

.PP

1485

.I Name

1486

should be the name of the shared network. This name is used when

1487

printing debugging messages, so it should be descriptive for the

1488

shared network. The name may have the syntax of a valid domain name

1489

(although it will never be used as such), or it may be any arbitrary

1490

name, enclosed in quotes.

1491

.PP

1492

.B The

1493

.I subnet

1494

.B statement

1495

.PP

1496

.nf

1497

\fBsubnet\fR \fIsubnet-number\fR \fBnetmask\fR \fInetmask\fR \fB{\fR

1498

[ \fIparameters\fR ]

1499

[ \fIdeclarations\fR ]

1500

\fB}\fR

1501

.fi

1502

.PP

1503

The \fIsubnet\fR statement is used to provide dhcpd with enough

1504

information to tell whether or not an IP address is on that subnet.

1505

It may also be used to provide subnet-specific parameters and to

1506

specify what addresses may be dynamically allocated to clients booting

1507

on that subnet. Such addresses are specified using the \fIrange\fR

1508

declaration.

1509

.PP

1510

The

1511

.I subnet-number

1512

should be an IP address or domain name which resolves to the subnet

1513

number of the subnet being described. The

1514

.I netmask

1515

should be an IP address or domain name which resolves to the subnet mask

1516

of the subnet being described. The subnet number, together with the

1517

netmask, are sufficient to determine whether any given IP address is

1518

on the specified subnet.

1519

.PP

1520

Although a netmask must be given with every subnet declaration, it is

1521

recommended that if there is any variance in subnet masks at a site, a

1522

subnet-mask option statement be used in each subnet declaration to set

1523

the desired subnet mask, since any subnet-mask option statement will

1524

override the subnet mask declared in the subnet statement.

1525

.PP

1526

.B The

1527

.I subnet6

1528

.B statement

1529

.PP

1530

.nf

1531

\fBsubnet6\fR \fIsubnet6-number\fR \fB{\fR

1532

[ \fIparameters\fR ]

1533

[ \fIdeclarations\fR ]

1534

\fB}\fR

1535

.fi

1536

.PP

1537

The \fIsubnet6\fR statement is used to provide dhcpd with enough

1538

information to tell whether or not an IPv6 address is on that subnet6.

1539

It may also be used to provide subnet-specific parameters and to

1540

specify what addresses may be dynamically allocated to clients booting

1541

on that subnet.

1542

.PP

1543

The

1544

.I subnet6-number

1545

should be an IPv6 network identifier, specified as ip6-address/bits.

1546

.PP

1547

.B The

1548

.I range

1549

.B statement

1550

.PP

1551

.nf

1552

.B range\fR [ \fBdynamic-bootp\fR ] \fIlow-address\fR [ \fIhigh-address\fR]\fB;\fR

1553

.fi

1554

.PP

1555

For any subnet on which addresses will be assigned dynamically, there

1556

must be at least one \fIrange\fR statement. The range statement

1557

gives the lowest and highest IP addresses in a range. All IP

1558

addresses in the range should be in the subnet in which the

1559

\fIrange\fR statement is declared. The \fIdynamic-bootp\fR flag may

1560

be specified if addresses in the specified range may be dynamically

1561

assigned to BOOTP clients as well as DHCP clients. When specifying a

1562

single address, \fIhigh-address\fR can be omitted.

1563

.PP

1564

.B The

1565

.I range6

1566

.B statement

1567

.PP

1568

.nf

1569

.B range6\fR \fIlow-address\fR \fIhigh-address\fR\fB;\fR

1570

.B range6\fR \fIsubnet6-number\fR\fB;\fR

1571

.B range6\fR \fIsubnet6-number\fR \fBtemporary\fR\fB;\fR

1572

.B range6\fR \fIaddress\fR \fBtemporary\fR\fB;\fR

1573

.fi

1574

.PP

1575

For any IPv6 subnet6 on which addresses will be assigned dynamically, there

1576

must be at least one \fIrange6\fR statement. The \fIrange6\fR statement

1577

can either be the lowest and highest IPv6 addresses in a \fIrange6\fR, or

1578

use CIDR notation, specified as ip6-address/bits. All IP addresses

1579

in the \fIrange6\fR should be in the subnet6 in which the

1580

\fIrange6\fR statement is declared.

1581

.PP

1582

The \fItemporary\fR variant makes the prefix (by default on 64 bits) available

1583

for temporary (RFC 4941) addresses. A new address per prefix in the shared

1584

network is computed at each request with an IA_TA option. Release and Confirm

1585

ignores temporary addresses.

1586

.PP

1587

Any IPv6 addresses given to hosts with \fIfixed-address6\fR are excluded

1588

from the \fIrange6\fR, as are IPv6 addresses on the server itself.

1589

.PP

1590

.PP

1591

.B The

1592

.I prefix6

1593

.B statement

1594

.PP

1595

.nf

1596

.B prefix6\fR \fIlow-address\fR \fIhigh-address\fR \fB/\fR \fIbits\fR\fB;\fR

1597

.fi

1598

.PP

1599

The \fIprefix6\fR is the \fIrange6\fR equivalent for Prefix Delegation

1600

(RFC 3633). Prefixes of \fIbits\fR length are assigned between

1601

\fIlow-address\fR and \fIhigh-address\fR.

1602

.PP

1603

Any IPv6 prefixes given to static entries (hosts) with \fIfixed-prefix6\fR

1604

are excluded from the \fIprefix6\fR.

1605

.PP

1606

This statement is currently global but it should have a shared-network scope.

1607

.PP

1608

.B The

1609

.I host

1610

.B statement

1611

.PP

1612

.nf

1613

\fBhost\fR \fIhostname\fR {

1614

[ \fIparameters\fR ]

1615

[ \fIdeclarations\fR ]

1616

\fB}\fR

1617

.fi

1618

.PP

1619

The

1620

.B host

1621

declaration provides a scope in which to provide configuration information about

1622

a specific client, and also provides a way to assign a client a fixed address.

1623

The host declaration provides a way for the DHCP server to identify a DHCP or

1624

BOOTP client, and also a way to assign the client a static IP address.

1625

.PP

1626

If it is desirable to be able to boot a DHCP or BOOTP client on more than one

1627

subnet with fixed addresses, more than one address may be specified in the

1628

.I fixed-address

1629

declaration, or more than one

1630

.B host

1631

statement may be specified matching the same client.

1632

.PP

1633

If client-specific boot parameters must change based on the network

1634

to which the client is attached, then multiple

1635

.B host

1636

declarations should be used. The

1637

.B host

1638

declarations will only match a client if one of their

1639

.I fixed-address

1640

statements is viable on the subnet (or shared network) where the client is

1641

attached. Conversely, for a

1642

.B host

1643

declaration to match a client being allocated a dynamic address, it must not

1644

have any

1645

.I fixed-address

1646

statements. You may therefore need a mixture of

1647

.B host

1648

declarations for any given client...some having

1649

.I fixed-address

1650

statements, others without.

1651

.PP

1652

.I hostname

1653

should be a name identifying the host. If a \fIhostname\fR option is

1654

not specified for the host, \fIhostname\fR is used.

1655

.PP

1656

\fIHost\fR declarations are matched to actual DHCP or BOOTP clients

1657

by matching the \fRdhcp-client-identifier\fR option specified in the

1658

\fIhost\fR declaration to the one supplied by the client, or, if the

1659

\fIhost\fR declaration or the client does not provide a

1660

\fRdhcp-client-identifier\fR option, by matching the \fIhardware\fR

1661

parameter in the \fIhost\fR declaration to the network hardware

1662

address supplied by the client. BOOTP clients do not normally

1663

provide a \fIdhcp-client-identifier\fR, so the hardware address must

1664

be used for all clients that may boot using the BOOTP protocol.

1665

.PP

1666

DHCPv6 servers can use the \fIhost-identifier option\fR parameter in

1667

the \fIhost\fR declaration, and specify any option with a fixed value

1668

to identify hosts.

1669

.PP

1670

Please be aware that

1671

.B only

1672

the \fIdhcp-client-identifier\fR option and the hardware address can be

1673

used to match a host declaration, or the \fIhost-identifier option\fR

1674

parameter for DHCPv6 servers. For example, it is not possible to

1675

match a host declaration to a \fIhost-name\fR option. This is

1676

because the host-name option cannot be guaranteed to be unique for any

1677

given client, whereas both the hardware address and

1678

\fIdhcp-client-identifier\fR option are at least theoretically

1679

guaranteed to be unique to a given client.

1680

.PP

1681

.B The

1682

.I group

1683

.B statement

1684

.PP

1685

.nf

1686

\fBgroup\fR {

1687

[ \fIparameters\fR ]

1688

[ \fIdeclarations\fR ]

1689

\fB}\fR

1690

.fi

1691

.PP

1692

The group statement is used simply to apply one or more parameters to

1693

a group of declarations. It can be used to group hosts, shared

1694

networks, subnets, or even other groups.

1695

.SH REFERENCE: ALLOW AND DENY

1696

The

1697

.I allow

1698

and

1699

.I deny

1700

statements can be used to control the response of the DHCP server to

1701

various sorts of requests. The allow and deny keywords actually have

1702

different meanings depending on the context. In a pool context, these

1703

keywords can be used to set up access lists for address allocation

1704

pools. In other contexts, the keywords simply control general server

1705

behavior with respect to clients based on scope. In a non-pool

1706

context, the

1707

.I ignore

1708

keyword can be used in place of the

1709

.I deny

1710

keyword to prevent logging of denied requests.

1711

.PP

1712

.SH ALLOW DENY AND IGNORE IN SCOPE

1713

The following usages of allow and deny will work in any scope,

1714

although it is not recommended that they be used in pool

1715

declarations.

1716

.PP

1717

.B The

1718

.I unknown-clients

1719

.B keyword

1720

.PP

1721

\fBallow unknown-clients;\fR

1722

\fBdeny unknown-clients;\fR

1723

\fBignore unknown-clients;\fR

1724

.PP

1725

The \fBunknown-clients\fR flag is used to tell dhcpd whether

1726

or not to dynamically assign addresses to unknown clients. Dynamic

1727

address assignment to unknown clients is \fBallow\fRed by default.

1728

An unknown client is simply a client that has no host declaration.

1729

.PP

1730

The use of this option is now \fIdeprecated\fR. If you are trying to

1731

restrict access on your network to known clients, you should use \fBdeny

1732

unknown-clients;\fR inside of your address pool, as described under the

1733

heading ALLOW AND DENY WITHIN POOL DECLARATIONS.

1734

.PP

1735

.B The

1736

.I bootp

1737

.B keyword

1738

.PP

1739

\fBallow bootp;\fR

1740

\fBdeny bootp;\fR

1741

\fBignore bootp;\fR

1742

.PP

1743

The \fBbootp\fR flag is used to tell dhcpd whether

1744

or not to respond to bootp queries. Bootp queries are \fBallow\fRed

1745

by default.

1746

.PP

1747

.B The

1748

.I booting

1749

.B keyword

1750

.PP

1751

\fBallow booting;\fR

1752

\fBdeny booting;\fR

1753

\fBignore booting;\fR

1754

.PP

1755

The \fBbooting\fR flag is used to tell dhcpd whether or not to respond

1756

to queries from a particular client. This keyword only has meaning

1757

when it appears in a host declaration. By default, booting is

1758

\fBallow\fRed, but if it is disabled for a particular client, then

1759

that client will not be able to get an address from the DHCP server.

1760

.PP

1761

.B The

1762

.I duplicates

1763

.B keyword

1764

.PP

1765

\fBallow duplicates;\fR

1766

\fBdeny duplicates;\fR

1767

.PP

1768

Host declarations can match client messages based on the DHCP Client

1769

Identifier option or based on the client's network hardware type and

1770

MAC address. If the MAC address is used, the host declaration will

1771

match any client with that MAC address - even clients with different

1772

client identifiers. This doesn't normally happen, but is possible

1773

when one computer has more than one operating system installed on it -

1774

for example, Microsoft Windows and NetBSD or Linux.

1775

.PP

1776

The \fBduplicates\fR flag tells the DHCP server that if a request is

1777

received from a client that matches the MAC address of a host

1778

declaration, any other leases matching that MAC address should be

1779

discarded by the server, even if the UID is not the same. This is a

1780

violation of the DHCP protocol, but can prevent clients whose client

1781

identifiers change regularly from holding many leases at the same time.

1782

By default, duplicates are \fBallow\fRed.

1783

.PP

1784

.B The

1785

.I declines

1786

.B keyword

1787

.PP

1788

\fBallow declines;\fR

1789

\fBdeny declines;\fR

1790

\fBignore declines;\fR

1791

.PP

1792

The DHCPDECLINE message is used by DHCP clients to indicate that the

1793

lease the server has offered is not valid. When the server receives

1794

a DHCPDECLINE for a particular address, it normally abandons that

1795

address, assuming that some unauthorized system is using it.

1796

Unfortunately, a malicious or buggy client can, using DHCPDECLINE

1797

messages, completely exhaust the DHCP server's allocation pool. The

1798

server will reclaim these leases, but while the client is running

1799

through the pool, it may cause serious thrashing in the DNS, and it

1800

will also cause the DHCP server to forget old DHCP client address

1801

allocations.

1802

.PP

1803

The \fBdeclines\fR flag tells the DHCP server whether or not to honor

1804

DHCPDECLINE messages. If it is set to \fBdeny\fR or \fBignore\fR in

1805

a particular scope, the DHCP server will not respond to DHCPDECLINE

1806

messages.

1807

.PP

1808

.B The

1809

.I client-updates

1810

.B keyword

1811

.PP

1812

\fBallow client-updates;\fR

1813

\fBdeny client-updates;\fR

1814

.PP

1815

The \fBclient-updates\fR flag tells the DHCP server whether or not to

1816

honor the client's intention to do its own update of its A record.

1817

This is only relevant when doing \fIinterim\fR DNS updates. See the

1818

documentation under the heading THE INTERIM DNS UPDATE SCHEME for

1819

details.

1820

.PP

1821

.B The

1822

.I leasequery

1823

.B keyword

1824

.PP

1825

\fBallow leasequery;\fR

1826

\fBdeny leasequery;\fR

1827

.PP

1828

The \fBleasequery\fR flag tells the DHCP server whether or not to

1829

answer DHCPLEASEQUERY packets. The answer to a DHCPLEASEQUERY packet

1830

includes information about a specific lease, such as when it was

1831

issued and when it will expire. By default, the server will not

1832

respond to these packets.

1833

.SH ALLOW AND DENY WITHIN POOL DECLARATIONS

1834

.PP

1835

The uses of the allow and deny keywords shown in the previous section

1836

work pretty much the same way whether the client is sending a

1837

DHCPDISCOVER or a DHCPREQUEST message - an address will be allocated

1838

to the client (either the old address it's requesting, or a new

1839

address) and then that address will be tested to see if it's okay to

1840

let the client have it. If the client requested it, and it's not

1841

okay, the server will send a DHCPNAK message. Otherwise, the server

1842

will simply not respond to the client. If it is okay to give the

1843

address to the client, the server will send a DHCPACK message.

1844

.PP

1845

The primary motivation behind pool declarations is to have address

1846

allocation pools whose allocation policies are different. A client

1847

may be denied access to one pool, but allowed access to another pool

1848

on the same network segment. In order for this to work, access

1849

control has to be done during address allocation, not after address

1850

allocation is done.

1851

.PP

1852

When a DHCPREQUEST message is processed, address allocation simply

1853

consists of looking up the address the client is requesting and seeing

1854

if it's still available for the client. If it is, then the DHCP

1855

server checks both the address pool permit lists and the relevant

1856

in-scope allow and deny statements to see if it's okay to give the

1857

lease to the client. In the case of a DHCPDISCOVER message, the

1858

allocation process is done as described previously in the ADDRESS

1859

ALLOCATION section.

1860

.PP

1861

When declaring permit lists for address allocation pools, the

1862

following syntaxes are recognized following the allow or deny keywords:

1863

.PP

1864

\fBknown-clients;\fR

1865

.PP

1866

If specified, this statement either allows or prevents allocation from

1867

this pool to any client that has a host declaration (i.e., is known).

1868

A client is known if it has a host declaration in \fIany\fR scope, not

1869

just the current scope.

1870

.PP

1871

\fBunknown-clients;\fR

1872

.PP

1873

If specified, this statement either allows or prevents allocation from

1874

this pool to any client that has no host declaration (i.e., is not

1875

known).

1876

.PP

1877

\fBmembers of "\fRclass\fB";\fR

1878

.PP

1879

If specified, this statement either allows or prevents allocation from

1880

this pool to any client that is a member of the named class.

1881

.PP

1882

\fBdynamic bootp clients;\fR

1883

.PP

1884

If specified, this statement either allows or prevents allocation from

1885

this pool to any bootp client.

1886

.PP

1887

\fBauthenticated clients;\fR

1888

.PP

1889

If specified, this statement either allows or prevents allocation from

1890

this pool to any client that has been authenticated using the DHCP

1891

authentication protocol. This is not yet supported.

1892

.PP

1893

\fBunauthenticated clients;\fR

1894

.PP

1895

If specified, this statement either allows or prevents allocation from

1896

this pool to any client that has not been authenticated using the DHCP

1897

authentication protocol. This is not yet supported.

1898

.PP

1899

\fBall clients;\fR

1900

.PP

1901

If specified, this statement either allows or prevents allocation from

1902

this pool to all clients. This can be used when you want to write a

1903

pool declaration for some reason, but hold it in reserve, or when you

1904

want to renumber your network quickly, and thus want the server to

1905

force all clients that have been allocated addresses from this pool to

1906

obtain new addresses immediately when they next renew.

1907

.PP

1908

\fBafter \fItime\fR\fB;\fR

1909

.PP

1910

If specified, this statement either allows or prevents allocation from

1911

this pool after a given date. This can be used when you want to move

1912

clients from one pool to another. The server adjusts the regular lease

1913

time so that the latest expiry time is at the given time+min-lease-time.

1914

A short min-lease-time enforces a step change, whereas a longer

1915

min-lease-time allows for a gradual change.

1916

\fItime\fR is either second since epoch, or a UTC time string e.g.

1917

4 2007/08/24 09:14:32 or a string with time zone offset in seconds

1918

e.g. 4 2007/08/24 11:14:32 -7200

1919

.SH REFERENCE: PARAMETERS

1920

The

1921

.I adaptive-lease-time-threshold

1922

statement

1923

.RS 0.25i

1924

.PP

1925

.B adaptive-lease-time-threshold \fIpercentage\fR\fB;\fR

1926

.PP

1927

When the number of allocated leases within a pool rises above

1928

the \fIpercentage\fR given in this statement, the DHCP server decreases

1929

the lease length for new clients within this pool to \fImin-lease-time\fR

1930

seconds. Clients renewing an already valid (long) leases get at least the

1931

remaining time from the current lease. Since the leases expire faster,

1932

the server may either recover more quickly or avoid pool exhaustion

1933

entirely. Once the number of allocated leases drop below the threshold,

1934

the server reverts back to normal lease times. Valid percentages are

1935

between 1 and 99.

1936

.RE

1937

.PP

1938

The

1939

.I always-broadcast

1940

statement

1941

.RS 0.25i

1942

.PP

1943

.B always-broadcast \fIflag\fR\fB;\fR

1944

.PP

1945

The DHCP and BOOTP protocols both require DHCP and BOOTP clients to

1946

set the broadcast bit in the flags field of the BOOTP message header.

1947

Unfortunately, some DHCP and BOOTP clients do not do this, and

1948

therefore may not receive responses from the DHCP server. The DHCP

1949

server can be made to always broadcast its responses to clients by

1950

setting this flag to \'on\' for the relevant scope; relevant scopes would be

1951

inside a conditional statement, as a parameter for a class, or as a parameter

1952

for a host declaration. To avoid creating excess broadcast traffic on your

1953

network, we recommend that you restrict the use of this option to as few

1954

clients as possible. For example, the Microsoft DHCP client is known not

1955

to have this problem, as are the OpenTransport and ISC DHCP clients.

1956

.RE

1957

.PP

1958

The

1959

.I always-reply-rfc1048

1960

statement

1961

.RS 0.25i

1962

.PP

1963

.B always-reply-rfc1048 \fIflag\fR\fB;\fR

1964

.PP

1965

Some BOOTP clients expect RFC1048-style responses, but do not follow

1966

RFC1048 when sending their requests. You can tell that a client is

1967

having this problem if it is not getting the options you have

1968

configured for it and if you see in the server log the message

1969

"(non-rfc1048)" printed with each BOOTREQUEST that is logged.

1970

.PP

1971

If you want to send rfc1048 options to such a client, you can set the

1972

.B always-reply-rfc1048

1973

option in that client's host declaration, and the DHCP server will

1974

respond with an RFC-1048-style vendor options field. This flag can

1975

be set in any scope, and will affect all clients covered by that

1976

scope.

1977

.RE

1978

.PP

1979

The

1980

.I authoritative

1981

statement

1982

.RS 0.25i

1983

.PP

1984

.B authoritative;

1985

.PP

1986

.B not authoritative;

1987

.PP

1988

The DHCP server will normally assume that the configuration

1989

information about a given network segment is not known to be correct

1990

and is not authoritative. This is so that if a naive user installs a

1991

DHCP server not fully understanding how to configure it, it does not

1992

send spurious DHCPNAK messages to clients that have obtained addresses

1993

from a legitimate DHCP server on the network.

1994

.PP

1995

Network administrators setting up authoritative DHCP servers for their

1996

networks should always write \fBauthoritative;\fR at the top of their

1997

configuration file to indicate that the DHCP server \fIshould\fR send

1998

DHCPNAK messages to misconfigured clients. If this is not done,

1999

clients will be unable to get a correct IP address after changing

2000

subnets until their old lease has expired, which could take quite a

2001

long time.

2002

.PP

2003

Usually, writing \fBauthoritative;\fR at the top level of the file

2004

should be sufficient. However, if a DHCP server is to be set up so

2005

that it is aware of some networks for which it is authoritative and

2006

some networks for which it is not, it may be more appropriate to

2007

declare authority on a per-network-segment basis.

2008

.PP

2009

Note that the most specific scope for which the concept of authority

2010

makes any sense is the physical network segment - either a

2011

shared-network statement or a subnet statement that is not contained

2012

within a shared-network statement. It is not meaningful to specify

2013

that the server is authoritative for some subnets within a shared

2014

network, but not authoritative for others, nor is it meaningful to

2015

specify that the server is authoritative for some host declarations

2016

and not others.

2017

.RE

2018

.PP

2019

The \fIboot-unknown-clients\fR statement

2020

.RS 0.25i

2021

.PP

2022

.B boot-unknown-clients \fIflag\fB;\fR

2023

.PP

2024

If the \fIboot-unknown-clients\fR statement is present and has a value

2025

of \fIfalse\fR or \fIoff\fR, then clients for which there is no

2026

.I host

2027

declaration will not be allowed to obtain IP addresses. If this

2028

statement is not present or has a value of \fItrue\fR or \fIon\fR,

2029

then clients without host declarations will be allowed to obtain IP

2030

addresses, as long as those addresses are not restricted by

2031

.I allow

2032

and \fIdeny\fR statements within their \fIpool\fR declarations.

2033

.RE

2034

.PP

2035

The \fIdb-time-format\fR statement

2036

.RS 0.25i

2037

.PP

2038

.B db-time-format \fR[ \fIdefault\fR | \fIlocal\fR ] \fB;\fR

2039

.PP

2040

The DHCP server software outputs several timestamps when writing leases to

2041

persistent storage. This configuration parameter selects one of two output

2042

formats. The \fIdefault\fR format prints the day, date, and time in UTC,

2043

while the \fIlocal\fR format prints the system seconds-since-epoch, and

2044

helpfully provides the day and time in the system timezone in a comment.

2045

The time formats are described in detail in the dhcpd.leases(5) manpage.

2046

.RE

2047

.PP

2048

The \fIddns-hostname\fR statement

2049

.RS 0.25i

2050

.PP

2051

.B ddns-hostname \fIname\fB;\fR

2052

.PP

2053

The \fIname\fR parameter should be the hostname that will be used in

2054

setting up the client's A and PTR records. If no ddns-hostname is

2055

specified in scope, then the server will derive the hostname

2056

automatically, using an algorithm that varies for each of the

2057

different update methods.

2058

.RE

2059

.PP

2060

The \fIddns-domainname\fR statement

2061

.RS 0.25i

2062

.PP

2063

.B ddns-domainname \fIname\fB;\fR

2064

.PP

2065

The \fIname\fR parameter should be the domain name that will be

2066

appended to the client's hostname to form a fully-qualified

2067

domain-name (FQDN).

2068

.RE

2069

.PP

2070

The \fIddns-rev-domainname\fR statement

2071

.RS 0.25i

2072

.PP

2073

.B ddns-rev-domainname \fIname\fB;\fR

2074

The \fIname\fR parameter should be the domain name that will be

2075

appended to the client's reversed IP address to produce a name for use

2076

in the client's PTR record. By default, this is "in-addr.arpa.", but

2077

the default can be overridden here.

2078

.PP

2079

The reversed IP address to which this domain name is appended is

2080

always the IP address of the client, in dotted quad notation, reversed

2081

- for example, if the IP address assigned to the client is

2082

10.17.92.74, then the reversed IP address is 74.92.17.10. So a

2083

client with that IP address would, by default, be given a PTR record

2084

of 10.17.92.74.in-addr.arpa.

2085

.RE

2086

.PP

2087

The \fIddns-update-style\fR parameter

2088

.RS 0.25i

2089

.PP

2090

.B ddns-update-style \fIstyle\fB;\fR

2091

.PP

2092

The

2093

.I style

2094

parameter must be one of \fBad-hoc\fR, \fBinterim\fR or \fBnone\fR.

2095

The \fIddns-update-style\fR statement is only meaningful in the outer

2096

scope - it is evaluated once after reading the dhcpd.conf file, rather

2097

than each time a client is assigned an IP address, so there is no way

2098

to use different DNS update styles for different clients. The default

2099

is \fBnone\fR.

2100

.RE

2101

.PP

2102

.B The

2103

.I ddns-updates

2104

.B statement

2105

.RS 0.25i

2106

.PP

2107

\fBddns-updates \fIflag\fR\fB;\fR

2108

.PP

2109

The \fIddns-updates\fR parameter controls whether or not the server will

2110

attempt to do a DNS update when a lease is confirmed. Set this to \fIoff\fR

2111

if the server should not attempt to do updates within a certain scope.

2112

The \fIddns-updates\fR parameter is on by default. To disable DNS

2113

updates in all scopes, it is preferable to use the

2114

\fIddns-update-style\fR statement, setting the style to \fInone\fR.

2115

.RE

2116

.PP

2117

The

2118

.I default-lease-time

2119

statement

2120

.RS 0.25i

2121

.PP

2122

.B default-lease-time \fItime\fR\fB;\fR

2123

.PP

2124

.I Time

2125

should be the length in seconds that will be assigned to a lease if

2126

the client requesting the lease does not ask for a specific expiration

2127

time. This is used for both DHCPv4 and DHCPv6 leases (it is also known

2128

as the "valid lifetime" in DHCPv6).

2129

The default is 43200 seconds.

2130

.RE

2131

.PP

2132

The

2133

.I delayed-ack

2134

and

2135

.I max-ack-delay

2136

statements

2137

.RS 0.25i

2138

.PP

2139

.B delayed-ack \fIcount\fR\fB;\fR

2140

.B max-ack-delay \fImicroseconds\fR\fB;\fR

2141

.PP

2142

.I Count

2143

should be an integer value from zero to 2^16-1, and defaults to 28. The

2144

count represents how many DHCPv4 replies maximum will be queued pending

2145

transmission until after a database commit event. If this number is

2146

reached, a database commit event (commonly resulting in fsync() and

2147

representing a performance penalty) will be made, and the reply packets

2148

will be transmitted in a batch afterwards. This preserves the RFC2131

2149

direction that "stable storage" be updated prior to replying to clients.

2150

Should the DHCPv4 sockets "go dry" (select() returns immediately with no

2151

read sockets), the commit is made and any queued packets are transmitted.

2152

.PP

2153

Similarly, \fImicroseconds\fR indicates how many microseconds are permitted

2154

to pass inbetween queuing a packet pending an fsync, and performing the

2155

fsync. Valid values range from 0 to 2^32-1, and defaults to 250,000 (1/4 of

2156

a second).

2157

.PP

2158

Please note that as delayed-ack is currently experimental, the delayed-ack

2159

feature is not compiled in by default, but must be enabled at compile time

2160

with \'./configure --enable-delayed-ack\'.

2161

.RE

2162

.PP

2163

The

2164

.I do-forward-updates

2165

statement

2166

.RS 0.25i

2167

.PP

2168

.B do-forward-updates \fIflag\fB;\fR

2169

.PP

2170

The \fIdo-forward-updates\fR statement instructs the DHCP server as

2171

to whether it should attempt to update a DHCP client's A record

2172

when the client acquires or renews a lease. This statement has no

2173

effect unless DNS updates are enabled and \fBddns-update-style\fR is

2174

set to \fBinterim\fR. Forward updates are enabled by default. If

2175

this statement is used to disable forward updates, the DHCP server

2176

will never attempt to update the client's A record, and will only ever

2177

attempt to update the client's PTR record if the client supplies an

2178

FQDN that should be placed in the PTR record using the fqdn option.

2179

If forward updates are enabled, the DHCP server will still honor the

2180

setting of the \fBclient-updates\fR flag.

2181

.RE

2182

.PP

2183

The

2184

.I dynamic-bootp-lease-cutoff

2185

statement

2186

.RS 0.25i

2187

.PP

2188

.B dynamic-bootp-lease-cutoff \fIdate\fB;\fR

2189

.PP

2190

The \fIdynamic-bootp-lease-cutoff\fR statement sets the ending time

2191

for all leases assigned dynamically to BOOTP clients. Because BOOTP

2192

clients do not have any way of renewing leases, and don't know that

2193

their leases could expire, by default dhcpd assigns infinite leases

2194

to all BOOTP clients. However, it may make sense in some situations

2195

to set a cutoff date for all BOOTP leases - for example, the end of a

2196

school term, or the time at night when a facility is closed and all

2197

machines are required to be powered off.

2198

.PP

2199

.I Date

2200

should be the date on which all assigned BOOTP leases will end. The

2201

date is specified in the form:

2202

.PP

2203

.ce 1

2204

W YYYY/MM/DD HH:MM:SS

2205

.PP

2206

W is the day of the week expressed as a number

2207

from zero (Sunday) to six (Saturday). YYYY is the year, including the

2208

century. MM is the month expressed as a number from 1 to 12. DD is

2209

the day of the month, counting from 1. HH is the hour, from zero to

2210

23. MM is the minute and SS is the second. The time is always in

2211

Coordinated Universal Time (UTC), not local time.

2212

.RE

2213

.PP

2214

The

2215

.I dynamic-bootp-lease-length

2216

statement

2217

.RS 0.25i

2218

.PP

2219

.B dynamic-bootp-lease-length\fR \fIlength\fR\fB;\fR

2220

.PP

2221

The \fIdynamic-bootp-lease-length\fR statement is used to set the

2222

length of leases dynamically assigned to BOOTP clients. At some

2223

sites, it may be possible to assume that a lease is no longer in

2224

use if its holder has not used BOOTP or DHCP to get its address within

2225

a certain time period. The period is specified in \fIlength\fR as a

2226

number of seconds. If a client reboots using BOOTP during the

2227

timeout period, the lease duration is reset to \fIlength\fR, so a

2228

BOOTP client that boots frequently enough will never lose its lease.

2229

Needless to say, this parameter should be adjusted with extreme

2230

caution.

2231

.RE

2232

.PP

2233

The

2234

.I filename

2235

statement

2236

.RS 0.25i

2237

.PP

2238

.B filename\fR \fB"\fR\fIfilename\fR\fB";\fR

2239

.PP

2240

The \fIfilename\fR statement can be used to specify the name of the

2241

initial boot file which is to be loaded by a client. The

2242

.I filename

2243

should be a filename recognizable to whatever file transfer protocol

2244

the client can be expected to use to load the file.

2245

.RE

2246

.PP

2247

The

2248

.I fixed-address

2249

declaration

2250

.RS 0.25i

2251

.PP

2252

.B fixed-address address\fR [\fB,\fR \fIaddress\fR ... ]\fB;\fR

2253

.PP

2254

The \fIfixed-address\fR declaration is used to assign one or more fixed

2255

IP addresses to a client. It should only appear in a \fIhost\fR

2256

declaration. If more than one address is supplied, then when the

2257

client boots, it will be assigned the address that corresponds to the

2258

network on which it is booting. If none of the addresses in the

2259

\fIfixed-address\fR statement are valid for the network to which the client

2260

is connected, that client will not match the \fIhost\fR declaration

2261

containing that \fIfixed-address\fR declaration. Each \fIaddress\fR

2262

in the \fIfixed-address\fR declaration should be either an IP address or

2263

a domain name that resolves to one or more IP addresses.

2264

.RE

2265

.PP

2266

The

2267

.I fixed-address6

2268

declaration

2269

.RS 0.25i

2270

.PP

2271

.B fixed-address6 ip6-address\fR ;\fR

2272

.PP

2273

The \fIfixed-address6\fR declaration is used to assign a fixed

2274

IPv6 addresses to a client. It should only appear in a \fIhost\fR

2275

declaration.

2276

.RE

2277

.PP

2278

The

2279

.I get-lease-hostnames

2280

statement

2281

.RS 0.25i

2282

.PP

2283

.B get-lease-hostnames\fR \fIflag\fR\fB;\fR

2284

.PP

2285

The \fIget-lease-hostnames\fR statement is used to tell dhcpd whether

2286

or not to look up the domain name corresponding to the IP address of

2287

each address in the lease pool and use that address for the DHCP

2288

\fIhostname\fR option. If \fIflag\fR is true, then this lookup is

2289

done for all addresses in the current scope. By default, or if

2290

\fIflag\fR is false, no lookups are done.

2291

.RE

2292

.PP

2293

The

2294

.I hardware

2295

statement

2296

.RS 0.25i

2297

.PP

2298

.B hardware \fIhardware-type hardware-address\fB;\fR

2299

.PP

2300

In order for a BOOTP client to be recognized, its network hardware

2301

address must be declared using a \fIhardware\fR clause in the

2302

.I host

2303

statement.

2304

.I hardware-type

2305

must be the name of a physical hardware interface type. Currently,

2306

only the

2307

.B ethernet

2308

and

2309

.B token-ring

2310

types are recognized, although support for a

2311

.B fddi

2312

hardware type (and others) would also be desirable.

2313

The

2314

.I hardware-address

2315

should be a set of hexadecimal octets (numbers from 0 through ff)

2316

separated by colons. The \fIhardware\fR statement may also be used

2317

for DHCP clients.

2318

.RE

2319

.PP

2320

The

2321

.I host-identifier option

2322

statement

2323

.RS 0.25i

2324

.PP

2325

.B host-identifier option \fIoption-name option-data\fB;\fR

2326

.PP

2327

This identifies a DHCPv6 client in a

2328

.I host

2329

statement.

2330

.I option-name

2331

is any option, and

2332

.I option-data

2333

is the value for the option that the client will send. The

2334

.I option-data

2335

must be a constant value.

2336

.RE

2337

.PP

2338

The

2339

.I infinite-is-reserved

2340

statement

2341

.RS 0.25i

2342

.PP

2343

.B infinite-is-reserved \fIflag\fB;\fR

2344

.PP

2345

ISC DHCP now supports \'reserved\' leases. See the section on RESERVED LEASES

2346

below. If this \fIflag\fR is on, the server will automatically reserve leases

2347

allocated to clients which requested an infinite (0xffffffff) lease-time.

2348

.PP

2349

The default is off.

2350

.RE

2351

.PP

2352

The

2353

.I lease-file-name

2354

statement

2355

.RS 0.25i

2356

.PP

2357

.B lease-file-name \fIname\fB;\fR

2358

.PP

2359

.I Name

2360

should be the name of the DHCP server's lease file. By default, this

2361

is DBDIR/dhcpd.leases. This statement \fBmust\fR appear in the outer

2362

scope of the configuration file - if it appears in some other scope,

2363

it will have no effect. Furthermore, it has no effect if overridden

2364

by the

2365

.B -lf

2366

flag or the

2367

.B PATH_DHCPD_DB

2368

environment variable.

2369

.RE

2370

.PP

2371

The

2372

.I limit-addrs-per-ia

2373

statement

2374

.RS 0.25i

2375

.PP

2376

.B limit-addrs-per-ia \fInumber\fB;\fR

2377

.PP

2378

By default, the DHCPv6 server will limit clients to one IAADDR per IA

2379

option, meaning one address. If you wish to permit clients to hang onto

2380

multiple addresses at a time, configure a larger \fInumber\fR here.

2381

.PP

2382

Note that there is no present method to configure the server to forcibly

2383

configure the client with one IP address per each subnet on a shared network.

2384

This is left to future work.

2385

.RE

2386

.PP

2387

The

2388

.I dhcpv6-lease-file-name

2389

statement

2390

.RS 0.25i

2391

.PP

2392

.B dhcpv6-lease-file-name \fIname\fB;\fR

2393

.PP

2394

.I Name

2395

is the name of the lease file to use if and only if the server is running

2396

in DHCPv6 mode. By default, this is DBDIR/dhcpd6.leases. This statement,

2397

like

2398

.I lease-file-name,

2399

\fBmust\fR appear in the outer scope of the configuration file. It

2400

has no effect if overridden by the

2401

.B -lf

2402

flag or the

2403

.B PATH_DHCPD6_DB

2404

environment variable. If

2405

.I dhcpv6-lease-file-name

2406

is not specified, but

2407

.I lease-file-name

2408

is, the latter value will be used.

2409

.RE

2410

.PP

2411

The

2412

.I local-port

2413

statement

2414

.RS 0.25i

2415

.PP

2416

.B local-port \fIport\fB;\fR

2417

.PP

2418

This statement causes the DHCP server to listen for DHCP requests on

2419

the UDP port specified in \fIport\fR, rather than on port 67.

2420

.RE

2421

.PP

2422

The

2423

.I local-address

2424

statement

2425

.RS 0.25i

2426

.PP

2427

.B local-address \fIaddress\fB;\fR

2428

.PP

2429

This statement causes the DHCP server to listen for DHCP requests sent

2430

to the specified \fIaddress\fR, rather than requests sent to all addresses.

2431

Since serving directly attached DHCP clients implies that the server must

2432

respond to requests sent to the all-ones IP address, this option cannot be

2433

used if clients are on directly attached networks...it is only realistically

2434

useful for a server whose only clients are reached via unicasts, such as via

2435

DHCP relay agents.

2436

.PP

2437

Note: This statement is only effective if the server was compiled using

2438

the USE_SOCKETS #define statement, which is default on a small number of

2439

operating systems, and must be explicitly chosen at compile-time for all

2440

others. You can be sure if your server is compiled with USE_SOCKETS if

2441

you see lines of this format at startup:

2442

.PP

2443

Listening on Socket/eth0

2444

.PP

2445

Note also that since this bind()s all DHCP sockets to the specified

2446

address, that only one address may be supported in a daemon at a given

2447

time.

2448

.RE

2449

.PP

2450

The

2451

.I log-facility

2452

statement

2453

.RS 0.25i

2454

.PP

2455

.B log-facility \fIfacility\fB;\fR

2456

.PP

2457

This statement causes the DHCP server to do all of its logging on the

2458

specified log facility once the dhcpd.conf file has been read. By

2459

default the DHCP server logs to the daemon facility. Possible log

2460

facilities include auth, authpriv, cron, daemon, ftp, kern, lpr, mail,

2461

mark, news, ntp, security, syslog, user, uucp, and local0 through

2462

local7. Not all of these facilities are available on all systems,

2463

and there may be other facilities available on other systems.

2464

.PP

2465

In addition to setting this value, you may need to modify your

2466

.I syslog.conf

2467

file to configure logging of the DHCP server. For example, you might

2468

add a line like this:

2469

.PP

2470

.nf

2471

local7.debug /var/log/dhcpd.log

2472

.fi

2473

.PP

2474

The syntax of the \fIsyslog.conf\fR file may be different on some

2475

operating systems - consult the \fIsyslog.conf\fR manual page to be

2476

sure. To get syslog to start logging to the new file, you must first

2477

create the file with correct ownership and permissions (usually, the

2478

same owner and permissions of your /var/log/messages or

2479

/usr/adm/messages file should be fine) and send a SIGHUP to syslogd.

2480

Some systems support log rollover using a shell script or program

2481

called newsyslog or logrotate, and you may be able to configure this

2482

as well so that your log file doesn't grow uncontrollably.

2483

.PP

2484

Because the \fIlog-facility\fR setting is controlled by the dhcpd.conf

2485

file, log messages printed while parsing the dhcpd.conf file or before

2486

parsing it are logged to the default log facility. To prevent this,

2487

see the README file included with this distribution, which describes

2488

how to change the default log facility. When this parameter is used,

2489

the DHCP server prints its startup message a second time after parsing

2490

the configuration file, so that the log will be as complete as

2491

possible.

2492

.RE

2493

.PP

2494

The

2495

.I max-lease-time

2496

statement

2497

.RS 0.25i

2498

.PP

2499

.B max-lease-time \fItime\fR\fB;\fR

2500

.PP

2501

.I Time

2502

should be the maximum length in seconds that will be assigned to a

2503

lease.

2504

If not defined, the default maximum lease time is 86400.

2505

The only exception to this is that Dynamic BOOTP lease

2506

lengths, which are not specified by the client, are not limited by

2507

this maximum.

2508

.RE

2509

.PP

2510

The

2511

.I min-lease-time

2512

statement

2513

.RS 0.25i

2514

.PP

2515

.B min-lease-time \fItime\fR\fB;\fR

2516

.PP

2517

.I Time

2518

should be the minimum length in seconds that will be assigned to a

2519

lease.

2520

The default is the minimum of 300 seconds or

2521

\fBmax-lease-time\fR.

2522

.RE

2523

.PP

2524

The

2525

.I min-secs

2526

statement

2527

.RS 0.25i

2528

.PP

2529

.B min-secs \fIseconds\fR\fB;\fR

2530

.PP

2531

.I Seconds

2532

should be the minimum number of seconds since a client began trying to

2533

acquire a new lease before the DHCP server will respond to its request.

2534

The number of seconds is based on what the client reports, and the maximum

2535

value that the client can report is 255 seconds. Generally, setting this

2536

to one will result in the DHCP server not responding to the client's first

2537

request, but always responding to its second request.

2538

.PP

2539

This can be used

2540

to set up a secondary DHCP server which never offers an address to a client

2541

until the primary server has been given a chance to do so. If the primary

2542

server is down, the client will bind to the secondary server, but otherwise

2543

clients should always bind to the primary. Note that this does not, by

2544

itself, permit a primary server and a secondary server to share a pool of

2545

dynamically-allocatable addresses.

2546

.RE

2547

.PP

2548

The

2549

.I next-server

2550

statement

2551

.RS 0.25i

2552

.PP

2553

.B next-server\fR \fIserver-name\fR\fB;\fR

2554

.PP

2555

The \fInext-server\fR statement is used to specify the host address of

2556

the server from which the initial boot file (specified in the

2557

\fIfilename\fR statement) is to be loaded. \fIServer-name\fR should

2558

be a numeric IP address or a domain name.

2559

.RE

2560

.PP

2561

The

2562

.I omapi-port

2563

statement

2564

.RS 0.25i

2565

.PP

2566

.B omapi-port\fR \fIport\fR\fB;\fR

2567

.PP

2568

The \fIomapi-port\fR statement causes the DHCP server to listen for

2569

OMAPI connections on the specified port. This statement is required

2570

to enable the OMAPI protocol, which is used to examine and modify the

2571

state of the DHCP server as it is running.

2572

.RE

2573

.PP

2574

The

2575

.I one-lease-per-client

2576

statement

2577

.RS 0.25i

2578

.PP

2579

.B one-lease-per-client \fIflag\fR\fB;\fR

2580

.PP

2581

If this flag is enabled, whenever a client sends a DHCPREQUEST for a

2582

particular lease, the server will automatically free any other leases

2583

the client holds. This presumes that when the client sends a

2584

DHCPREQUEST, it has forgotten any lease not mentioned in the

2585

DHCPREQUEST - i.e., the client has only a single network interface

2586

.I and

2587

it does not remember leases it's holding on networks to which it is

2588

not currently attached. Neither of these assumptions are guaranteed

2589

or provable, so we urge caution in the use of this statement.

2590

.RE

2591

.PP

2592

The

2593

.I pid-file-name

2594

statement

2595

.RS 0.25i

2596

.PP

2597

.B pid-file-name

2598

.I name\fR\fB;\fR

2599

.PP

2600

.I Name

2601

should be the name of the DHCP server's process ID file. This is the

2602

file in which the DHCP server's process ID is stored when the server

2603

starts. By default, this is RUNDIR/dhcpd.pid. Like the

2604

.I lease-file-name

2605

statement, this statement must appear in the outer scope

2606

of the configuration file. It has no effect if overridden by the

2607

.B -pf

2608

flag or the

2609

.B PATH_DHCPD_PID

2610

environment variable.

2611

.PP

2612

The

2613

.I dhcpv6-pid-file-name

2614

statement

2615

.RS 0.25i

2616

.PP

2617

.B dhcpv6-pid-file-name \fIname\fB;\fR

2618

.PP

2619

.I Name

2620

is the name of the pid file to use if and only if the server is running

2621

in DHCPv6 mode. By default, this is DBDIR/dhcpd6.pid. This statement,

2622

like

2623

.I pid-file-name,

2624

\fBmust\fR appear in the outer scope of the configuration file. It

2625

has no effect if overridden by the

2626

.B -pf

2627

flag or the

2628

.B PATH_DHCPD6_PID

2629

environment variable. If

2630

.I dhcpv6-pid-file-name

2631

is not specified, but

2632

.I pid-file-name

2633

is, the latter value will be used.

2634

.RE

2635

.PP

2636

The

2637

.I ping-check

2638

statement

2639

.RS 0.25i

2640

.PP

2641

.B ping-check

2642

.I flag\fR\fB;\fR

2643

.PP

2644

When the DHCP server is considering dynamically allocating an IP

2645

address to a client, it first sends an ICMP Echo request (a \fIping\fR)

2646

to the address being assigned. It waits for a second, and if no

2647

ICMP Echo response has been heard, it assigns the address. If a

2648

response \fIis\fR heard, the lease is abandoned, and the server does

2649

not respond to the client.

2650

.PP

2651

This \fIping check\fR introduces a default one-second delay in responding

2652

to DHCPDISCOVER messages, which can be a problem for some clients. The

2653

default delay of one second may be configured using the ping-timeout

2654

parameter. The ping-check configuration parameter can be used to control

2655

checking - if its value is false, no ping check is done.

2656

.RE

2657

.PP

2658

The

2659

.I ping-timeout

2660

statement

2661

.RS 0.25i

2662

.PP

2663

.B ping-timeout

2664

.I seconds\fR\fB;\fR

2665

.PP

2666

If the DHCP server determined it should send an ICMP echo request (a

2667

\fIping\fR) because the ping-check statement is true, ping-timeout allows

2668

you to configure how many seconds the DHCP server should wait for an

2669

ICMP Echo response to be heard, if no ICMP Echo response has been received

2670

before the timeout expires, it assigns the address. If a response \fIis\fR

2671

heard, the lease is abandoned, and the server does not respond to the client.

2672

If no value is set, ping-timeout defaults to 1 second.

2673

.RE

2674

.PP

2675

The

2676

.I preferred-lifetime

2677

statement

2678

.RS 0.25i

2679

.PP

2680

.B preferred-lifetime

2681

.I seconds\fR\fB;\fR

2682

.PP

2683

IPv6 addresses have \'valid\' and \'preferred\' lifetimes. The valid lifetime

2684

determines at what point at lease might be said to have expired, and is no

2685

longer useable. A preferred lifetime is an advisory condition to help

2686

applications move off of the address and onto currently valid addresses

2687

(should there still be any open TCP sockets or similar).

2688

.PP

2689

The preferred lifetime defaults to the renew+rebind timers, or 3/4 the

2690

default lease time if none were specified.

2691

.RE

2692

.PP

2693

The

2694

.I remote-port

2695

statement

2696

.RS 0.25i

2697

.PP

2698

.B remote-port \fIport\fB;\fR

2699

.PP

2700

This statement causes the DHCP server to transmit DHCP responses to DHCP

2701

clients upon the UDP port specified in \fIport\fR, rather than on port 68.

2702

In the event that the UDP response is transmitted to a DHCP Relay, the

2703

server generally uses the \fBlocal-port\fR configuration value. Should the

2704

DHCP Relay happen to be addressed as 127.0.0.1, however, the DHCP Server

2705

transmits its response to the \fBremote-port\fR configuration value. This

2706

is generally only useful for testing purposes, and this configuration value

2707

should generally not be used.

2708

.RE

2709

.PP

2710

The

2711

.I server-identifier

2712

statement

2713

.RS 0.25i

2714

.PP

2715

.B server-identifier \fIhostname\fR\fB;\fR

2716

.PP

2717

The server-identifier statement can be used to define the value that

2718

is sent in the DHCP Server Identifier option for a given scope. The

2719

value specified \fBmust\fR be an IP address for the DHCP server, and

2720

must be reachable by all clients served by a particular scope.

2721

.PP

2722

The use of the server-identifier statement is not recommended - the only

2723

reason to use it is to force a value other than the default value to be

2724

sent on occasions where the default value would be incorrect. The default

2725

value is the first IP address associated with the physical network interface

2726

on which the request arrived.

2727

.PP

2728

The usual case where the

2729

\fIserver-identifier\fR statement needs to be sent is when a physical

2730

interface has more than one IP address, and the one being sent by default

2731

isn't appropriate for some or all clients served by that interface.

2732

Another common case is when an alias is defined for the purpose of

2733

having a consistent IP address for the DHCP server, and it is desired

2734

that the clients use this IP address when contacting the server.

2735

.PP

2736

Supplying a value for the dhcp-server-identifier option is equivalent

2737

to using the server-identifier statement.

2738

.RE

2739

.PP

2740

The

2741

.I server-duid

2742

statement

2743

.RS 0.25i

2744

.PP

2745

.B server-duid \fILLT\fR [ \fIhardware-type\fR \fItimestamp\fR \fIhardware-address\fR ] \fB;\fR

2746

2747

.B server-duid \fIEN\fR \fIenterprise-number\fR \fIenterprise-identifier\fR \fB;\fR

2748

2749

.B server-duid \fILL\fR [ \fIhardware-type\fR \fIhardware-address\fR ] \fB;\fR

2750

.PP

2751

The server-duid statement configures the server DUID. You may pick either

2752

LLT (link local address plus time), EN (enterprise), or LL (link local).

2753

.PP

2754

If you choose LLT or LL, you may specify the exact contents of the DUID.

2755

Otherwise the server will generate a DUID of the specified type.

2756

.PP

2757

If you choose EN, you must include the enterprise number and the

2758

enterprise-identifier.

2759

.PP

2760

The default server-duid type is LLT.

2761

.RE

2762

.PP

2763

The

2764

.I server-name

2765

statement

2766

.RS 0.25i

2767

.PP

2768

.B server-name "\fIname\fB";\fR

2769

.PP

2770

The \fIserver-name\fR statement can be used to inform the client of

2771

the name of the server from which it is booting. \fIName\fR should

2772

be the name that will be provided to the client.

2773

.RE

2774

.PP

2775

The

2776

.I site-option-space

2777

statement

2778

.RS 0.25i

2779

.PP

2780

.B site-option-space "\fIname\fB";\fR

2781

.PP

2782

The \fIsite-option-space\fR statement can be used to determine from

2783

what option space site-local options will be taken. This can be used

2784

in much the same way as the \fIvendor-option-space\fR statement.

2785

Site-local options in DHCP are those options whose numeric codes are

2786

greater than 224. These options are intended for site-specific

2787

uses, but are frequently used by vendors of embedded hardware that

2788

contains DHCP clients. Because site-specific options are allocated

2789

on an ad hoc basis, it is quite possible that one vendor's DHCP client

2790

might use the same option code that another vendor's client uses, for

2791

different purposes. The \fIsite-option-space\fR option can be used

2792

to assign a different set of site-specific options for each such

2793

vendor, using conditional evaluation (see \fBdhcp-eval (5)\fR for

2794

details).

2795

.RE

2796

.PP

2797

The

2798

.I stash-agent-options

2799

statement

2800

.RS 0.25i

2801

.PP

2802

.B stash-agent-options \fIflag\fB;\fR

2803

.PP

2804

If the \fIstash-agent-options\fR parameter is true for a given client,

2805

the server will record the relay agent information options sent during

2806

the client's initial DHCPREQUEST message when the client was in the

2807

SELECTING state and behave as if those options are included in all

2808

subsequent DHCPREQUEST messages sent in the RENEWING state. This

2809

works around a problem with relay agent information options, which is

2810

that they usually not appear in DHCPREQUEST messages sent by the

2811

client in the RENEWING state, because such messages are unicast

2812

directly to the server and not sent through a relay agent.

2813

.RE

2814

.PP

2815

The

2816

.I update-conflict-detection

2817

statement

2818

.RS 0.25i

2819

.PP

2820

.B update-conflict-detection \fIflag\fB;\fR

2821

.PP

2822

If the \fIupdate-conflict-detection\fR parameter is true, the server will

2823

perform standard DHCID multiple-client, one-name conflict detection. If

2824

the parameter has been set false, the server will skip this check and

2825

instead simply tear down any previous bindings to install the new

2826

binding without question. The default is true.

2827

.RE

2828

.PP

2829

The

2830

.I update-optimization

2831

statement

2832

.RS 0.25i

2833

.PP

2834

.B update-optimization \fIflag\fB;\fR

2835

.PP

2836

If the \fIupdate-optimization\fR parameter is false for a given client,

2837

the server will attempt a DNS update for that client each time the

2838

client renews its lease, rather than only attempting an update when it

2839

appears to be necessary. This will allow the DNS to heal from

2840

database inconsistencies more easily, but the cost is that the DHCP

2841

server must do many more DNS updates. We recommend leaving this option

2842

enabled, which is the default. This option only affects the behavior of

2843

the interim DNS update scheme, and has no effect on the ad-hoc DNS update

2844

scheme. If this parameter is not specified, or is true, the DHCP server

2845

will only update when the client information changes, the client gets a

2846

different lease, or the client's lease expires.

2847

.RE

2848

.PP

2849

The

2850

.I update-static-leases

2851

statement

2852

.RS 0.25i

2853

.PP

2854

.B update-static-leases \fIflag\fB;\fR

2855

.PP

2856

The \fIupdate-static-leases\fR flag, if enabled, causes the DHCP

2857

server to do DNS updates for clients even if those clients are being

2858

assigned their IP address using a \fIfixed-address\fR statement - that

2859

is, the client is being given a static assignment. This can only

2860

work with the \fIinterim\fR DNS update scheme. It is not

2861

recommended because the DHCP server has no way to tell that the update

2862

has been done, and therefore will not delete the record when it is not

2863

in use. Also, the server must attempt the update each time the

2864

client renews its lease, which could have a significant performance

2865

impact in environments that place heavy demands on the DHCP server.

2866

.RE

2867

.PP

2868

The

2869

.I use-host-decl-names

2870

statement

2871

.RS 0.25i

2872

.PP

2873

.B use-host-decl-names \fIflag\fB;\fR

2874

.PP

2875

If the \fIuse-host-decl-names\fR parameter is true in a given scope,

2876

then for every host declaration within that scope, the name provided

2877

for the host declaration will be supplied to the client as its

2878

hostname. So, for example,

2879

.PP

2880

.nf

2881

group {

2882

use-host-decl-names on;

2883

2884

host joe {

2885

hardware ethernet 08:00:2b:4c:29:32;

2886

fixed-address joe.fugue.com;

2887

}

2888

}

2889

2890

is equivalent to

2891

2892

host joe {

2893

hardware ethernet 08:00:2b:4c:29:32;

2894

fixed-address joe.fugue.com;

2895

option host-name "joe";

2896

}

2897

.fi

2898

.PP

2899

An \fIoption host-name\fR statement within a host declaration will

2900

override the use of the name in the host declaration.

2901

.PP

2902

It should be noted here that most DHCP clients completely ignore the

2903

host-name option sent by the DHCP server, and there is no way to

2904

configure them not to do this. So you generally have a choice of

2905

either not having any hostname to client IP address mapping that the

2906

client will recognize, or doing DNS updates. It is beyond

2907

the scope of this document to describe how to make this

2908

determination.

2909

.RE

2910

.PP

2911

The

2912

.I use-lease-addr-for-default-route

2913

statement

2914

.RS 0.25i

2915

.PP

2916

.B use-lease-addr-for-default-route \fIflag\fR\fB;\fR

2917

.PP

2918

If the \fIuse-lease-addr-for-default-route\fR parameter is true in a

2919

given scope, then instead of sending the value specified in the

2920

routers option (or sending no value at all), the IP address of the

2921

lease being assigned is sent to the client. This supposedly causes

2922

Win95 machines to ARP for all IP addresses, which can be helpful if

2923

your router is configured for proxy ARP. The use of this feature is

2924

not recommended, because it won't work for many DHCP clients.

2925

.RE

2926

.PP

2927

The

2928

.I vendor-option-space

2929

statement

2930

.RS 0.25i

2931

.PP

2932

.B vendor-option-space \fIstring\fR\fB;\fR

2933

.PP

2934

The \fIvendor-option-space\fR parameter determines from what option

2935

space vendor options are taken. The use of this configuration

2936

parameter is illustrated in the \fBdhcp-options(5)\fR manual page, in

2937

the \fIVENDOR ENCAPSULATED OPTIONS\fR section.

2938

.RE

2939

.SH SETTING PARAMETER VALUES USING EXPRESSIONS

2940

Sometimes it's helpful to be able to set the value of a DHCP server

2941

parameter based on some value that the client has sent. To do this,

2942

you can use expression evaluation. The

2943

.B dhcp-eval(5)

2944

manual page describes how to write expressions. To assign the result

2945

of an evaluation to an option, define the option as follows:

2946

.nf

2947

.sp 1

2948

\fImy-parameter \fB= \fIexpression \fB;\fR

2949

.fi

2950

.PP

2951

For example:

2952

.nf

2953

.sp 1

2954

ddns-hostname = binary-to-ascii (16, 8, "-",

2955

substring (hardware, 1, 6));

2956

.fi

2957

.RE

2958

.SH RESERVED LEASES

2959

It's often useful to allocate a single address to a single client, in

2960

approximate perpetuity. Host statements with \fBfixed-address\fR clauses

2961

exist to a certain extent to serve this purpose, but because host statements

2962

are intended to approximate \'static configuration\', they suffer from not

2963

being referenced in a littany of other Server Services, such as dynamic DNS,

2964

failover, \'on events\' and so forth.

2965

.PP

2966

If a standard dynamic lease, as from any range statement, is marked

2967

\'reserved\', then the server will only allocate this lease to the client it

2968

is identified by (be that by client identifier or hardware address).

2969

.PP

2970

In practice, this means that the lease follows the normal state engine, enters

2971

ACTIVE state when the client is bound to it, expires, or is released, and any

2972

events or services that would normally be supplied during these events are

2973

processed normally, as with any other dynamic lease. The only difference

2974

is that failover servers treat reserved leases as special when they enter

2975

the FREE or BACKUP states - each server applies the lease into the state it

2976

may allocate from - and the leases are not placed on the queue for allocation

2977

to other clients. Instead they may only be \'found\' by client identity. The

2978

result is that the lease is only offered to the returning client.

2979

.PP

2980

Care should probably be taken to ensure that the client only has one lease

2981

within a given subnet that it is identified by.

2982

.PP

2983

Leases may be set \'reserved\' either through OMAPI, or through the

2984

\'infinite-is-reserved\' configuration option (if this is applicable to your

2985

environment and mixture of clients).

2986

.PP

2987

It should also be noted that leases marked \'reserved\' are effectively treated

2988

the same as leases marked \'bootp\'.

2989

.RE

2990

.SH REFERENCE: OPTION STATEMENTS

2991

DHCP option statements are documented in the

2992

.B dhcp-options(5)

2993

manual page.

2994

.SH REFERENCE: EXPRESSIONS

2995

Expressions used in DHCP option statements and elsewhere are

2996

documented in the

2997

.B dhcp-eval(5)

2998

manual page.

2999

.SH SEE ALSO

3000

dhcpd(8), dhcpd.leases(5), dhcp-options(5), dhcp-eval(5), RFC2132, RFC2131.

3001

.SH AUTHOR

3002

.B dhcpd.conf(5)

3003

was written by Ted Lemon

3004

under a contract with Vixie Labs. Funding

3005

for this project was provided by Internet Systems Consortium.

3006

Information about Internet Systems Consortium can be found at

3007

.B https://www.isc.org.