mirror/stackexchange-dnscontrol
1
0
Fork 0
mirror of https://github.com/StackExchange/dnscontrol.git synced 2024-05-11 05:55:12 +00:00
Code Issues Releases Activity

NEW FEATURE: Support DNS LOC record type (#2174)

Browse Source
This commit is contained in:
Paul Dee
2023-03-16 19:04:20 +01:00
committed by GitHub
parent 31765b0bef
commit 3b6591fd95
57 changed files with 1554 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
documentation/functions/domain/LOC.md Normal file
View File

@ -0,0 +1,103 @@
---
name: LOC
parameters:
- deg1
- min1
- sec1
- deg2
- min2
- sec2
- altitude
- size
- horizontal_precision
- vertical_precision
parameter_types:
name: string
target: string
deg1: uint32
min1: uint32
sec1: float32
deg2: uint32
min2: uint32
sec2: float32
altitude: uint32
size: float32
horizontal_precision: float32
vertical_precision: float32
---
## Description ##
Strictly follows [RFC 1876](https://datatracker.ietf.org/doc/html/rfc1876).
A LOC record holds a geographical position. In the zone file, it may look like:
```text
;
pipex.net. LOC 52 14 05 N 00 08 50 E 10m
```
On the wire, it is in a binary format.
A use case for LOC is suggested in the RFC:
> Some uses for the LOC RR have already been suggested, including the
USENET backbone flow maps, a "visual traceroute" application showing
the geographical path of an IP packet, and network management
applications that could use LOC RRs to generate a map of hosts and
routers being managed.
There is the UK based [https://find.me.uk](https://find.me.uk/) whereby you can do:
```sh
dig loc <uk-postcode>.find.me.uk
```
There are some behaviours that you should be aware of, however:
> If omitted, minutes and seconds default to zero, size defaults to 1m,
horizontal precision defaults to 10000m, and vertical precision
defaults to 10m. These defaults are chosen to represent typical
ZIP/postal code area sizes, since it is often easy to find
approximate geographical location by ZIP/postal code.
Alas, the world does not revolve around US ZIP codes, but here we are. Internally,
the LOC record type will supply defaults where values were absent on DNS import.
One must supply the `LOC()` js helper all parameters. If that seems like too
much work, see also helper functions:
* [`LOC_BUILDER_DD()`](../record/LOC_BUILDER_DD.md) - build a `LOC` by supplying only **d**ecimal **d**egrees.
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
* [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries LOC_BUILDER_DM*STR()
## Format ##
The coordinate format for `LOC()` is:
`degrees,minutes,seconds,[NnSs],deg,min,sec,[EeWw],altitude,size,horizontal_precision,vertical_precision`
## Examples ##
{% code title="dnsconfig.js" %}
```javascript
D("foo.com","none"
// LOC "subdomain", d1, m1, s1, "[NnSs]", d2, m2, s2, "[EeWw]", alt, siz, hp, vp)
//42 21 54 N 71 06 18 W -24m 30m
, LOC("@", 42, 21, 54, "N", 71, 6, 18, "W", -24, 30, 0, 0)
//42 21 43.952 N 71 5 6.344 W -24m 1m 200m 10m
, LOC("a", 42, 21, 43.952, "N", 71, 5, 6.344, "W", -24, 1, 200, 10)
//52 14 05 N 00 08 50 E 10m
, LOC("b", 52, 14, 5, "N", 0, 8, 50, "E", 10, 0, 0, 0)
//32 7 19 S 116 2 25 E 10m
, LOC("c", 32, 7, 19, "S",116, 2, 25, "E", 10, 0, 0, 0)
//42 21 28.764 N 71 00 51.617 W -44m 2000m
, LOC("d", 42, 21, 28.764, "N", 71, 0, 51.617, "W", -44, 2000, 0, 0)
);
```
{% endcode %}

68
documentation/functions/record/LOC_BUILDER_DD.md Normal file
View File

@ -0,0 +1,68 @@
---
name: LOC_BUILDER_DD
parameters:
- subdomain
- decimal_degrees_x
- decimal_degrees_y
- altitude
- ttl
parameter_types:
subdomain: string
decimal_degrees_x: float32
decimal_degrees_y: float32
altitude: float32
ttl: int
---
`LOC_BUILDER_DD({})` actually takes an object with the mentioned properties.
A helper to build [`LOC`](../domain/LOC.md) records. Supply four parameters instead of 12.
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
The cartesian coordinates are decimal degrees, like you typically find in e.g. Google Maps.
Examples.
Big Ben:
`51.50084265331501, -0.12462541415599787`
The White House:
`38.89775977858357, -77.03655125982903`
{% code title="dnsconfig.js" %}
```javascript
D("example.com","none"
, LOC_BUILDER_DD({
label: "big-ben",
x: 51.50084265331501,
y: -0.12462541415599787,
alt: 6,
})
, LOC_BUILDER_DD({
label: "white-house",
x: 38.89775977858357,
y: -77.03655125982903,
alt: 19,
})
, LOC_BUILDER_DD({
label: "white-house-ttl",
x: 38.89775977858357,
y: -77.03655125982903,
alt: 19,
ttl: "5m",
})
);
```
{% endcode %}
Part of the series:
* [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
* [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries LOC_BUILDER_DM*STR()

49
documentation/functions/record/LOC_BUILDER_DMM_STR.md Normal file
View File

@ -0,0 +1,49 @@
---
name: LOC_BUILDER_DMM
parameters:
- subdomain
- input_string
- altitude
- ttl
parameter_types:
subdomain: string
input_string: string
altitude: float32
ttl: int
---
`LOC_BUILDER_DMM({})` actually takes an object with the mentioned properties.
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
Accepts a string with decimal minutes (DMM) coordinates in the form: 25.24°S 153.15°E
Note that the following are acceptable forms (symbols differ):
* `25.24°S 153.15°E`
* `25.24 S 153.15 E`
* `25.24° S 153.15° E`
* `25.24S 153.15E`
{% code title="dnsconfig.js" %}
```javascript
D("example.com","none"
LOC_BUILDER_STR({
label: "tasmania",
str: '42°S 147°E',
alt: 3,
})
);
```
{% endcode %}
Part of the series:
* [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
* [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries LOC_BUILDER_DM*STR()

50
documentation/functions/record/LOC_BUILDER_DMS_STR.md Normal file
View File

@ -0,0 +1,50 @@
---
name: LOC_BUILDER_DMS_STR
parameters:
- subdomain
- input_string
- altitude
- ttl
parameter_types:
subdomain: string
input_string: string
altitude: float32
ttl: int
---
`LOC_BUILDER_DMS_STR({})` actually takes an object with the mentioned properties.
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
Accepts a string with degrees, minutes, and seconds (DMS) coordinates in the form: 41°24'12.2"N 2°10'26.5"E
Note that the following are acceptable forms (symbols differ):
* `33°51′31″S 151°12′51″E`
* `33°51'31"S 151°12'51"E`
* `33d51m31sS 151d12m51sE`
* `33d51m31s S 151d12m51s E`
{% code title="dnsconfig.js" %}
```javascript
D("example.com","none"
LOC_BUILDER_DMS_STR({
label: "sydney-opera-house",
str: '33°51′31″S 151°12′51″E',
alt: 4,
ttl: "5m",
})
);
```
{% endcode %}
Part of the series:
* [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
* [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries LOC_BUILDER_DM*STR()

57
documentation/functions/record/LOC_BUILDER_STRING.md Normal file
View File

@ -0,0 +1,57 @@
---
name: LOC_BUILDER_STR
parameters:
- subdomain
- input_string
- altitude
- ttl
parameter_types:
subdomain: string
input_string: string
altitude: float32
ttl: int
---
`LOC_BUILDER_STR({})` actually takes an object with the mentioned properties.
A helper to build [`LOC`](../domain/LOC.md) records. Supply three parameters instead of 12.
Internally assumes some defaults for [`LOC`](../domain/LOC.md) records.
Accepts a string and tries all `LOC_BUILDER_DM*_STR({})` methods:
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
{% code title="dnsconfig.js" %}
```javascript
D("example.com","none"
, LOC_BUILDER_STR({
label: "old-faithful",
str: '44.46046°N 110.82815°W',
alt: 2240,
})
, LOC_BUILDER_STR({
label: "ribblehead-viaduct",
str: '54.210436°N 2.370231°W',
alt: 300,
})
, LOC_BUILDER_STR({
label: "guinness-brewery",
str: '53°20′40″N 6°17′20″W',
alt: 300,
})
);
```
{% endcode %}
Part of the series:
* [`LOC()`](LOC.md) - build a `LOC` by supplying all 12 parameters
* [`LOC_BUILDER_DD({})`](../record/LOC_BUILDER_DD.md) - accepts cartesian x, y
* [`LOC_BUILDER_DMS_STR({})`](LOC_BUILDER_DMS_STR.md) - accepts DMS 33°51′31″S 151°12′51″E
* [`LOC_BUILDER_DMM_STR({})`](LOC_BUILDER_DMM_STR.md) - accepts DMM 25.24°S 153.15°E
* [`LOC_BUILDER_STR({})`](LOC_BUILDER_STR.md) - tries LOC_BUILDER_DM*STR()