Skip to content

Commit f543aa6

Browse files
author
dougbw
committed
fallthrough documentation and confi
1 parent 6c5a10b commit f543aa6

File tree

8 files changed

+53
-26
lines changed

8 files changed

+53
-26
lines changed

‎Corefile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
password {$OMADA_PASSWORD}
88
refresh_minutes 1
99
ignore_startup_errors {$OMADA_IGNORE_STARTUP_ERRORS}
10+
fallthrough ${FALLTHROUGH_ZONES}
1011
}
1112
forward . {$UPSTREAM_DNS}
1213
}

‎Dockerfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,4 +43,5 @@ COPY --from=builder /coredns/coredns /coredns
4343
COPY Corefile /Corefile
4444
EXPOSE 53 53/udp
4545
ENV OMADA_IGNORE_STARTUP_ERRORS=FALSE
46+
ENV FALLTHROUGH_ZONES="disabled"
4647
ENTRYPOINT ["/coredns"]

‎config.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ type config struct {
2121
resolve_dhcp_reservations bool // resolve static 'dhcp reservations'
2222
stale_record_duration time.Duration // duration to keep serving stale records for clients no longer present in the controller)
2323
ignore_startup_errors bool // ignore any errors during the initial zone refresh
24-
fall *[]string // fallthrough to the next plugin if no records found for a query
24+
fallthrough_zones *[]string // list of fallthrough zones
2525
}
2626

2727
func parse(c *caddy.Controller) (config config, err error) {
@@ -129,7 +129,7 @@ func parse(c *caddy.Controller) (config config, err error) {
129129

130130
case "fallthrough":
131131
fallthroughZones := c.RemainingArgs()
132-
config.fall = &fallthroughZones
132+
config.fallthrough_zones = &fallthroughZones
133133
if err != nil {
134134
return config, c.ArgErr()
135135
}

‎corefile-examples/fallthrough/Corefile‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
. {
2+
health :8080
3+
omada {
4+
controller_url https://10.0.0.2
5+
site Home
6+
username coredns-omada
7+
password coredns-omada
8+
refresh_minutes 1
9+
fallthrough
10+
}
11+
forward . 10.0.0.1
12+
}

‎docs/configuration.md‎

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -7,20 +7,20 @@ Example corefiles are located [here](../corefile-examples)
77

88
## Omada plugin configuration syntax
99

10-
| Name | Required | Type | Notes |
11-
|---------------------------|----------|----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
12-
| controller_url | ✅ | string | address of the Omada controller. Include `https://` prefix |
13-
| site | ✅ | string | name of the site from the Omada controller (note this is a regex pattern) |
14-
| username | ✅ | string | Omada controller username |
15-
| password | ✅ | string | Omada controller password |
16-
| refresh_minutes | ❌ | int | How often to refresh the zones (default 1 minute) |
17-
| refresh_login_hours | ❌ | int | How often to refresh the login token (default 24 hours) |
18-
| resolve_clients | ❌ | bool | Whether to resolve client addresses (default true) |
19-
| resolve_devices | ❌ | bool | Whether to resolve device addresses (default true) |
20-
| resolve_dhcp_reservations | ❌ | bool | Whether to resolve device addresses (default true) |
10+
| Name | Required | Type | Notes |
11+
| ------------------------- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
12+
| controller_url | ✅ | string | address of the Omada controller. Include `https://` prefix |
13+
| site | ✅ | string | name of the site from the Omada controller (note this is a regex pattern) |
14+
| username | ✅ | string | Omada controller username |
15+
| password | ✅ | string | Omada controller password |
16+
| refresh_minutes | ❌ | int | How often to refresh the zones (default 1 minute) |
17+
| refresh_login_hours | ❌ | int | How often to refresh the login token (default 24 hours) |
18+
| resolve_clients | ❌ | bool | Whether to resolve client addresses (default true) |
19+
| resolve_devices | ❌ | bool | Whether to resolve device addresses (default true) |
20+
| resolve_dhcp_reservations | ❌ | bool | Whether to resolve device addresses (default true) |
2121
| stale_record_duration | ❌ | duration | How long to keep serving stale records for clients/devices which are no longer present in the Omada controller. Specified in Go time [duration](https://pkg.go.dev/time#ParseDuration) format |
22-
| ignore_startup_errors | ❌ | bool | ignore connection/configuration errors to the omada controller on startup. Set this to true if you want coredns to startup even if unable to connect to omada (default false) |
23-
22+
| ignore_startup_errors | ❌ | bool | ignore connection/configuration errors to the omada controller on startup. Set this to true if you want coredns to startup even if unable to connect to omada (default false) |
23+
| fallthrough [ZONES...] | ❌ | []string | Whether to enable fallthrough. If fallthrough statement is present but no zone is specified then defaults to all zones, equivilent to:<br> `fallthrough .` |
2424

2525
## Credentials
2626

@@ -30,6 +30,14 @@ For this service you should create a new user in the `Admin` page of the control
3030

3131
A single Omada controller can support multiple network sites. This plugin can be configured to use multiple sites via the `site` configuration property (regex). Multiple sites can be specified using the `|` separator like this `SiteA|SiteB|SiteC` or all sites can be selected by setting it to `.*`
3232

33+
## Fallthrough behaviour
34+
35+
The `fallthrough` option controls the behaviour for records which are not found. If fallthrough is enabled then requests for records which are not found are passed to the next plugin in the chain. If fallthrough is disabled then records which are not found are returned an `NXDOMAIN` response by the coredns_omada plugin and processing stops without being passed down the plugin chain.
36+
37+
The use case for using fallthrough is to use other plugins to handle queries for the same zone as `coredns_omada` such as the [file](https://coredns.io/plugins/file/) plugin.
38+
39+
Note: prior to the fallthrough option being implemented, the default behaviour enabled fallthrough.
40+
3341
## HTTPS Verification
3442

3543
This will depend on your network and configuration, but due to the lack of a suitable internal DNS resolution you may need to disable HTTPS verification to the controller, as even if you have a valid certificate on your controller you need a valid DNS record pointing to your controller where coredns is running.

‎docs/getting-started.md‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,9 +27,9 @@ CoreDNS plugins need to be compiled into CoreDNS, you can follow the [build](bui
2727

2828
This guide provides three options on how to run CoreDNS:
2929

30-
- [CoreDNS binary](#coredns-binary)
31-
- [Docker container](#docker)
32-
- [Kubernetes](#kubernetes)
30+
- [CoreDNS binary](#coredns-binary)
31+
- [Docker](#docker)
32+
- [Kubernetes](#kubernetes)
3333

3434
### CoreDNS binary
3535

@@ -52,8 +52,13 @@ Note: If you do not have a valid https certificate on your controller then set t
5252
* `OMADA_PASSWORD`
5353
* `UPSTREAM_DNS`
5454

55+
The pre-built images support these optional environment variables:
56+
* `OMADA_IGNORE_STARTUP_ERRORS` = `true` | `false`
57+
* `FALLTHROUGH_ZONES` - defaults to a fake zone `disabled` to disable it. Set to `.` to enable fallthrough for all zones.
58+
5559
Note: If you do not have a valid https certificate on your controller then set the `OMADA_DISABLE_HTTPS_VERIFICATION` environment variable to true
5660

61+
5762
Example docker run command:
5863
```
5964
docker run \

‎omada.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ func (o *Omada) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg)
4949
qtype := state.QType()
5050
log.Debugf("query; type: %d, name: %s\n", qtype, qname)
5151

52-
// this plugin can only handle 'A' and 'PTR' queries
52+
// this plugin can only handle 'A', 'PTR' and 'SOA' queries
5353
var qzone string
5454
switch qtype {
5555
case 1: // A
@@ -92,19 +92,19 @@ func (o *Omada) ServeDNS(ctx context.Context, w dns.ResponseWriter, r *dns.Msg)
9292
case file.Success:
9393
case file.NoData:
9494
case file.NameError:
95+
log.Debugf("-- RcodeNameError")
9596
m.Rcode = dns.RcodeNameError
9697
case file.Delegation:
9798
m.Authoritative = false
9899
case file.ServerFailure:
99-
log.Debugf("RcodeServerFailure")
100+
log.Debugf("-- RcodeServerFailure")
100101
return dns.RcodeServerFailure, nil
101102
}
102103
err := w.WriteMsg(m)
103104
if err != nil {
104-
log.Debugf("-- error writing message: %v\n", err)
105+
log.Debugf("-- error writing message: %v\n", err)
105106
return dns.RcodeServerFailure, err
106107
}
107-
log.Debugf("-- message written successfully\n")
108108
return dns.RcodeSuccess, nil
109109
}
110110

‎setup.go‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,8 @@ func setup(c *caddy.Controller) error {
3535
var fall fall.F
3636

3737
// check if fallthrough pointer is nil
38-
if o.config.fall != nil {
39-
fall.SetZonesFromArgs(*o.config.fall)
38+
if o.config.fallthrough_zones != nil {
39+
fall.SetZonesFromArgs(*o.config.fallthrough_zones)
4040
o.Fall = fall
4141
}
4242

@@ -77,10 +77,10 @@ func (o *Omada) login() error {
7777
func (o *Omada) controllerInit(ctx context.Context) error {
7878

7979
log.Info("starting initial omada setup...")
80-
if o.config.fall == nil {
80+
if o.config.fallthrough_zones == nil {
8181
log.Debug("fallthrough disabled")
8282
} else {
83-
log.Debug("fallthrough zones are enabled: ", o.Fall.Zones)
83+
log.Debug("fallthrough zones: ", o.Fall.Zones)
8484
}
8585

8686
const retrySeconds = 15

0 commit comments

Comments
 (0)
⚡