acme_proxy/config/types/ipam.rs
1//! `[ipam]` — the IP address management inventory this endpoint consults.
2//!
3//! Re-exported flat from [`super`], so nothing outside this directory names
4//! the submodule.
5
6use serde::Deserialize;
7
8use super::empty_string_is_no_values;
9
10/// Which inventory answers "which names does this address own?", and how long
11/// it is given to answer.
12///
13/// Per-profile, so two endpoints may consult different inventories — but the
14/// *policy* built on the answer is the `ipam` filter's, not this section's.
15/// Nothing here is read unless `ipam` appears in `filter.enabled`.
16#[derive(Debug, Clone, Deserialize)]
17#[serde(default)]
18pub struct IpamConfig {
19 /// `netbox`, `phpipam`, `custom`, or empty for no inventory at all.
20 /// Anything else is a startup error rather than a silent fallback.
21 pub backend: String,
22 /// Budget for one whole lookup, however many requests the backend makes to
23 /// answer it. Applied by the registry rather than by each backend, so a
24 /// backend added later cannot forget it. This runs inline in `newOrder`
25 /// and `finalize`, so it is part of those requests' worst case.
26 pub timeout_ms: u64,
27 pub netbox: NetboxConfig,
28 pub phpipam: PhpIpamConfig,
29 pub custom: CustomIpamConfig,
30}
31
32impl Default for IpamConfig {
33 fn default() -> Self {
34 Self {
35 backend: String::new(),
36 timeout_ms: 5000,
37 netbox: NetboxConfig::default(),
38 phpipam: PhpIpamConfig::default(),
39 custom: CustomIpamConfig::default(),
40 }
41 }
42}
43
44/// The default `sources` both backends ship with: the address object's own
45/// name, the custom field on it, and that same field on the machine it is
46/// assigned to.
47///
48/// Exactly the behaviour of the `netbox` filter before it became an IPAM
49/// backend, so an existing deployment that moves its section across sees no
50/// change. The two service-address sources are deliberately *not* here: both
51/// widen what a client may certify, and widening is opted into.
52fn default_sources() -> Vec<String> {
53 vec![
54 "dns_name".to_string(),
55 "custom_field".to_string(),
56 "device".to_string(),
57 ]
58}
59
60/// Configuration for the `netbox` IPAM backend.
61///
62/// `token` is a secret, so it belongs in `ACME_PROXY_IPAM__NETBOX__TOKEN`
63/// rather than in a file on disk — the same advice
64/// [`super::signer::Rfc2136Config::tsig_key_secret`] carries.
65#[derive(Debug, Clone, Deserialize)]
66#[serde(default)]
67pub struct NetboxConfig {
68 /// Base URL of the NetBox instance, e.g. `https://netbox.example.com`. Any
69 /// path is kept, so an instance served under a subpath works.
70 pub url: String,
71 /// NetBox API token, sent as `Authorization: Token <token>`.
72 pub token: String,
73 /// Custom field, on the IP address or on its device/VM, holding the extra
74 /// names that address may have certified.
75 pub custom_field: String,
76 /// Which places a permitted name may come from. Empty, or an unknown
77 /// entry, is a startup error; order is meaningless, since the result is a
78 /// union. See [`crate::ipam::Source`].
79 #[serde(deserialize_with = "empty_string_is_no_values")]
80 pub sources: Vec<String>,
81 /// Which NetBox address roles count as a service address for the `vip`
82 /// source. Read only when `vip` is in `sources`, so this is *which* roles
83 /// rather than whether to look at all.
84 #[serde(deserialize_with = "empty_string_is_no_values")]
85 pub vip_roles: Vec<String>,
86 /// Extra CA certificates (PEM) to trust on top of the public roots, for a
87 /// NetBox behind an internal PKI. Ignored when `insecure_skip_verify` is on.
88 pub ca_cert_path: String,
89 /// Skip verification of NetBox's TLS certificate entirely.
90 ///
91 /// Off by default and meant as a temporary way out of an expired NetBox
92 /// certificate: with it on, the answers this backend trusts could come from
93 /// anyone able to intercept the connection. Startup logs a warning for as
94 /// long as it is set.
95 pub insecure_skip_verify: bool,
96}
97
98impl Default for NetboxConfig {
99 fn default() -> Self {
100 Self {
101 url: String::new(),
102 token: String::new(),
103 custom_field: "acme_allowed_names".to_string(),
104 sources: default_sources(),
105 // The roles NetBox itself offers for a shared address. Listing them
106 // all is not a widening: nothing is queried at all unless `vip` is
107 // in `sources`.
108 vip_roles: vec![
109 "vip".to_string(),
110 "vrrp".to_string(),
111 "hsrp".to_string(),
112 "glbp".to_string(),
113 "carp".to_string(),
114 "anycast".to_string(),
115 ],
116 ca_cert_path: String::new(),
117 insecure_skip_verify: false,
118 }
119 }
120}
121
122/// Configuration for the `phpipam` IPAM backend.
123///
124/// `token` is the application's static app code and is a secret, so it belongs
125/// in `ACME_PROXY_IPAM__PHPIPAM__TOKEN`.
126#[derive(Debug, Clone, Deserialize)]
127#[serde(default)]
128pub struct PhpIpamConfig {
129 /// Base URL of the phpIPAM instance, e.g. `https://ipam.example.com`. Any
130 /// path is kept, so an instance served under a subpath works.
131 pub url: String,
132 /// The API application's identifier, the `<app_id>` in every phpIPAM API
133 /// path. Created in phpIPAM under Administration → API.
134 pub app_id: String,
135 /// The application's app code, sent as a `token` header.
136 pub token: String,
137 /// Custom field on the address (and, for the `device` source, on the
138 /// device) holding the extra names it may have certified. phpIPAM prefixes
139 /// custom columns with `custom_`, so the default carries that prefix.
140 pub custom_field: String,
141 /// Which places a permitted name may come from. phpIPAM records no
142 /// redundancy groups, so `vip` and `fhrp` are refused here by name rather
143 /// than quietly ignored.
144 #[serde(deserialize_with = "empty_string_is_no_values")]
145 pub sources: Vec<String>,
146 /// Extra CA certificates (PEM) to trust on top of the public roots.
147 /// Ignored when `insecure_skip_verify` is on.
148 pub ca_cert_path: String,
149 /// Skip verification of phpIPAM's TLS certificate entirely. The
150 /// counterpart of [`NetboxConfig::insecure_skip_verify`], warned about at
151 /// startup for as long as it is set.
152 pub insecure_skip_verify: bool,
153}
154
155impl Default for PhpIpamConfig {
156 fn default() -> Self {
157 Self {
158 url: String::new(),
159 app_id: "acme".to_string(),
160 token: String::new(),
161 custom_field: "custom_acme_allowed_names".to_string(),
162 sources: default_sources(),
163 ca_cert_path: String::new(),
164 insecure_skip_verify: false,
165 }
166 }
167}
168
169/// Configuration for the `custom` IPAM backend.
170///
171/// The one backend with no URL, no credential and no `sources`: the script is
172/// the inventory, and it decides for itself where its answer comes from. It
173/// also takes no `timeout_ms` of its own — [`IpamConfig::timeout_ms`] is the
174/// budget the whole lookup runs under, and a second one here would contradict
175/// the "one budget however many requests it takes" rule the other two follow.
176#[derive(Debug, Clone, Default, Deserialize)]
177#[serde(default)]
178pub struct CustomIpamConfig {
179 /// Path to the executable answering "which names does this address own?".
180 /// Empty while `backend = "custom"` is a startup error.
181 pub script_path: String,
182 /// Fixed arguments passed to the script before it is told anything about
183 /// the request, which travels in the environment and on stdin.
184 #[serde(deserialize_with = "empty_string_is_no_values")]
185 pub args: Vec<String>,
186}