From 83a16e3debd113a91f5c54d80b0d379c9ef8bfba Mon Sep 17 00:00:00 2001
From: Martin Atkins <mart@degeneration.co.uk>
Date: Sun, 13 May 2018 14:11:13 -0700
Subject: [PATCH] website: Docs for all of the IP address calculation functions

---
 .../configuration/functions/cidrhost.html.md  | 43 +++++++++++++++++
 .../functions/cidrnetmask.html.md             | 33 +++++++++++++
 .../functions/cidrsubnet.html.md              | 48 +++++++++++++++++++
 3 files changed, 124 insertions(+)
 create mode 100644 website/docs/configuration/functions/cidrhost.html.md
 create mode 100644 website/docs/configuration/functions/cidrnetmask.html.md
 create mode 100644 website/docs/configuration/functions/cidrsubnet.html.md

diff --git a/website/docs/configuration/functions/cidrhost.html.md b/website/docs/configuration/functions/cidrhost.html.md
new file mode 100644
index 000000000..d8fe66503
--- /dev/null
+++ b/website/docs/configuration/functions/cidrhost.html.md
@@ -0,0 +1,43 @@
+---
+layout: "functions"
+page_title: "cidrhost function"
+sidebar_current: "docs-funcs-ipnet-cidrhost"
+description: |-
+  The cidrhost function calculates a full host IP address within a given
+  IP network address prefix.
+---
+
+# `cidrhost` Function
+
+`cidrhost` calculates a full host IP address for a given host number within
+a given IP network address prefix.
+
+```hcl
+cidrhost(prefix, hostnum)
+```
+
+`prefix` must be given in CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+`hostnum` is a whole number that can be represented as a binary integer with
+no more than the number of digits remaining in the address after the given
+prefix.
+
+This function accepts both IPv6 and IPv4 prefixes, and the result always uses
+the same addressing scheme as the given prefix.
+
+## Examples
+
+```
+> cidrhost("10.12.127.0/20", 16)
+10.12.112.16
+> cidrhost("10.12.127.0/20", 268)
+10.12.113.12
+> cidrhost("fd00:fd12:3456:7890:00a2::/72", 34)
+fd00:fd12:3456:7890::22
+```
+
+## Related Functions
+
+* [`cidrsubnet`](./cidrsubnet.html) calculates a subnet address under a given
+  network address prefix.
diff --git a/website/docs/configuration/functions/cidrnetmask.html.md b/website/docs/configuration/functions/cidrnetmask.html.md
new file mode 100644
index 000000000..6b2b16dc8
--- /dev/null
+++ b/website/docs/configuration/functions/cidrnetmask.html.md
@@ -0,0 +1,33 @@
+---
+layout: "functions"
+page_title: "cidrnetmask function"
+sidebar_current: "docs-funcs-ipnet-cidrnetmask"
+description: |-
+  The cidrnetmask function converts an IPv4 address prefix given in CIDR
+  notation into a subnet mask address.
+---
+
+# `cidrnetmask` Function
+
+`cidrnetmask` converts an IPv4 address prefix given in CIDR notation into
+a subnet mask address.
+
+```hcl
+cidrnetmask(prefix)
+```
+
+`prefix` must be given in IPv4 CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+The result is a subnet address formatted in the conventional dotted-decimal
+IPv4 address syntax, as expected by some software.
+
+CIDR notation is the only valid notation for IPv6 addresses, so `cidrnetmask`
+produces an error if given an IPv6 address.
+
+## Examples
+
+```
+> cidrnetmask("172.16.0.0/12")
+255.240.0.0
+```
diff --git a/website/docs/configuration/functions/cidrsubnet.html.md b/website/docs/configuration/functions/cidrsubnet.html.md
new file mode 100644
index 000000000..34a9c994d
--- /dev/null
+++ b/website/docs/configuration/functions/cidrsubnet.html.md
@@ -0,0 +1,48 @@
+---
+layout: "functions"
+page_title: "cidrsubnet function"
+sidebar_current: "docs-funcs-ipnet-cidrsubnet"
+description: |-
+  The cidrsubnet function calculates a subnet address within a given IP network
+  address prefix.
+---
+
+# `cidrsubnet` Function
+
+`cidrhost` calculates a subnet address within given IP network address prefix.
+
+```hcl
+cidrsubnet(prefix, newbits, netnum)
+```
+
+`prefix` must be given in CIDR notation, as defined in
+[RFC 4632 section 3.1](https://tools.ietf.org/html/rfc4632#section-3.1).
+
+`newbits` is the number of additional bits with which to extend the prefix.
+For example, if given a prefix ending in `/16` and a `newbits` value of
+`4`, the resulting subnet address will have length `/20`.
+
+`netnum` is a whole number that can be represented as a binary integer with
+no more than `newbits` binary digits, which will be used to populate the
+additional bits added to the prefix.
+
+This function accepts both IPv6 and IPv4 prefixes, and the result always uses
+the same addressing scheme as the given prefix.
+
+## Examples
+
+```
+> cidrsubnet("172.16.0.0/12", 4, 2)
+172.18.0.0/16
+> cidrsubnet("10.1.2.0/24", 4, 15)
+10.1.2.240/28
+> cidrsubnet("fd00:fd12:3456:7890::/56", 16, 162)
+fd00:fd12:3456:7800:a200::/72
+```
+
+## Related Functions
+
+* [`cidrhost`](./cidrhost.html) calculates the IP address for a single host
+  within a given network address prefix.
+* [`cidrnetmask`](./cidrnetmask.html) converts an IPv4 network prefix in CIDR
+  notation into netmask notation.