1

# pvl-hosts

     2

     3

DNS/DHCP hosts management/integration for ISC bind9 and dhcpd.

     4

     5

## Hosts

     6

The `pvl.hosts-*` tools read hosts files as input, which have an ini format, using section names as hostnames to configure attributes for that host:

     7

     8

    [foo]

     9

        ip          = 192.0.2.1

    10

        ethernet    = 00:11:22:33:44:55

    11

    12

    [bar]

    13

        ip          = 192.0.2.2

    14

        ethernet    = 01:23:45:67:89:ab

    15

    16

The domain name for a host is determined from the basename of the config file, so this example file would generate something like the following output for use in a `zone "example.com" { ... }` zonefile:

    17

    18

    $ bin/pvl.hosts-forward etc/hosts/example.com 

    19

    foo                               A     192.0.2.1

    20

    bar                               A     192.0.2.2

    21

    22

And correspondingly, the reverse zone for `2.0.192.in-addr.arpa`:

    23

    24

    $ bin/pvl.hosts-reverse --zone-prefix=192.0.2.0/24 etc/hosts/example.com

    25

    1                                 PTR   foo.example.com.

    26

    2                                 PTR   bar.example.com.

    27

    28

And the associated DHCP hosts:

    29

    30

    $ bin/pvl.hosts-dhcp etc/hosts/example.com 

    31

    host foo {

    32

        option host-name foo;

    33

        hardware ethernet 00:11:22:33:44:55;

    34

        fixed-address 192.0.2.1;

    35

    }

    36

    37

    host bar {

    38

        option host-name bar;

    39

        hardware ethernet 01:23:45:67:89:ab;

    40

        fixed-address 192.0.2.2;

    41

    }

    42

    43

### Include directories

    44

Host configs can be included:

    45

    46

    $ cat etc/hosts/test

    47

    include = test.d/

    48

    49

    $ cat etc/hosts/test.d/foo 

    50

    ip = 192.0.2.1

    51

    52

    $ cat etc/hosts/test.d/bar 

    53

    ip = 192.0.2.2

    54

    55

    $ bin/pvl.hosts-forward etc/hosts/test

    56

    foo                               A     192.0.2.1

    57

    bar                               A     192.0.2.2

    58

    59

Including a directory of files is equivalent to substituiting each file as a named section at the level of the include = statement. Note that this means that included files are treated directly as host definitions, IOW, you should NOT include a section name in an included host file unless you want to declare an additional subdomain:

    60

    61

    $ cat etc/hosts/wrong.test 

    62

    include = wrong.d/

    63

    64

    $ etc/hosts/wrong.d/host

    65

    [host]

    66

        ip  = 192.0.2.6

    67

    68

Using the --root-zone option to generate the full FQDN for the host:

    69

    70

    $ bin/pvl.hosts-forward --root-zone etc/hosts/wrong.test 

    71

    host.host.wrong.test              A     192.0.2.6

    72

    73

### Host aliases

    74

Hosts can specify DNS aliases:

    75

    76

    [foo]

    77

        ip          = 127.0.0.1

    78

        alias       = test1

    79

        alias4      = test

    80

    81

    [bar]

    82

        ip          = 127.0.0.2

    83

        alias       = test2

    84

        alias4      = test

    85

    86

    $ bin/pvl.hosts-forward etc/hosts/alias.test 

    87

    foo                               A     127.0.0.1

    88

    test1                             CNAME foo

    89

    test                              A     127.0.0.1

    90

    bar                               A     127.0.0.2

    91

    test2                             CNAME bar

    92

    test                              A     127.0.0.2

    93

    94

Normal CNAME aliases cannot overlap with other hosts, but the IPv4/IPv6-only `alias4`/`alias6` may overlap.

    95

    96

### Generated hosts

    97

The hosts file format supports something similar to bind9's $GENERATE directive for hosts:

    98

    99

    [dyn{1-8}]

   100

        ip  = 10.1.16.$

   101

   102

    $ bin/pvl.hosts-forward etc/hosts/dyn.test 

   103

    dyn1                              A     10.1.16.1

   104

    dyn2                              A     10.1.16.2

   105

    dyn3                              A     10.1.16.3

   106

    dyn4                              A     10.1.16.4

   107

    dyn5                              A     10.1.16.5

   108

    dyn6                              A     10.1.16.6

   109

    dyn7                              A     10.1.16.7

   110

    dyn8                              A     10.1.16.8

   111

   112

This feature can be used for generating reverse delegations:

   113

    [foo-{240-247}]

   114

        forward =

   115

        reverse = $.240/29.0.0.10.in-addr.arpa

   116

        ip      = 10.0.0.$

   117

   118

    $ bin/pvl.hosts-reverse --zone-prefix=10.0.0.0/16 etc/hosts/reverse.test 

   119

    240.0                             CNAME 240.240/29.0.0.10.in-addr.arpa.

   120

    241.0                             CNAME 241.240/29.0.0.10.in-addr.arpa.

   121

    242.0                             CNAME 242.240/29.0.0.10.in-addr.arpa.

   122

    243.0                             CNAME 243.240/29.0.0.10.in-addr.arpa.

   123

    244.0                             CNAME 244.240/29.0.0.10.in-addr.arpa.

   124

    245.0                             CNAME 245.240/29.0.0.10.in-addr.arpa.

   125

    246.0                             CNAME 246.240/29.0.0.10.in-addr.arpa.

   126

    247.0                             CNAME 247.240/29.0.0.10.in-addr.arpa.

   127

   128

### DHCP Options

   129

The hosts need not specify any fixed ip address, leaving IP address allocation to dhcpd:

   130

   131

    [foo]

   132

        ethernet    = 00:11:22:33:44:55 

   133

   134

    $ bin/pvl.hosts-dhcp etc/hosts/dhcp.test 

   135

    host foo {

   136

        option host-name foo;

   137

        hardware ethernet 00:11:22:33:44:55;

   138

    }

   139

   140

### DHCP Boot options

   141

The hosts can specify DHCP boot server/file options:

   142

   143

    boot.next-server  = boot.test

   144

   145

    [foo]

   146

        ethernet        = 00:11:22:33:44:55

   147

        boot            = boot2.test:/debian/wheezy/pxelinux.0

   148

   149

    [bar]

   150

        ethernet        = 00:11:22:33:44:55

   151

        boot.filename   = /debian/jessie/pxelinux.0

   152

   153

    $ bin/pvl.hosts-dhcp etc/hosts/boot.test 

   154

    host foo {

   155

        option host-name foo;

   156

        hardware ethernet 00:11:22:33:44:55;

   157

        next-server boot2.test;

   158

        filename "/debian/wheezy/pxelinux.0";

   159

    }

   160

   161

    host bar {

   162

        option host-name bar;

   163

        hardware ethernet 00:11:22:33:44:55;

   164

        next-server boot.test;

   165

        filename "/debian/jessie/pxelinux.0";

   166

    }

   167

   168

### DHCP hosts in multiple subnets/domains

   169

A host with different interfaces in multiple domains must specify unique interface names:

   170

   171

    [foo]

   172

        [[asdf]]

   173

            ip              = 10.1.0.1

   174

            ethernet.eth1   = 00:11:22:33:44:55

   175

   176

    [bar]

   177

        [[asdf]]

   178

            ip              = 10.2.0.1

   179

            ethernet.eth2   = 55:44:33:22:11:00

   180

   181

    $ bin/pvl.hosts-dhcp etc/hosts/dhcp-test 

   182

    host asdf-eth1 {

   183

        option host-name asdf;

   184

        hardware ethernet 00:11:22:33:44:55;

   185

        fixed-address 10.1.0.1;

   186

    }

   187

   188

    host asdf-eth2 {

   189

        option host-name asdf;

   190

        hardware ethernet 55:44:33:22:11:00;

   191

        fixed-address 10.2.0.1;

   192

    }

   193

   194

### DHCP subgroups

   195

Hosts can be assigned to DHCP subgroups by hardware ethernet:

   196

   197

#### `dhcpd.conf`

   198

    class "test-hosts" {

   199

        match hardware;

   200

    }

   201

   202

#### `etc/hosts/dhcp-classes.test`

   203

    [foo]

   204

        ethernet        = 00:11:22:33:44:55

   205

        dhcp:subclass   = test-hosts

   206

   207

#### `bin/pvl.hosts-dhcp etc/hosts/dhcp-classes.test`

   208

    host foo {

   209

        option host-name foo;

   210

        hardware ethernet 00:11:22:33:44:55;

   211

    }

   212

   213

    subclass "test-hosts" 1:00:11:22:33:44:55;

   214

   215

# `update`

   216

A script to drive the *pvl.hosts* tools for maintaing a set of zone/host files for a DNS/DHCP server.

   217

   218

## Source host files

   219

   220

Creating a tree of symlinks for managing split zonefile domains can be useful:

   221

   222

    $ tree etc/zones/

   223

    etc/zones/

   224

    ├── forward

   225

    │   └── test

   226

    │       ├── asdf.test -> ../../../hosts/asdf.test

   227

    │       └── test -> ../../../hosts/test

   228

    ├── reverse

   229

    │   └── 192.0.2

   230

    │       ├── asdf.test -> ../../../hosts/asdf.test

   231

    │       └── test -> ../../../hosts/test

   232

    └── test

   233

   234

Given a structure like above, the `pvl.hosts-forward` can generate a single forward zone containing all sub-domains:

   235

   236

    $ bin/pvl.hosts-forward --hosts-include etc/hosts/ etc/zones/forward/test/

   237

    foo                               A     192.0.2.1

   238

    bar                               A     192.0.2.2

   239

    quux.asdf                         A     192.0.2.5

   240

   241

Note that the directory name is treated separately as a zone origin; the file names within the domain are still treated as a flat namespace independent of the directory name (which is different than *pvl.hosts* would behave for `include = etc/zones/forward/test/`).

   242

   243

The same trick also works for `pvl.hosts-reverse`:

   244

   245

    $ bin/pvl.hosts-reverse --hosts-include etc/hosts/ etc/zones/reverse/192.0.2/

   246

    1                                 PTR   foo.test.

   247

    2                                 PTR   bar.test.

   248

    5                                 PTR   quux.asdf.test.

   249

   250

## Source zone files

   251

   252

The zonefile header should be written out manually, using an `$INCLUDE` directive to reference the (generated) hosts zonefile:

   253

   254

    $ cat etc/zones/test 

   255

    $TTL 3600

   256

   257

    @                   SOA     foo.test. hostmaster.test. (

   258

                                0               ; serial

   259

                                1d              ; refresh

   260

                                5m              ; retry

   261

                                10d             ; expiry

   262

                                300             ; negative

   263

                        )

   264

   265

                        NS      foo

   266

                        NS      bar

   267

   268

    $INCLUDE "forward/test"

   269

   270

## Operation

   271

   272

Use the *update* script to generate a complete set of output zonefiles:

   273

   274

    $ ./bin/update -C

   275

      var: apply dir

   276

      var/dhcp: apply dir

   277

      var/zones: apply dir

   278

      var/include-cache: apply dir

   279

      var/serials: apply dir

   280

      var/dhcp/hosts: apply dir

   281

      var/zones/includes: apply dir

   282

      var/zones/forward: apply dir

   283

      var/zones/reverse: apply dir

   284

    Commit...

   285

    Using commit timestamp: 1425379711

   286

    Updating forward host zones...

   287

      var/zones/forward/test: Generating forward hosts zone: etc/zones/forward/test

   288

    Updating reverse host zones...

   289

      var/zones/reverse/192.0.2: Generating reverse hosts zone: etc/zones/reverse/192.0.2

   290

    Updating DHCP hosts...

   291

    Copying zone includes...

   292

    Updating zones...

   293

      var/serials/test: Update serial:  <- 1425379711

   294

      var/zones/test: Generate zone: etc/zones/test @ 1425379711

   295

    Updating DHCP confs...

   296

    Testing zones...

   297

    Reload zones...

   298

      Reload zones

   299

     * Reloading domain name service... bind9 [ OK ] 

   300

    Testing DHCP...

   301

    Reload DHCP...

   302

      Reload DHCP

   303

    isc-dhcp-server stop/waiting

   304

    isc-dhcp-server start/running, process 32581

   305

   306

The update script tracks hostfile/zonefile dependencies, and only updates the necessary output files:

   307

   308

    $ touch etc/hosts/test.d/foo && ./bin/update -C

   309

    Commit...

   310

    Using commit timestamp: 1425379801

   311

    Updating forward host zones...

   312

      var/zones/forward/test: Generating forward hosts zone: etc/zones/forward/test

   313

    Updating reverse host zones...

   314

      var/zones/reverse/192.0.2: Generating reverse hosts zone: etc/zones/reverse/192.0.2

   315

    Updating DHCP hosts...

   316

    Copying zone includes...

   317

    Updating zones...

   318

      var/serials/test: Update serial: 1425379801 <- 1425379801

   319

      var/zones/test: Generate zone: etc/zones/test @ 1425379801

   320

    Updating DHCP confs...

   321

    Testing zones...

   322

    Reload zones...

   323

      Reload zones

   324

     * Reloading domain name service... bind9 ...done.

   325

    Testing DHCP...

   326

    Reload DHCP...

   327

      Reload DHCP

   328

    isc-dhcp-server stop/waiting

   329

    isc-dhcp-server start/running, process 775

   330

   331

Use `-n` to enable noop mode and preview changes before updating:

   332

   333

    sed -i s/quux/quux2/ etc/hosts/asdf.test && ./bin/update -C -n

   334

    Commit...

   335

      /home/tjmartti/pvl/pvl-hosts: skip commit

   336

    Using local unix time for uncommited changes: 1425380558

   337

    Updating forward host zones...

   338

      var/zones/forward/test: Generating forward hosts zone: etc/zones/forward/test

   339

            --- var/zones/forward/test      2015-03-03 12:55:53.480735624 +0200

   340

            +++ var/zones/forward/test.new  2015-03-03 13:02:38.708732551 +0200

   341

            @@ -2,2 +2,2 @@

   342

             bar                               A     192.0.2.2

   343

            -quux.asdf                         A     192.0.2.5

   344

            +quux22.asdf                       A     192.0.2.5

   345

    Updating reverse host zones...

   346

      var/zones/reverse/192.0.2: Generating reverse hosts zone: etc/zones/reverse/192.0.2

   347

            --- var/zones/reverse/192.0.2   2015-03-03 12:55:53.596735623 +0200

   348

            +++ var/zones/reverse/192.0.2.new       2015-03-03 13:02:38.832732550 +0200

   349

            @@ -2,2 +2,2 @@

   350

             2                                 PTR   bar.test.

   351

            -5                                 PTR   quux.asdf.test.

   352

            +5                                 PTR   quux22.asdf.test.

   353

    Updating DHCP hosts...

   354

    Copying zone includes...

   355

    Updating zones...

   356

    Updating DHCP confs...

   357

    Testing zones...

   358

    Reload zones...

   359

      Skip reload zones

   360

    Testing DHCP...

   361

    Reload DHCP...

   362

      Skip reload DHCP

   363

   364

Note that noop mode does not yet handle dependency chains, i.e. you will not see which zones get updated serials without also using `-F`, which force-updates all output files regardless of dependency states.

   365

   366

Finally, the default operation mode of update is to commit any changes, and update the zones using the commit timestamp as a serial. Use the `-p` flag to show output diffs as with `-n`:

   367

   368

    $ sed -i s/quux/quux2/ etc/hosts/asdf.test && ./bin/update -m "rename quux to quux2" -p

   369

    Commit...

   370

      /home/tjmartti/pvl/pvl-hosts: commit: rename quux to quux2

   371

        diff -r 8790e1e28661 etc/hosts/asdf.test

   372

        --- a/etc/hosts/asdf.test   Tue Mar 03 13:05:13 2015 +0200

   373

        +++ b/etc/hosts/asdf.test   Tue Mar 03 13:06:03 2015 +0200

   374

        @@ -1,2 +1,2 @@

   375

        -[quux]

   376

        +[quux2]

   377

             ip  = 192.0.2.5

   378

    Using commit timestamp: 1425380763

   379

    Updating forward host zones...

   380

      var/zones/forward/test: Generating forward hosts zone: etc/zones/forward/test

   381

            --- var/zones/forward/test      2015-03-03 13:04:09.556731909 +0200

   382

            +++ var/zones/forward/test.new  2015-03-03 13:06:04.260731122 +0200

   383

            @@ -2,2 +2,2 @@

   384

             bar                               A     192.0.2.2

   385

            -quux22.asdf                       A     192.0.2.5

   386

            +quux2.asdf                        A     192.0.2.5

   387

    Updating reverse host zones...

   388

      var/zones/reverse/192.0.2: Generating reverse hosts zone: etc/zones/reverse/192.0.2

   389

            --- var/zones/reverse/192.0.2   2015-03-03 13:04:09.684731908 +0200

   390

            +++ var/zones/reverse/192.0.2.new       2015-03-03 13:06:04.384731122 +0200

   391

            @@ -2,2 +2,2 @@

   392

             2                                 PTR   bar.test.

   393

            -5                                 PTR   quux22.asdf.test.

   394

            +5                                 PTR   quux2.asdf.test.

   395

    Updating DHCP hosts...

   396

    Copying zone includes...

   397

    Updating zones...

   398

      var/serials/test: Update serial: 1425380649 <- 1425380763

   399

      var/zones/test: Generate zone: etc/zones/test @ 1425380763

   400

            --- var/zones/test      2015-03-03 13:04:09.812731907 +0200

   401

            +++ var/zones/test.new  2015-03-03 13:06:04.512731121 +0200

   402

            @@ -1,3 +1,3 @@

   403

             $TTL   3600

   404

            -@                                 SOA   foo.test. hostmaster.test. 1425380649 1d 5m 10d 300

   405

            +@                                 SOA   foo.test. hostmaster.test. 1425380763 1d 5m 10d 300

   406

                                               NS    foo

   407

    Updating DHCP confs...

   408

    Testing zones...

   409

    Reload zones...

   410

      Reload zones

   411

     * Reloading domain name service... bind9 [ OK ] 

   412

    Testing DHCP...

   413

    Reload DHCP...

   414

      Reload DHCP

   415

    isc-dhcp-server stop/waiting

   416

    isc-dhcp-server start/running, process 2839

   417

   418

   419

## Output zone files

   420

   421

The generated zone files can then be loaded by bind:

   422

   423

    $ cat var/zones/test 

   424

    $TTL    3600

   425

    @                                 SOA   foo.test. hostmaster.test. 1425049508 1d 5m 10d 300

   426

                                      NS    foo

   427

                                      NS    bar

   428

    $INCLUDE        "./var/zones/forward/test"

   429

   430

    $ cat var/zones/forward/test 

   431

    foo                               A     192.0.2.1

   432

    bar                               A     192.0.2.2

   433

    quux.asdf                         A     192.0.2.5

   434

   435

# *pvl-dns*

   436

Low-level zonefile utilities.

   437

   438

## `bin/pvl.dns-process`

   439

Process a zonefile to modify:

   440

   441

* `SOA` record serial

   442

* `$INCLUDE` paths

   443

   444

    $ bin/pvl.dns-process --serial $(date +%s) --include-path var/zones etc/zones/test 

   445

    $TTL    3600

   446

    @                                 SOA   foo.test. hostmaster.test. 1425049088 1d 5m 10d 300

   447

                                      NS    foo

   448

                                      NS    bar

   449

    $INCLUDE        "var/zones/forward/test"

   450

   451

## `bin/pvl.dns-zone`

   452

Load a zonefile and output any ZoneRecords that it contains, including `$GENERATE`ed and `$INCLUDE`ed records:

   453

   454

    $ bin/pvl.dns-zone --zone=test var/zones/test 

   455

    @                         3600    SOA   foo.test. hostmaster.test. 1425049248 1d 5m 10d 300

   456

    @                         3600    NS    foo

   457

    @                         3600    NS    bar

   458

    foo                       3600    A     192.0.2.1

   459

    bar                       3600    A     192.0.2.2

   460

    quux.asdf                 3600    A     192.0.2.5

   461

   462

   463

Optionally `--check-hosts` for dupliates `A`/`AAAA` records.

   464

   465

Use `--reverse-prefix=192.0.2` to generate a reverse-dns zone from `A`/`AAAA` records:

   466

   467

    $ bin/pvl.dns-zone --zone=test var/zones/test --reverse-prefix=192.0.2

   468

    1                                 PTR   foo.test.

   469

    2                                 PTR   bar.test.

   470

    5                                 PTR   quux.asdf.test.

   471

   472

# Experimental features 

   473

   474

Features that are still under development

   475

   476

* DHCP host status tracking from syslog/dhcpd.leases into a database 

   477

* SNMP network topology discovery