README.md 5.5 KB
Newer Older
1
2
3
Zonemaster LDNS
===============

mats Dufberg's avatar
mats Dufberg committed
4
5
6
7
8
9
10
11
12
13
**Table of contents**

* [Introduction](#introduction)
* [Dependencies and Compatibility](#dependencies-and-compatibility)
* [Installation and verification](#installation-and-verification)
  * [Recommended installation](#recommended-installation)
  * [Installation from source](#installation-from-source)
  * [Post-installation sanity check](#post-installation-sanity-check)
  * [Testing](#testing)
* [Optional features](#optional-features)
14
15
16
  * [Ed25519]
  * [IDN]
  * [Internal ldns]
mats Dufberg's avatar
mats Dufberg committed
17
18
19
  * [Randomized capitalization](#randomized-capitalization)


20
21
## Introduction

mats Dufberg's avatar
mats Dufberg committed
22
This module provides a Perl interface to the [ldns library](https://www.nlnetlabs.nl/projects/ldns/) from [NLnet Labs](https://www.nlnetlabs.nl/). This module includes the necessary C code from ldns, so the library does not need to be globally installed. It does, however, rely on a sufficiently recent version of OpenSSL being present.
Calle Dybedahl's avatar
Calle Dybedahl committed
23

24
This module is written as part of the [Zonemaster project](http://github.com/zonemaster/zonemaster), and therefore primarily exposes the functionality needed for that. Since Zonemaster is a diagnostic tool, that means the functions most used are those for looking things up and inspecting them.
25

mats Dufberg's avatar
mats Dufberg committed
26
If you want a module that specifically aims to be a complete and transparent interface to ldns, [DNS::LDNS](http://search.cpan.org/~erikoest/DNS-LDNS/) is a better fit than this module.
27
28

Initially this module was named Net::LDNS.
Calle Dybedahl's avatar
Calle Dybedahl committed
29

mats Dufberg's avatar
mats Dufberg committed
30
## Dependencies and compatibility
31

32
Run-time dependencies:
33
 * `openssl` (openssl >= 1.1.1 unless [Ed25519] is disabled)
34
 * `libidn` (if [IDN] is enabled)
35
 * `libldns` (if [Internal ldns] is disabled; libldns >= 1.7.0, or libldns >= 1.7.1 if [Ed25519] is enabled)
36
37
38
39

Compile-time dependencies (only when installing from source):
 * `make`
 * `Devel::CheckLib`
40
41
 * `Module::Install`
 * `Module::Install::XSUtil`
42
 * `Test::More >= 1.302015`
43
44
45
46
47
48
49
 * `git` (if [Internal ldns] is enabled)
 * `libtool` (if [Internal ldns] is enabled)
 * `autoconf` (if [Internal ldns] is enabled)
 * `automake` (if [Internal ldns] is enabled)

Test-time dependencies:
 * `Test::Fatal`
50

mats Dufberg's avatar
mats Dufberg committed
51
There is a small part in the code that may not be compatible with non-Unix operating systems, in that it assumes that the file /dev/null exists.
52

mats Dufberg's avatar
mats Dufberg committed
53
## Installation and verification
54

55
### Recommended installation
mats Dufberg's avatar
mats Dufberg committed
56

57
The recommended way to install Zonemaster::LDNS is to install it from CPAN as a dependency to Zonemaster::Engine. If you follow the [installation instructions for Zonemaster::Engine](https://github.com/zonemaster/zonemaster-engine/blob/master/docs/Installation.md) you will get all the prerequisites and dependencies for Zonemaster::LDNS before installing it from CPAN.
58

59
### Installation from source
60
61
62
63
64

Override the default set of features by appending `--FEATURE` and/or
`--no-FEATURE` options to the `perl Makefile.PL` command.

```sh
65
git clone https://github.com/zonemaster/zonemaster-ldns
66
67
68
69
70
71
72
73
74
75
cd zonemaster-ldns
perl Makefile.PL
make
make test
make install
```

> **Note:** The source ZIP files downloaded from Github are broken with
> respect to this instruction.

mats Dufberg's avatar
mats Dufberg committed
76
### Post-installation sanity check
77
78
79
80
81
82
83

```sh
perl -MZonemaster::LDNS -E 'say Zonemaster::LDNS->new("8.8.8.8")->query("zonemaster.net")->string'
```

The above command should print some `dig`-like output.

mats Dufberg's avatar
mats Dufberg committed
84
### Testing
mats Dufberg's avatar
mats Dufberg committed
85
86

Some of the unit tests depend on data on Internet, which may change. To avoid false 
mats Dufberg's avatar
mats Dufberg committed
87
88
89
fails, those unit tests are only run if the environment variable `TEST_WITH_NETWORK` is `true`. By default that variable
is unset (those tests are not run). To run all tests, execute

90
```sh
mats Dufberg's avatar
mats Dufberg committed
91
92
TEST_WITH_NETWORK=1 make test
```
Calle Dybedahl's avatar
Calle Dybedahl committed
93

mats Dufberg's avatar
mats Dufberg committed
94
## Optional features
95

mats Dufberg's avatar
mats Dufberg committed
96
97
98
When installing from source, you can choose to enable or disable a number
of optional features using command line options to the `perl Makefile.PL`
commands.
99

100
101
102
103
104
### Ed25519

Enabled by default.
Disabled with `--no-ed25519`

105
106
Requires support for Ed25519 in both openssl and ldns.

107
>
108
109
> *Note:* Zonemaster Engine relies on this feature for its analysis when Ed25519
> (algorithm 15) is being used in DNS records.
110
111
>

mats Dufberg's avatar
mats Dufberg committed
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
### IDN

Enabled by default.
Disable with `--no-idn`.

If the IDN feature is enabled, the GNU `libidn` library will be used to
add a simple function that converts strings from Perl's internal encoding
to IDNA domain name format.
In order to convert strings from whatever encoding you have to Perl's
internal format, use L<Encode>.
If you need any kind of control or options, use L<Net::LibIDN>.
The included function here is only meant to assist in the most basic case,
although that should cover a lot of real-world use cases.

> **Note:** The Zonemaster Engine test suite assumes this feature
> is enabled.

### Internal ldns

Enabled by default.
Disable with `--no-internal-ldns`.

When enabled, an included version of ldns is statically linked into
Zonemaster::LDNS.
When disabled, libldns is dynamically linked just like other dependencies.

### Randomized capitalization

Disabled by default.
Enable with `--randomize`.

> **Note:** This feature is experimental.

Randomizes the capitalization of returned domain names.
146
147


148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
### Custom OpenSSL

Disabled by default.
Enabled with `--prefix-openssl=/path/to/openssl`.

Enabling this makes the build tools look for OpenSSL in a non-standard place.

Technically this does two things:
 * Libcrypto is sought in the `lib` directory under the given directory.
 * The `include` directory under the given directory is added to the include
   path.

> **Note:** The `lib` directory under the given path must be known to the
> dynamic linker or feature checks will fail.


164
165
[IDN]: #idn
[Internal ldns]: #internal-ldns
166
167
[Ed25519]: #ed25519