Skip to content

Commit d24dd38

Browse files
stgraberstgraber
authored
Merge pull request #1956 from rahafjrw/port-nic-gendoc
Port nic device documentation to gendoc
2 parents 8286f4e + 7dd7464 commit d24dd38

File tree

11 files changed

+2941
-144
lines changed

11 files changed

+2941
-144
lines changed

‎doc/config_options.txt

Lines changed: 928 additions & 0 deletions
Large diffs are not rendered by default.

‎doc/reference/devices_nic.md

Lines changed: 40 additions & 144 deletions
Large diffs are not rendered by default.

‎internal/server/device/nic_bridged.go

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,34 +72,249 @@ func (d *nicBridged) validateConfig(instConf instance.ConfigReader) error {
7272

7373
var requiredFields []string
7474
optionalFields := []string{
75+
// gendoc:generate(entity=devices, group=nic_bridged, key=name)
76+
//
77+
// ---
78+
// type: string
79+
// default: kernel assigned
80+
// managed: no
81+
// shortdesc: The name of the interface inside the instance
7582
"name",
83+
84+
// gendoc:generate(entity=devices, group=nic_bridged, key=network)
85+
//
86+
// ---
87+
// type: string
88+
// managed: no
89+
// shortdesc: The managed network to link the device to (instead of specifying the `nictype` directly)
7690
"network",
91+
92+
// gendoc:generate(entity=devices, group=nic_bridged, key=parent)
93+
//
94+
// ---
95+
// type: string
96+
// managed: yes
97+
// shortdesc: The name of the parent host device (required if specifying the `nictype` directly)
7798
"parent",
99+
100+
// gendoc:generate(entity=devices, group=nic_bridged, key=mtu)
101+
//
102+
// ---
103+
// type: integer
104+
// default: MTU of the parent device
105+
// managed: yes
106+
// shortdesc: The Maximum Transmit Unit (MTU) of the new interface
78107
"mtu",
108+
109+
// gendoc:generate(entity=devices, group=nic_bridged, key=queue.tx.length)
110+
//
111+
// ---
112+
// type: integer
113+
// managed: no
114+
// shortdesc: The transmit queue length for the NIC
79115
"queue.tx.length",
116+
117+
// gendoc:generate(entity=devices, group=nic_bridged, key=hwaddr)
118+
//
119+
// ---
120+
// type: string
121+
// default: randomly assigned
122+
// managed: no
123+
// shortdesc: The MAC address of the new interface
80124
"hwaddr",
125+
126+
// gendoc:generate(entity=devices, group=nic_bridged, key=host_name)
127+
//
128+
// ---
129+
// type: string
130+
// default: randomly assigned
131+
// managed: no
132+
// shortdesc: The name of the interface on the host
81133
"host_name",
134+
135+
// gendoc:generate(entity=devices, group=nic_bridged, key=limits.ingress)
136+
//
137+
// ---
138+
// type: string
139+
// managed: no
140+
// shortdesc: I/O limit in bit/s for incoming traffic (various suffixes supported, see {ref}instances-limit-units)
82141
"limits.ingress",
142+
143+
// gendoc:generate(entity=devices, group=nic_bridged, key=limits.egress)
144+
//
145+
// ---
146+
// type: string
147+
// managed: no
148+
// shortdesc: I/O limit in bit/s for outgoing traffic (various suffixes supported, see {ref}instances-limit-units)
83149
"limits.egress",
150+
151+
// gendoc:generate(entity=devices, group=nic_bridged, key=limits.max)
152+
//
153+
// ---
154+
// type: string
155+
// managed: no
156+
// shortdesc: I/O limit in bit/s for both incoming and outgoing traffic (same as setting both limits.ingress and limits.egress)
84157
"limits.max",
158+
159+
// gendoc:generate(entity=devices, group=nic_bridged, key=limits.priority)
160+
//
161+
// ---
162+
// type: integer
163+
// managed: no
164+
// shortdesc: The priority for outgoing traffic, to be used by the kernel queuing discipline to prioritize network packets
85165
"limits.priority",
166+
167+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv4.address)
168+
//
169+
// ---
170+
// type: string
171+
// managed: no
172+
// shortdesc: An IPv4 address to assign to the instance through DHCP (can be `none` to restrict all IPv4 traffic when `security.ipv4_filtering` is set)
86173
"ipv4.address",
174+
175+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv6.address)
176+
//
177+
// ---
178+
// type: string
179+
// managed: no
180+
// shortdesc: An IPv6 address to assign to the instance through DHCP (can be `none` to restrict all IPv6 traffic when `security.ipv6_filtering` is set)
87181
"ipv6.address",
182+
183+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv4.routes)
184+
//
185+
// ---
186+
// type: string
187+
// managed: no
188+
// shortdesc: Comma-delimited list of IPv4 static routes to add on host to NIC
88189
"ipv4.routes",
190+
191+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv6.routes)
192+
//
193+
// ---
194+
// type: string
195+
// managed: no
196+
// shortdesc: Comma-delimited list of IPv6 static routes to add on host to NIC
89197
"ipv6.routes",
198+
199+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv4.routes.external)
200+
//
201+
// ---
202+
// type: string
203+
// managed: no
204+
// shortdesc: Comma-delimited list of IPv4 static routes to route to the NIC and publish on uplink network (BGP)
90205
"ipv4.routes.external",
206+
207+
// gendoc:generate(entity=devices, group=nic_bridged, key=ipv6.routes.external)
208+
//
209+
// ---
210+
// type: string
211+
// managed: no
212+
// shortdesc: Comma-delimited list of IPv6 static routes to route to the NIC and publish on uplink network (BGP)
91213
"ipv6.routes.external",
214+
215+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.mac_filtering)
216+
//
217+
// ---
218+
// type: bool
219+
// default: false
220+
// managed: no
221+
// shortdesc: Prevent the instance from spoofing another instance's MAC address
92222
"security.mac_filtering",
223+
224+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.ipv4_filtering)
225+
//
226+
// ---
227+
// type: bool
228+
// default: false
229+
// managed: no
230+
// shortdesc: Prevent the instance from spoofing another instance's IPv4 address (enables `security.mac_filtering`)
231+
93232
"security.ipv4_filtering",
233+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.ipv6_filtering)
234+
//
235+
// ---
236+
// type: bool
237+
// default: false
238+
// managed: no
239+
// shortdesc: Prevent the instance from spoofing another instance's IPv6 address (enables `security.mac_filtering`)
94240
"security.ipv6_filtering",
241+
242+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.port_isolation)
243+
//
244+
// ---
245+
// type: bool
246+
// default: false
247+
// managed: no
248+
// shortdesc: Prevent the NIC from communicating with other NICs in the network that have port isolation enabled
95249
"security.port_isolation",
250+
251+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.acls)
252+
//
253+
// ---
254+
// type: string
255+
// managed: no
256+
// shortdesc: Comma-separated list of network ACLs to apply
96257
"security.acls",
258+
259+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.acls.default.ingress.action)
260+
//
261+
// ---
262+
// type: string
263+
// default: drop
264+
// managed: no
265+
// shortdesc: Action to use for ingress traffic that doesn't match any ACL rule
97266
"security.acls.default.ingress.action",
267+
268+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.acls.default.egress.action)
269+
//
270+
// ---
271+
// type: string
272+
// default: drop
273+
// managed: no
274+
// shortdesc: Action to use for egress traffic that doesn't match any ACL rule
98275
"security.acls.default.egress.action",
276+
277+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.acls.default.ingress.logged)
278+
//
279+
// ---
280+
// type: bool
281+
// default: false
282+
// managed: no
283+
// shortdesc: Whether to log ingress traffic that doesn't match any ACL rule
99284
"security.acls.default.ingress.logged",
285+
286+
// gendoc:generate(entity=devices, group=nic_bridged, key=security.acls.default.egress.logged)
287+
//
288+
// ---
289+
// type: bool
290+
// default: false
291+
// managed: no
292+
// shortdesc: Whether to log egress traffic that doesn't match any ACL rule
100293
"security.acls.default.egress.logged",
294+
295+
// gendoc:generate(entity=devices, group=nic_bridged, key=boot.priority)
296+
//
297+
// ---
298+
// type: integer
299+
// managed: no
300+
// shortdesc: Boot priority for VMs (higher value boots first)
101301
"boot.priority",
302+
303+
// gendoc:generate(entity=devices, group=nic_bridged, key=vlan)
304+
//
305+
// ---
306+
// type: integer
307+
// managed: no
308+
// shortdesc: The VLAN ID to use for non-tagged traffic (can be none to remove port from default VLAN)
102309
"vlan",
310+
311+
// gendoc:generate(entity=devices, group=nic_bridged, key=io.bus)
312+
//
313+
// ---
314+
// type: string
315+
// default: `virtio`
316+
// managed: no
317+
// shortdesc: Override the bus for the device (can be `virtio` or `usb`) (VM only)
103318
"io.bus",
104319
}
105320

@@ -326,6 +541,13 @@ func (d *nicBridged) validateConfig(instConf instance.ConfigReader) error {
326541
}
327542

328543
// Add bridge specific vlan.tagged validation.
544+
545+
// gendoc:generate(entity=devices, group=nic_bridged, key=vlan.tagged)
546+
//
547+
// ---
548+
// type: integer
549+
// managed: no
550+
// shortdesc: Comma-delimited list of VLAN IDs or VLAN ranges to join for tagged traffic
329551
rules["vlan.tagged"] = func(value string) error {
330552
if value == "" {
331553
return nil

‎internal/server/device/nic_ipvlan.go

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,84 @@ func (d *nicIPVLAN) validateConfig(instConf instance.ConfigReader) error {
3939

4040
requiredFields := []string{"parent"}
4141
optionalFields := []string{
42+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=name)
43+
//
44+
// ---
45+
// type: string
46+
// default: kernel assigned
47+
// shortdesc: The name of the interface inside the instance
4248
"name",
49+
50+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=mtu)
51+
//
52+
// ---
53+
// type: integer
54+
// default: MTU of the parent device
55+
// shortdesc: The Maximum Transmit Unit (MTU) of the new interface
4356
"mtu",
57+
58+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=hwaddr)
59+
//
60+
// ---
61+
// type: string
62+
// default: randomly assigned
63+
// shortdesc: The MAC address of the new interface
4464
"hwaddr",
65+
66+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=vlan)
67+
//
68+
// ---
69+
// type: integer
70+
// shortdesc: The VLAN ID to attach to
4571
"vlan",
72+
73+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv4.gateway)
74+
//
75+
// ---
76+
// type: string
77+
// default: `auto` (in `l3s` mode), `-` (in `l2` mode)
78+
// shortdesc: In `l3s` mode, whether to add an automatic default IPv4 gateway (can be `auto` or `none`). In `l2` mode, the IPv4 address of the gateway
4679
"ipv4.gateway",
80+
81+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv6.gateway)
82+
//
83+
// ---
84+
// type: string
85+
// default: `auto` (in `l3s` mode), `-` (in `l2` mode)
86+
// shortdesc: In `l3s` mode, whether to add an automatic default IPv6 gateway (can be `auto` or `none`). In `l2` mode, the IPv6 address of the gateway
4787
"ipv6.gateway",
88+
89+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv4.host_table)
90+
//
91+
// ---
92+
// type: integer
93+
// shortdesc: The custom policy routing table ID to add IPv4 static routes to (in addition to the main routing table)
4894
"ipv4.host_table",
95+
96+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv6.host_table)
97+
//
98+
// ---
99+
// type: integer
100+
// shortdesc: The custom policy routing table ID to add IPv6 static routes to (in addition to the main routing table)
49101
"ipv6.host_table",
102+
103+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=gvrp)
104+
//
105+
// ---
106+
// type: bool
107+
// default: false
108+
// shortdesc: Register VLAN using GARP VLAN Registration Protocol
50109
"gvrp",
51110
}
52111

53112
rules := nicValidationRules(requiredFields, optionalFields, instConf)
54113
rules["gvrp"] = validate.Optional(validate.IsBool)
114+
115+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv4.address)
116+
//
117+
// ---
118+
// type: string
119+
// shortdesc: Comma-delimited list of IPv4 static addresses to add to the instance (in l2 mode, these can be specified as CIDR values or singular addresses using a subnet of /24)
55120
rules["ipv4.address"] = func(value string) error {
56121
if value == "" {
57122
return nil
@@ -82,6 +147,11 @@ func (d *nicIPVLAN) validateConfig(instConf instance.ConfigReader) error {
82147
return validate.IsListOf(validate.IsNetworkAddressV4)(value)
83148
}
84149

150+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=ipv6.address)
151+
//
152+
// ---
153+
// type: string
154+
// shortdesc: Comma-delimited list of IPv6 static addresses to add to the instance (in `l2` mode, these can be specified as CIDR values or singular addresses using a subnet of /64)
85155
rules["ipv6.address"] = func(value string) error {
86156
if value == "" {
87157
return nil
@@ -112,6 +182,12 @@ func (d *nicIPVLAN) validateConfig(instConf instance.ConfigReader) error {
112182
return validate.IsListOf(validate.IsNetworkAddressV6)(value)
113183
}
114184

185+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=mode)
186+
//
187+
// ---
188+
// type: string
189+
// default: `l3s`
190+
// shortdesc: The IPVLAN mode (either `l2` or `l3s`)
115191
rules["mode"] = func(value string) error {
116192
if value == "" {
117193
return nil
@@ -153,6 +229,11 @@ func (d *nicIPVLAN) validateEnvironment() error {
153229
return fmt.Errorf("Requires liblxc has following API extensions: network_ipvlan, network_l2proxy, network_gateway_device_route")
154230
}
155231

232+
// gendoc:generate(entity=devices, group=nic_ipvlan, key=parent)
233+
//
234+
// ---
235+
// type: string
236+
// shortdesc: The name of the host device (required)
156237
if !network.InterfaceExists(d.config["parent"]) {
157238
return fmt.Errorf("Parent device '%s' doesn't exist", d.config["parent"])
158239
}

0 commit comments

Comments
 (0)