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

    80

    [bar]

    81

        ip          = 127.0.0.2

    82

        alias       = test2

    83

    84

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

    85

    foo                               A     127.0.0.1

    86

    test1                             CNAME foo

    87

    bar                               A     127.0.0.2

    88

    test2                             CNAME bar

    89

    90

### Generated hosts

    91

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

    92

    93

    [asdf{1-3}]

    94

        ip  = 10.100.100.$

    95

    96

    $ bin/pvl.hosts-dns --forward-zone=asdf etc/hosts/asdf 

    97

    asdf1@asdf                        A     10.100.100.1

    98

    asdf2@asdf                        A     10.100.100.2

    99

    asdf3@asdf                        A     10.100.100.3

   100

   101

Note that the generate directives are interpreted and compiled directly by pvl.hosts. 

   102

   103

Most of the $GENERATE options should be supported, with a little clever hackery:

   104

   105

    [asdf{1-5/2}{0,2}]

   106

       ip  = 10.100.100.$${10}

   107

   108

    $ bin/pvl.hosts-dns --forward-zone=asdf2 etc/hosts/asdf2

   109

    asdf01@asdf2                      A     10.100.100.11

   110

    asdf03@asdf2                      A     10.100.100.13

   111

    asdf05@asdf2                      A     10.100.100.15

   112

   113

This feature can be used for generating reverse delegations:

   114

   115

    [foo-{240-247}]

   116

        forward =

   117

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

   118

        ip      = 10.0.0.$

   119

   120

    $ bin/pvl.hosts-dns --reverse-zone=10 etc/hosts/reverse 

   121

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

   122

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

   123

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

   124

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

   125

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

   126

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

   127

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

   128

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

   129

   130

### DHCP Options

   131

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

   132

   133

    [foo]

   134

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

   135

   136

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

   137

    host foo {

   138

        option host-name foo;

   139

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

   140

    }

   141

   142

### DHCP Boot options

   143

The hosts can specify DHCP boot server/file options:

   144

   145

    [foo]

   146

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

   147

        boot        = boot.lan:debian/wheezy/pxelinux.0

   148

   149

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

   150

    host foo {

   151

        option host-name foo;

   152

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

   153

        next-server boot.lan;

   154

        filename debian/wheezy/pxelinux.0;

   155

    }

   156

   157

### DHCP hosts in multiple subnets/domains

   158

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

   159

   160

    [foo.dhcp]

   161

        [[asdf]]

   162

            ip              = 10.1.0.1

   163

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

   164

   165

    [bar.dhcp]

   166

        [[asdf]]

   167

            ip              = 10.2.0.1

   168

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

   169

   170

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

   171

    host asdf-eth1 {

   172

        option host-name asdf;

   173

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

   174

        fixed-address 10.1.0.1;

   175

    }

   176

   177

    host asdf-eth2 {

   178

        option host-name asdf;

   179

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

   180

        fixed-address 10.2.0.1;

   181

    }

   182

   183

# `update`

   184

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

   185

   186

## Source host files

   187

   188

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

   189

   190

    $ tree etc/zones/

   191

    etc/zones/

   192

    ├── forward

   193

    │   └── test

   194

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

   195

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

   196

    └── reverse

   197

        └── 192.0.2

   198

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

   199

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

   200

   201

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

   202

   203

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

   204

    foo                               A     192.0.2.1

   205

    bar                               A     192.0.2.2

   206

    quux.asdf                         A     192.0.2.5

   207

   208

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/`).

   209

   210

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

   211

   212

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

   213

    1                                 PTR   foo.test.

   214

    2                                 PTR   bar.test.

   215

    5                                 PTR   quux.asdf.test.

   216

   217

## Source zone files

   218

   219

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

   220

   221

    $ cat etc/zones/test 

   222

    $TTL 3600

   223

   224

    @                   SOA     foo.test. hostmaster.test. (

   225

                                0               ; serial

   226

                                1d              ; refresh

   227

                                5m              ; retry

   228

                                10d             ; expiry

   229

                                300             ; negative

   230

                        )

   231

   232

                        NS      foo

   233

                        NS      bar

   234

   235

    $INCLUDE "forward/test"

   236

   237

## Operation

   238

   239

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

   240

   241

    $ ./bin/update

   242

    Commit...

   243

    Using commit timestamp: 1425049508

   244

    Updating forward host zones...

   245

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

   246

    Updating reverse host zones...

   247

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

   248

    Updating DHCP hosts...

   249

    Copying zone includes...

   250

    Updating zones...

   251

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

   252

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

   253

    Updating DHCP confs...

   254

    Testing zones...

   255

    Reload zones...

   256

      Reload zones

   257

            rndc: server reload successful

   258

    Testing DHCP...

   259

    Reload DHCP...

   260

   261

## Output zone files

   262

   263

The generated zone files can then be loaded by bind:

   264

   265

    $ cat var/zones/test 

   266

    $TTL    3600

   267

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

   268

                                      NS    foo

   269

                                      NS    bar

   270

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

   271

   272

    $ cat var/zones/forward/test 

   273

    foo                               A     192.0.2.1

   274

    bar                               A     192.0.2.2

   275

    quux.asdf                         A     192.0.2.5

   276

   277

# *pvl-dns*

   278

Low-level zonefile utilities.

   279

   280

## `bin/pvl.dns-process`

   281

Process a zonefile to modify:

   282

   283

* `SOA` record serial

   284

* `$INCLUDE` paths

   285

   286

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

   287

    $TTL    3600

   288

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

   289

                                      NS    foo

   290

                                      NS    bar

   291

    $INCLUDE        "var/zones/forward/test"

   292

   293

## `bin/pvl.dns-zone`

   294

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

   295

   296

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

   297

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

   298

    @                         3600    NS    foo

   299

    @                         3600    NS    bar

   300

    foo                       3600    A     192.0.2.1

   301

    bar                       3600    A     192.0.2.2

   302

    quux.asdf                 3600    A     192.0.2.5

   303

   304

   305

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

   306

   307

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

   308

   309

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

   310

    1                                 PTR   foo.test.

   311

    2                                 PTR   bar.test.

   312

    5                                 PTR   quux.asdf.test.

   313

   314

# Experimental features 

   315

   316

Features that are still under development

   317

   318

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

   319

* SNMP network topology discovery