Skip to content

Commit 4f304df

Browse files
ppacherppacher
committed
Added plugin documentation
1 parent d4e1b24 commit 4f304df

File tree

11 files changed

+514
-0
lines changed

11 files changed

+514
-0
lines changed

‎.gitmodules

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "nextdhcp"]
2+
path = nextdhcp
3+
url = https://github.com/nextdhcp/nextdhcp

‎content/plugins/database.md

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
---
2+
title: "database"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
# database
8+
9+
## Name
10+
11+
*database* - configures the lease database to use
12+
13+
## Description
14+
15+
The *database* plugin configures the lease database to use. Most users will likely don't need to use it as the default [bbolt](https://github.com/etcd-io/bbolt) driver will be used. Note that the database plugin only allows configuration of
16+
databases that have been compiled into NextDHCP.
17+
18+
## Syntax
19+
20+
```
21+
database NAME OPTION...
22+
```
23+
24+
* **NAME** is the name of the database driver to use
25+
* **OPTION** is one or more options for the database driver. Please refer to the
26+
documentation of the driver you like to use for more information.
27+
28+
The *database* plugin also allows a block based key-value configuration that has
29+
the following syntax:
30+
31+
```
32+
database NAME {
33+
KEY VALUE
34+
...
35+
}
36+
```
37+
38+
**NAME** is the name of the database driver and **KEY**/**VALUE** specify driver related configuration parameters.
39+
40+
## Examples
41+
42+
```
43+
192.168.0.1/24 {
44+
database bold ./leases.db
45+
}
46+
```
47+
48+
```
49+
192.168.0.1/24 {
50+
database bold {
51+
file ./leases.db
52+
timeout 1m
53+
mode 0600
54+
}
55+
}
56+
```
57+
58+
There's also the built-in *memory* database driver. Note that this driver does not
59+
persist leases in any way so a restart of NextDHCP will discard all active leases.
60+
61+
**Use with case**
62+
63+
```
64+
192.168.0.1/24 {
65+
database memory
66+
}
67+
```

‎content/plugins/gotify.md

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
---
2+
title: "gotify"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
# gotify
8+
9+
## Name
10+
11+
*gotify* - Send notifications via [Gotify](https://gotify.net)
12+
13+
## Description
14+
15+
The *gotify* plugin can send push notifications about IP addresses and client requests. In order to
16+
authenticate against the gotify server please make sure to create a new application token first. If a
17+
gotify directive does not specify a server address and token it will use them from a previously defined
18+
directive. If not server address and token can be found an error is thrown. In other words, the first
19+
gotify directive MUST have a server and token configured. It is also possible to omit the message and
20+
condition to only declare the authentication token and server address.
21+
22+
## Syntax
23+
24+
```
25+
gotify [CONDITION] {
26+
[server SERVER TOKEN]
27+
[title TITLE]
28+
[message MESSAGE]
29+
}
30+
```
31+
32+
* **CONDITION** is the condition that must match to send a notification via gotify. If the condition is omitted, a notification
33+
will be sent for each message.
34+
* **SERVER** is the server address of where gotify is running
35+
* **TOKEN** is the application token generated on the gotify server
36+
* **TITLE** is the title of the notification. All [replacement keys](../../core/replacer/README.md) are supported.
37+
* **MESSAGE** is the message that should be sent. All [replacement keys](../../core/replacer/README.md) are supported.
38+
39+
## Examples
40+
41+
This example will send a notification for each client that requests a new IP address:
42+
43+
```
44+
gotify msgtype == 'REQUEST' && clientip != '' {
45+
server https://gotify.example.com Adk57Vkdh487
46+
title '{msgtype} by {hostname}'
47+
message 'Client {hwaddr} '
48+
}
49+
```

‎content/plugins/ifname.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: "interface"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
8+
# interface
9+
10+
## Name
11+
12+
*interface* - allows to configure the interface a subnet listener should bind to
13+
14+
## Description
15+
16+
By default NextDHCP tries to find the interface that has the IP address of the subnet to serve assigned.
17+
As this may fail for various reasons the *interface* plugin can be used to tell NextDHCP which interface
18+
should be used. This plugin/directive should **not** be use more than once.
19+
20+
## Syntax
21+
22+
```
23+
interface IFNAME
24+
```
25+
26+
* **IFNAME** is the name of the network interface as reported by `ifconfig` or `ip addr`. NextDHCP will error out if the interface does not exist
27+
28+
## Examples
29+
30+
The most basic example is to tell NextDHCP that it should serve a given subnet (10.1.0.1/8) on `eth0`:
31+
32+
```
33+
10.1.0.1/8 {
34+
interface eth0
35+
}
36+
```
37+
38+
Working with VLANs can also be implemented by using the `interface` directive:
39+
(assuming *eth0.300* is a tagged VLAN port)
40+
41+
```
42+
10.0.300.0/24 {
43+
interface eth0.300
44+
}
45+
```
46+

‎content/plugins/lease.md

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: "lease"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
# lease
8+
9+
## Name
10+
11+
*lease* - configure the allowed lease time for an IP address
12+
13+
## Description
14+
15+
The *lease* plugin allows to configure the valid life-time of an IP address lease. It only sets the IP address lease time if no other plugin set it. The *lease* option SHOULD be used in almost all NextDHCP setups.
16+
17+
## Syntax
18+
19+
```
20+
lease DURATION
21+
```
22+
23+
* **DURATION** is the duration for which a lease is valid. The format should follow the [time.Duration](https://godoc.org/golang.org/time) format supported by [Go](https://golang.org)
24+
25+
## Examples
26+
27+
The *lease* directive supports all duration formats that Go supports. Thus, the following directive are all valid:
28+
29+
```
30+
lease 1h
31+
lease 1d3m
32+
lease 3m30s
33+
lease 1y10m3s
34+
```
35+
36+
An example could look like:
37+
38+
```
39+
192.168.0.1/24 {
40+
lease 1d
41+
}
42+
```

‎content/plugins/option.md

Lines changed: 137 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,137 @@
1+
---
2+
title: "option"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
# option
8+
9+
## Name
10+
11+
*option* - configures a DHCP option
12+
13+
## Description
14+
15+
The *option* plugin can be used to configure one or more DHCP options for clients
16+
requesting them. It provides some common names for well-known options but can
17+
also be used to configure custom DHCP options. See examples for more information.
18+
The *option* plugin may be used multiple times per server-block.
19+
20+
## Syntax
21+
22+
```
23+
option NAME VALUE...
24+
```
25+
26+
* **NAME** is the well-known name of the option. See below for a list of supported names.
27+
* **VALUE** one or more values for the option. The actual format of the value depends on the option name.
28+
29+
```
30+
option {
31+
NAME VALUE
32+
...
33+
}
34+
```
35+
36+
The *option* plugin allows multiple DHCP options to be configured at once by using a `{}` block add adding multiple NAME/VALUE pairs (one per line).
37+
38+
## Examples
39+
40+
```
41+
10.1.0.1/24 {
42+
option router 10.1.0.1 10.1.0.2
43+
option nameserver 10.1.0.1 10.1.0.2
44+
}
45+
```
46+
47+
The next example has the same effect as the above one but this time using
48+
only one *option* directive
49+
50+
```
51+
10.1.0.1/24 {
52+
option {
53+
router 10.1.0.1 10.1.0.2
54+
nameserver 10.1.0.1 10.1.0.2
55+
}
56+
}
57+
```
58+
59+
## Supported Names
60+
61+
### *router*
62+
63+
Configures default gateways. Expects one or more IP addresses.
64+
65+
```
66+
option router 10.1.0.1 10.1.0.2
67+
```
68+
69+
### *nameserver*
70+
71+
Configures the DNS servers. Expects one or more IP addresses.
72+
73+
```
74+
option nameserver 8.8.8.8 1.1.1.1
75+
```
76+
77+
### *ntp-server*
78+
79+
Configures the time servers to use by clients. Expectes on or more IP
80+
addresses.
81+
82+
```
83+
option ntp-server 1.2.3.4 10.1.1.1
84+
```
85+
86+
### *broadcast-address*
87+
88+
The boardcast address of the local network. Expects an IP address
89+
90+
```
91+
option broadcast-address 192.168.0.255
92+
```
93+
94+
### *netmask*
95+
96+
Configures the netmask of the local network. Expects the mask to be in IP address format.
97+
98+
```
99+
option netmask 255.255.255.0
100+
```
101+
102+
### *hostname*
103+
104+
Configures the hostname that should be used by the client
105+
106+
```
107+
option hostname myhostname
108+
```
109+
110+
### *domain-name*
111+
112+
Configures the domain-name that should be used by the client.
113+
114+
```
115+
option domain-name nextdhcp.io
116+
```
117+
118+
### *tftp-server-name*
119+
120+
This option is used to identify a TFTP server. (Option 66).
121+
122+
```
123+
option tftp-server-name tftp.nextdhcp.io
124+
```
125+
126+
### *tftp-server-addr*
127+
128+
This option sets the TFTP server address (150). Note that [RFC5859](https://tools.ietf.org/html/rfc5859)
129+
defines this option with a higher priority than the *tftp-server-name* (66) option.
130+
131+
### *filename*
132+
133+
The filename that should be loaded during PXE / network boot. (Option 67)
134+
135+
```
136+
option filename pxe.0
137+
```

‎content/plugins/ranges.md

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: "range"
3+
date: 2019-09-20T19:00:00+02:00
4+
draft: false
5+
---
6+
7+
# range
8+
9+
## Name
10+
11+
*range* - configure a range of IP address to be leased
12+
13+
## Description
14+
15+
The *range* plugin allows to dynamically lease IP addresses to requesting clients. Each client requesting
16+
will be assigned an IP address from one of the configured ranges. If the client has already been assigned
17+
an address (i.e. in RENEWING state) it will get the very same address assigned. If the `range` plugin is
18+
not able to find a suitable address the next plugin will be called. Typically, the `range` plugin should
19+
be one of the last plugins used. This plugin may be specified multiple times per DHCP server block.
20+
21+
## Syntax
22+
23+
```
24+
range START_IP END_IP
25+
```
26+
27+
* **START_IP** is the (inclusive) start IP of the range (like `192.168.0.1`)
28+
* **END_IP** is the (inclusive) end IP of the range (like `192.168.0.100`)
29+
30+
## Examples
31+
32+
The following example allows dynamic clients to receive IP addresses from two different pools:
33+
34+
```
35+
192.168.0.1/24 {
36+
range 192.168.0.100 192.168.0.150
37+
range 192.168.0.200 192.168.0.250
38+
}
39+
```

0 commit comments

Comments
 (0)