Merge ~raharper/cloud-init:network-config-doc into cloud-init:master
- Git
- lp:~raharper/cloud-init
- network-config-doc
- Merge into master
Status: | Merged |
---|---|
Merged at revision: | 99faf3ece1badc566e7e75e769ff374250196197 |
Proposed branch: | ~raharper/cloud-init:network-config-doc |
Merge into: | cloud-init:master |
Diff against target: |
1549 lines (+1395/-0) 19 files modified
doc/rtd/index.rst (+1/-0) doc/rtd/topics/datasources/altcloud.rst (+2/-0) doc/rtd/topics/datasources/azure.rst (+2/-0) doc/rtd/topics/datasources/cloudsigma.rst (+2/-0) doc/rtd/topics/datasources/cloudstack.rst (+2/-0) doc/rtd/topics/datasources/configdrive.rst (+2/-0) doc/rtd/topics/datasources/digitalocean.rst (+2/-0) doc/rtd/topics/datasources/ec2.rst (+2/-0) doc/rtd/topics/datasources/fallback.rst (+2/-0) doc/rtd/topics/datasources/maas.rst (+2/-0) doc/rtd/topics/datasources/nocloud.rst (+39/-0) doc/rtd/topics/datasources/opennebula.rst (+2/-0) doc/rtd/topics/datasources/openstack.rst (+2/-0) doc/rtd/topics/datasources/ovf.rst (+2/-0) doc/rtd/topics/datasources/smartos.rst (+2/-0) doc/rtd/topics/network-config-format-eni.rst (+19/-0) doc/rtd/topics/network-config-format-v1.rst (+555/-0) doc/rtd/topics/network-config-format-v2.rst (+503/-0) doc/rtd/topics/network-config.rst (+252/-0) |
Related bugs: |
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Server Team CI bot | continuous-integration | Approve | |
Scott Moser | Needs Fixing | ||
Review via email: mp+321397@code.launchpad.net |
Commit message
Description of the change
doc: document network configuration defaults, policy, formats and examples
Add documentation for cloud-init networking configuration formats, default
behavior, policy and other specific details about how network config is
consumed and utilized.
Server Team CI bot (server-team-bot) wrote : | # |
Scott Moser (smoser) wrote : | # |
Ryan, this looks really good.
you did a lot of sleuthing!
there are some comments inline, i read mostly around the 'cloud-init' parts, i very lightly skimmed the v1 and v2 doc sections.
Scott Moser (smoser) wrote : | # |
Ryan, this looks really good.
you did a lot of sleuthing!
there are some comments inline, i read mostly around the 'cloud-init' parts, i very lightly skimmed the v1 and v2 doc sections.
Ryan Harper (raharper) wrote : | # |
Thanks for the input; I'll update.
Scott Moser (smoser) : | # |
- 4990a43... by Ryan Harper
-
Incorporate MR feedback, remove trailing whitespace.
Server Team CI bot (server-team-bot) wrote : | # |
PASSED: Continuous integration, rev:4990a439de9
https:/
Executed test runs:
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
Click here to trigger a rebuild:
https:/
- e3df470... by Scott Moser
-
silence warning about yaml format by explicitly stating code block format
- f9acbc2... by Scott Moser
-
input format is legacy. output format is fine (and required by current OSes)
- c46692d... by Scott Moser
-
system config does not come under system_info
Scott Moser (smoser) wrote : | # |
only a few small things inline.
and also i have done some commits on top of this at
https:/
so just pull those into yours if you agree.
- 5a452c4... by Ryan Harper
-
Wrap lines < 80
- bd2ae47... by Ryan Harper
-
Merge remote-tracking branch 'smoser-
cloudinit/ network- config- docs' into network-config-doc - e3e1ef6... by Ryan Harper
-
remove documentation on disabling during upgrade
- b773c3c... by Ryan Harper
-
Drop system_info as config space key; rename to cloud config
- 41e0e8e... by Ryan Harper
-
Add vlan to list of ignored interfaces for fallback
Server Team CI bot (server-team-bot) wrote : | # |
PASSED: Continuous integration, rev:bd2ae472d2d
https:/
Executed test runs:
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
Click here to trigger a rebuild:
https:/
- 42e5031... by Ryan Harper
-
Remove interface selection algorithm details
- e1d999a... by Ryan Harper
-
Reword network config background, fix ConfigDrive network sources
Ryan Harper (raharper) wrote : | # |
OK, I've addressed the comments, and merged your network-config-doc branch. Please re-review.
Server Team CI bot (server-team-bot) wrote : | # |
PASSED: Continuous integration, rev:e1d999ae6a7
https:/
Executed test runs:
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
Click here to trigger a rebuild:
https:/
- 3e5f2fe... by Ryan Harper
-
Merge in additional feedback.
Server Team CI bot (server-team-bot) wrote : | # |
PASSED: Continuous integration, rev:3e5f2fee2e2
https:/
Executed test runs:
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
Click here to trigger a rebuild:
https:/
Preview Diff
1 | diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst |
2 | index 8f163b6..a691103 100644 |
3 | --- a/doc/rtd/index.rst |
4 | +++ b/doc/rtd/index.rst |
5 | @@ -38,6 +38,7 @@ initialization of a cloud instance. |
6 | topics/logging.rst |
7 | topics/modules.rst |
8 | topics/merging.rst |
9 | + topics/network-config.rst |
10 | topics/vendordata.rst |
11 | topics/moreinfo.rst |
12 | topics/hacking.rst |
13 | diff --git a/doc/rtd/topics/datasources/altcloud.rst b/doc/rtd/topics/datasources/altcloud.rst |
14 | index 202b0a4..eeb197f 100644 |
15 | --- a/doc/rtd/topics/datasources/altcloud.rst |
16 | +++ b/doc/rtd/topics/datasources/altcloud.rst |
17 | @@ -1,3 +1,5 @@ |
18 | +.. _datasource_alt_cloud: |
19 | + |
20 | Alt Cloud |
21 | ========= |
22 | |
23 | diff --git a/doc/rtd/topics/datasources/azure.rst b/doc/rtd/topics/datasources/azure.rst |
24 | index 18d7c50..4a3735b 100644 |
25 | --- a/doc/rtd/topics/datasources/azure.rst |
26 | +++ b/doc/rtd/topics/datasources/azure.rst |
27 | @@ -1,3 +1,5 @@ |
28 | +.. _datasource_azure: |
29 | + |
30 | Azure |
31 | ===== |
32 | |
33 | diff --git a/doc/rtd/topics/datasources/cloudsigma.rst b/doc/rtd/topics/datasources/cloudsigma.rst |
34 | index 54963f6..86b834c 100644 |
35 | --- a/doc/rtd/topics/datasources/cloudsigma.rst |
36 | +++ b/doc/rtd/topics/datasources/cloudsigma.rst |
37 | @@ -1,3 +1,5 @@ |
38 | +.. _datasource_cloudsigma: |
39 | + |
40 | CloudSigma |
41 | ========== |
42 | |
43 | diff --git a/doc/rtd/topics/datasources/cloudstack.rst b/doc/rtd/topics/datasources/cloudstack.rst |
44 | index 04603d9..225093a 100644 |
45 | --- a/doc/rtd/topics/datasources/cloudstack.rst |
46 | +++ b/doc/rtd/topics/datasources/cloudstack.rst |
47 | @@ -1,3 +1,5 @@ |
48 | +.. _datasource_cloudstack: |
49 | + |
50 | CloudStack |
51 | ========== |
52 | |
53 | diff --git a/doc/rtd/topics/datasources/configdrive.rst b/doc/rtd/topics/datasources/configdrive.rst |
54 | index 11dd52a..f1a488a 100644 |
55 | --- a/doc/rtd/topics/datasources/configdrive.rst |
56 | +++ b/doc/rtd/topics/datasources/configdrive.rst |
57 | @@ -1,3 +1,5 @@ |
58 | +.. _datasource_config_drive: |
59 | + |
60 | Config Drive |
61 | ============ |
62 | |
63 | diff --git a/doc/rtd/topics/datasources/digitalocean.rst b/doc/rtd/topics/datasources/digitalocean.rst |
64 | index c6f5bc7..938ede8 100644 |
65 | --- a/doc/rtd/topics/datasources/digitalocean.rst |
66 | +++ b/doc/rtd/topics/datasources/digitalocean.rst |
67 | @@ -1,3 +1,5 @@ |
68 | +.. _datasource_digital_ocean: |
69 | + |
70 | Digital Ocean |
71 | ============= |
72 | |
73 | diff --git a/doc/rtd/topics/datasources/ec2.rst b/doc/rtd/topics/datasources/ec2.rst |
74 | index 4810c98..3bc66e1 100644 |
75 | --- a/doc/rtd/topics/datasources/ec2.rst |
76 | +++ b/doc/rtd/topics/datasources/ec2.rst |
77 | @@ -1,3 +1,5 @@ |
78 | +.. _datasource_ec2: |
79 | + |
80 | Amazon EC2 |
81 | ========== |
82 | |
83 | diff --git a/doc/rtd/topics/datasources/fallback.rst b/doc/rtd/topics/datasources/fallback.rst |
84 | index 1eb01dd..2b133fc 100644 |
85 | --- a/doc/rtd/topics/datasources/fallback.rst |
86 | +++ b/doc/rtd/topics/datasources/fallback.rst |
87 | @@ -1,3 +1,5 @@ |
88 | +.. _datasource_fallback: |
89 | + |
90 | Fallback/None |
91 | ============= |
92 | |
93 | diff --git a/doc/rtd/topics/datasources/maas.rst b/doc/rtd/topics/datasources/maas.rst |
94 | index f495dd4..85c853e 100644 |
95 | --- a/doc/rtd/topics/datasources/maas.rst |
96 | +++ b/doc/rtd/topics/datasources/maas.rst |
97 | @@ -1,3 +1,5 @@ |
98 | +.. _datasource_maas: |
99 | + |
100 | MAAS |
101 | ==== |
102 | |
103 | diff --git a/doc/rtd/topics/datasources/nocloud.rst b/doc/rtd/topics/datasources/nocloud.rst |
104 | index b9ab5f1..0159e85 100644 |
105 | --- a/doc/rtd/topics/datasources/nocloud.rst |
106 | +++ b/doc/rtd/topics/datasources/nocloud.rst |
107 | @@ -1,3 +1,5 @@ |
108 | +.. _datasource_nocloud: |
109 | + |
110 | NoCloud |
111 | ======= |
112 | |
113 | @@ -70,6 +72,43 @@ Example metadata: |
114 | gateway 192.168.1.254 |
115 | hostname: myhost |
116 | |
117 | + |
118 | +Network configuration can also be provided to cloud-init in either |
119 | +:ref:`network_config_v1` or :ref:`network_config_v2` by providing that |
120 | +yaml formatted data in a file named ``network-config``. If found, |
121 | +this file will override a ``network-interfaces`` file. |
122 | + |
123 | +See an example below. Note specifically that this file does not |
124 | +have a top level ``network`` key as it it is already assumed to |
125 | +be network configuration based on the filename. |
126 | + |
127 | +.. code:: yaml |
128 | + |
129 | + version: 1 |
130 | + config: |
131 | + - type: physical |
132 | + name: interface0 |
133 | + mac_address: "52:54:00:12:34:00" |
134 | + subnets: |
135 | + - type: static |
136 | + address: 192.168.1.10 |
137 | + netmask: 255.255.255.0 |
138 | + gateway: 192.168.1.254 |
139 | + |
140 | + |
141 | +.. code:: yaml |
142 | + |
143 | + version: 2 |
144 | + ethernets: |
145 | + interface0: |
146 | + match: |
147 | + mac_address: "52:54:00:12:34:00" |
148 | + set-name: interface0 |
149 | + addresses: |
150 | + - 192.168.1.10/255.255.255.0 |
151 | + gateway4: 192.168.1.254 |
152 | + |
153 | + |
154 | .. _iso9660: https://en.wikipedia.org/wiki/ISO_9660 |
155 | .. _vfat: https://en.wikipedia.org/wiki/File_Allocation_Table |
156 | .. vi: textwidth=78 |
157 | diff --git a/doc/rtd/topics/datasources/opennebula.rst b/doc/rtd/topics/datasources/opennebula.rst |
158 | index 1b90a9c..7c0367c 100644 |
159 | --- a/doc/rtd/topics/datasources/opennebula.rst |
160 | +++ b/doc/rtd/topics/datasources/opennebula.rst |
161 | @@ -1,3 +1,5 @@ |
162 | +.. _datasource_opennebula: |
163 | + |
164 | OpenNebula |
165 | ========== |
166 | |
167 | diff --git a/doc/rtd/topics/datasources/openstack.rst b/doc/rtd/topics/datasources/openstack.rst |
168 | index 164b0e0..607b70f 100644 |
169 | --- a/doc/rtd/topics/datasources/openstack.rst |
170 | +++ b/doc/rtd/topics/datasources/openstack.rst |
171 | @@ -1,3 +1,5 @@ |
172 | +.. _datasource_openstack: |
173 | + |
174 | OpenStack |
175 | ========= |
176 | |
177 | diff --git a/doc/rtd/topics/datasources/ovf.rst b/doc/rtd/topics/datasources/ovf.rst |
178 | index a077033..c312617 100644 |
179 | --- a/doc/rtd/topics/datasources/ovf.rst |
180 | +++ b/doc/rtd/topics/datasources/ovf.rst |
181 | @@ -1,3 +1,5 @@ |
182 | +.. _datasource_ovf: |
183 | + |
184 | OVF |
185 | === |
186 | |
187 | diff --git a/doc/rtd/topics/datasources/smartos.rst b/doc/rtd/topics/datasources/smartos.rst |
188 | index a1e1542..cb9a128 100644 |
189 | --- a/doc/rtd/topics/datasources/smartos.rst |
190 | +++ b/doc/rtd/topics/datasources/smartos.rst |
191 | @@ -1,3 +1,5 @@ |
192 | +.. _datasource_smartos: |
193 | + |
194 | SmartOS Datasource |
195 | ================== |
196 | |
197 | diff --git a/doc/rtd/topics/network-config-format-eni.rst b/doc/rtd/topics/network-config-format-eni.rst |
198 | new file mode 100644 |
199 | index 0000000..f9ecaf7 |
200 | --- /dev/null |
201 | +++ b/doc/rtd/topics/network-config-format-eni.rst |
202 | @@ -0,0 +1,19 @@ |
203 | +.. _network_config_eni: |
204 | + |
205 | +Network Configuration ENI (Legacy) |
206 | +---------------------------------- |
207 | + |
208 | +`Cloud-init`_ supports reading and writing network config in the ``ENI`` |
209 | +format which is consumed by the ``ifupdown`` tool to parse and apply network |
210 | +configuration. |
211 | + |
212 | +As an input format this is **legacy** and `Cloud-init`_. In cases where |
213 | +ENI format is available and another format is also available, it will |
214 | +prefer to use the other format. This can happen in either :ref:`datasource_nocloud` or |
215 | +:ref:`datasource_openstack` datasources. |
216 | + |
217 | +Please reference existing `documentation`_ for the ``/etc/network/interfaces(5)`` format. |
218 | + |
219 | +.. _Cloud-init: https://launchpad.net/cloud-init |
220 | +.. _documentation: http://manpages.ubuntu.com/manpages/trusty/en/man5/interfaces.5.html |
221 | +.. vi: textwidth=78 |
222 | diff --git a/doc/rtd/topics/network-config-format-v1.rst b/doc/rtd/topics/network-config-format-v1.rst |
223 | new file mode 100644 |
224 | index 0000000..f5f5d5d |
225 | --- /dev/null |
226 | +++ b/doc/rtd/topics/network-config-format-v1.rst |
227 | @@ -0,0 +1,555 @@ |
228 | +.. _network_config_v1: |
229 | + |
230 | +Networking Config Version 1 |
231 | +=========================== |
232 | + |
233 | +This network configuration format lets users customize their instance's |
234 | +networking interfaces by assigning subnet configuration, virtual device |
235 | +creation (bonds, bridges, vlans) routes and DNS configuration. |
236 | + |
237 | +Required elements of a Network Config Version 1 are ``config`` and |
238 | +``version``. |
239 | + |
240 | +Cloud-init will read this format from system config. |
241 | +For example the following could be present in |
242 | +``/etc/cloud/cloud.cfg.d/custom-networking.cfg``: |
243 | + |
244 | +.. code-block:: yaml |
245 | + |
246 | + network: |
247 | + version: 1 |
248 | + config: |
249 | + - type: physical |
250 | + name: eth0 |
251 | + subnets: |
252 | + - type: dhcp |
253 | + |
254 | +The :ref:`datasource_nocloud` datasource can also provide cloud-init networking |
255 | +configuration in this Format. |
256 | + |
257 | +Configuration Types |
258 | +------------------- |
259 | +Within the network ``config`` portion, users include a list of configuration |
260 | +types. The current list of support ``type`` values are as follows: |
261 | + |
262 | +- Physical (``physical``) |
263 | +- Bond (``bond``) |
264 | +- Bridge (``bridge``) |
265 | +- VLAN (``vlan``) |
266 | +- Nameserver (``nameserver``) |
267 | +- Route (``route``) |
268 | + |
269 | +Physical, Bond, Bridge and VLAN types may also include IP configuration under |
270 | +the key ``subnets``. |
271 | + |
272 | +- Subnet/IP (``subnets``) |
273 | + |
274 | + |
275 | +Physical |
276 | +~~~~~~~~ |
277 | +The ``physical`` type configuration represents a "physical" network device, |
278 | +typically Ethernet-based. At least one of of these entries is required for |
279 | +external network connectivity. Type ``physical`` requires only one key: |
280 | +``name``. A ``physical`` device may contain some or all of the following keys: |
281 | + |
282 | +**name**: *<desired device name>* |
283 | + |
284 | +A devices name must be less than 15 characters. Names exceeding the maximum |
285 | +will be truncated. This is a limitation of the Linux kernel network-device |
286 | +structure. |
287 | + |
288 | +**mac_address**: *<MAC Address>* |
289 | + |
290 | +The MAC Address is a device unique identifier that most Ethernet-based network |
291 | +devices possess. Specifying a MAC Address is optional. |
292 | + |
293 | + |
294 | +.. note:: |
295 | + |
296 | + Cloud-init will handle the persistent mapping between a |
297 | + device's ``name`` and the ``mac_address``. |
298 | + |
299 | +**mtu**: *<MTU SizeBytes>* |
300 | + |
301 | +The MTU key represents a device's Maximum Transmission Unit, the largest size |
302 | +packet or frame, specified in octets (eight-bit bytes), that can be sent in a |
303 | +packet- or frame-based network. Specifying ``mtu`` is optional. |
304 | + |
305 | +.. note:: |
306 | + |
307 | + The possible supported values of a device's MTU is not available at |
308 | + configuration time. It's possible to specify a value too large or to |
309 | + small for a device and may be ignored by the device. |
310 | + |
311 | + |
312 | +**Physical Example**:: |
313 | + |
314 | + network: |
315 | + version: 1 |
316 | + config: |
317 | + # Simple network adapter |
318 | + - type: physical |
319 | + name: interface0 |
320 | + mac_address: 00:11:22:33:44:55 |
321 | + # Second nic with Jumbo frames |
322 | + - type: physical |
323 | + name: jumbo0 |
324 | + mac_address: aa:11:22:33:44:55 |
325 | + mtu: 9000 |
326 | + # 10G pair |
327 | + - type: physical |
328 | + name: gbe0 |
329 | + mac_address: cd:11:22:33:44:00 |
330 | + - type: physical |
331 | + name: gbe1 |
332 | + mac_address: cd:11:22:33:44:02 |
333 | + |
334 | +Bond |
335 | +~~~~ |
336 | +A ``bond`` type will configure a Linux software Bond with one or more network |
337 | +devices. A ``bond`` type requires the following keys: |
338 | + |
339 | +**name**: *<desired device name>* |
340 | + |
341 | +A devices name must be less than 15 characters. Names exceeding the maximum |
342 | +will be truncated. This is a limitation of the Linux kernel network-device |
343 | +structure. |
344 | + |
345 | +**mac_address**: *<MAC Address>* |
346 | + |
347 | +When specifying MAC Address on a bond this value will be assigned to the bond |
348 | +device and may be different than the MAC address of any of the underlying |
349 | +bond interfaces. Specifying a MAC Address is optional. If ``mac_address`` is |
350 | +not present, then the bond will use one of the MAC Address values from one of |
351 | +the bond interfaces. |
352 | + |
353 | + |
354 | +**bond_interfaces**: *<List of network device names>* |
355 | + |
356 | +The ``bond_interfaces`` key accepts a list of network device ``name`` values |
357 | +from the configuration. This list may be empty. |
358 | + |
359 | +**params**: *<Dictionary of key: value bonding parameter pairs>* |
360 | + |
361 | +The ``params`` key in a bond holds a dictionary of bonding parameters. |
362 | +This dictionary may be empty. For more details on what the various bonding |
363 | +parameters mean please read the Linux Kernel Bonding.txt. |
364 | + |
365 | +Valid ``params`` keys are: |
366 | + |
367 | + - ``active_slave``: Set bond attribute |
368 | + - ``ad_actor_key``: Set bond attribute |
369 | + - ``ad_actor_sys_prio``: Set bond attribute |
370 | + - ``ad_actor_system``: Set bond attribute |
371 | + - ``ad_aggregator``: Set bond attribute |
372 | + - ``ad_num_ports``: Set bond attribute |
373 | + - ``ad_partner_key``: Set bond attribute |
374 | + - ``ad_partner_mac``: Set bond attribute |
375 | + - ``ad_select``: Set bond attribute |
376 | + - ``ad_user_port_key``: Set bond attribute |
377 | + - ``all_slaves_active``: Set bond attribute |
378 | + - ``arp_all_targets``: Set bond attribute |
379 | + - ``arp_interval``: Set bond attribute |
380 | + - ``arp_ip_target``: Set bond attribute |
381 | + - ``arp_validate``: Set bond attribute |
382 | + - ``downdelay``: Set bond attribute |
383 | + - ``fail_over_mac``: Set bond attribute |
384 | + - ``lacp_rate``: Set bond attribute |
385 | + - ``lp_interval``: Set bond attribute |
386 | + - ``miimon``: Set bond attribute |
387 | + - ``mii_status``: Set bond attribute |
388 | + - ``min_links``: Set bond attribute |
389 | + - ``mode``: Set bond attribute |
390 | + - ``num_grat_arp``: Set bond attribute |
391 | + - ``num_unsol_na``: Set bond attribute |
392 | + - ``packets_per_slave``: Set bond attribute |
393 | + - ``primary``: Set bond attribute |
394 | + - ``primary_reselect``: Set bond attribute |
395 | + - ``queue_id``: Set bond attribute |
396 | + - ``resend_igmp``: Set bond attribute |
397 | + - ``slaves``: Set bond attribute |
398 | + - ``tlb_dynamic_lb``: Set bond attribute |
399 | + - ``updelay``: Set bond attribute |
400 | + - ``use_carrier``: Set bond attribute |
401 | + - ``xmit_hash_policy``: Set bond attribute |
402 | + |
403 | +**Bond Example**:: |
404 | + |
405 | + network: |
406 | + version: 1 |
407 | + config: |
408 | + # Simple network adapter |
409 | + - type: physical |
410 | + name: interface0 |
411 | + mac_address: 00:11:22:33:44:55 |
412 | + # 10G pair |
413 | + - type: physical |
414 | + name: gbe0 |
415 | + mac_address: cd:11:22:33:44:00 |
416 | + - type: physical |
417 | + name: gbe1 |
418 | + mac_address: cd:11:22:33:44:02 |
419 | + - type: bond |
420 | + name: bond0 |
421 | + bond_interfaces: |
422 | + - gbe0 |
423 | + - gbe1 |
424 | + params: |
425 | + bond-mode: active-backup |
426 | + |
427 | +Bridge |
428 | +~~~~~~ |
429 | +Type ``bridge`` requires the following keys: |
430 | + |
431 | +- ``name``: Set the name of the bridge. |
432 | +- ``bridge_interfaces``: Specify the ports of a bridge via their ``name``. This list may be empty. |
433 | +- ``params``: A list of bridge params. For more details, please read the bridge-utils-interfaces manpage. |
434 | + |
435 | +Valid keys are: |
436 | + |
437 | + - ``bridge_ageing``: Set the bridge's ageing value. |
438 | + - ``bridge_bridgeprio``: Set the bridge device network priority. |
439 | + - ``bridge_fd``: Set the bridge's forward delay. |
440 | + - ``bridge_hello``: Set the bridge's hello value. |
441 | + - ``bridge_hw``: Set the bridge's MAC address. |
442 | + - ``bridge_maxage``: Set the bridge's maxage value. |
443 | + - ``bridge_maxwait``: Set how long network scripts should wait for the bridge to be up. |
444 | + - ``bridge_pathcost``: Set the cost of a specific port on the bridge. |
445 | + - ``bridge_portprio``: Set the priority of a specific port on the bridge. |
446 | + - ``bridge_ports``: List of devices that are part of the bridge. |
447 | + - ``bridge_stp``: Set spanning tree protocol on or off. |
448 | + - ``bridge_waitport``: Set amount of time in seconds to wait on specific ports to become available. |
449 | + |
450 | + |
451 | +**Bridge Example**:: |
452 | + |
453 | + network: |
454 | + version: 1 |
455 | + config: |
456 | + # Simple network adapter |
457 | + - type: physical |
458 | + name: interface0 |
459 | + mac_address: 00:11:22:33:44:55 |
460 | + # Second nic with Jumbo frames |
461 | + - type: physical |
462 | + name: jumbo0 |
463 | + mac_address: aa:11:22:33:44:55 |
464 | + mtu: 9000 |
465 | + - type: bridge |
466 | + name: br0 |
467 | + bridge_interfaces: |
468 | + - jumbo0 |
469 | + params: |
470 | + bridge_ageing: 250 |
471 | + bridge_bridgeprio: 22 |
472 | + bridge_fd: 1 |
473 | + bridge_hello: 1 |
474 | + bridge_maxage: 10 |
475 | + bridge_maxwait: 0 |
476 | + bridge_pathcost: |
477 | + - jumbo0 75 |
478 | + bridge_pathprio: |
479 | + - jumbo0 28 |
480 | + bridge_stp: 'off' |
481 | + bridge_maxwait: |
482 | + - jumbo0 0 |
483 | + |
484 | + |
485 | +VLAN |
486 | +~~~~ |
487 | +Type ``vlan`` requires the following keys: |
488 | + |
489 | +- ``name``: Set the name of the VLAN |
490 | +- ``vlan_link``: Specify the underlying link via its ``name``. |
491 | +- ``vlan_id``: Specify the VLAN numeric id. |
492 | + |
493 | +**VLAN Example**:: |
494 | + |
495 | + network: |
496 | + version: 1 |
497 | + config: |
498 | + # Physical interfaces. |
499 | + - type: physical |
500 | + name: eth0 |
501 | + mac_address: "c0:d6:9f:2c:e8:80" |
502 | + # VLAN interface. |
503 | + - type: vlan |
504 | + name: eth0.101 |
505 | + vlan_link: eth0 |
506 | + vlan_id: 101 |
507 | + mtu: 1500 |
508 | + |
509 | +Nameserver |
510 | +~~~~~~~~~~ |
511 | + |
512 | +Users can specify a ``nameserver`` type. Nameserver dictionaries include |
513 | +the following keys: |
514 | + |
515 | +- ``address``: List of IPv4 or IPv6 address of nameservers. |
516 | +- ``search``: List of of hostnames to include in the resolv.conf search path. |
517 | + |
518 | +**Nameserver Example**:: |
519 | + |
520 | + network: |
521 | + version: 1 |
522 | + config: |
523 | + - type: physical |
524 | + name: interface0 |
525 | + mac_address: 00:11:22:33:44:55 |
526 | + subnets: |
527 | + - type: static |
528 | + address: 192.168.23.14/27 |
529 | + gateway: 192.168.23.1 |
530 | + - type: nameserver: |
531 | + address: |
532 | + - 192.168.23.2 |
533 | + - 8.8.8.8 |
534 | + search: |
535 | + - exemplary |
536 | + |
537 | + |
538 | + |
539 | +Route |
540 | +~~~~~ |
541 | + |
542 | +Users can include static routing information as well. A ``route`` dictionary |
543 | +has the following keys: |
544 | + |
545 | +- ``destination``: IPv4 network address with CIDR netmask notation. |
546 | +- ``gateway``: IPv4 gateway address with CIDR netmask notation. |
547 | +- ``metric``: Integer which sets the network metric value for this route. |
548 | + |
549 | +**Route Example**:: |
550 | + |
551 | + network: |
552 | + version: 1 |
553 | + config: |
554 | + - type: physical |
555 | + name: interface0 |
556 | + mac_address: 00:11:22:33:44:55 |
557 | + subnets: |
558 | + - type: static |
559 | + address: 192.168.23.14/24 |
560 | + gateway: 192.168.23.1 |
561 | + - type: route |
562 | + destination: 192.168.24.0/24 |
563 | + gateway: 192.168.24.1 |
564 | + metric: 3 |
565 | + |
566 | +Subnet/IP |
567 | +~~~~~~~~~ |
568 | + |
569 | +For any network device (one of the Config Types) users can define a list of |
570 | +``subnets`` which contain ip configuration dictionaries. Multiple subnet |
571 | +entries will create interface alias allowing a single interface to use different |
572 | +ip configurations. |
573 | + |
574 | +Valid keys for for ``subnets`` include the following: |
575 | + |
576 | +- ``type``: Specify the subnet type. |
577 | +- ``control``: Specify manual, auto or hotplug. Indicates how the interface will be handled during boot. |
578 | +- ``address``: IPv4 or IPv6 address. It may include CIDR netmask notation. |
579 | +- ``netmask``: IPv4 subnet mask in dotted format or CIDR notation. |
580 | +- ``gateway``: IPv4 address of the default gateway for this subnet. |
581 | +- ``dns_nameserver``: Specify a list of IPv4 dns server IPs to end up in resolv.conf. |
582 | +- ``dns_search``: Specify a list of search paths to be included in resolv.conf. |
583 | +- ``routes``: Specify a list of routes for a given interface |
584 | + |
585 | + |
586 | +Subnet types are one of the following: |
587 | + |
588 | +- ``dhcp4``: Configure this interface with IPv4 dhcp. |
589 | +- ``dhcp``: Alias for ``dhcp4`` |
590 | +- ``dhcp6``: Configure this interface with IPv6 dhcp. |
591 | +- ``static``: Configure this interface with a static IPv4. |
592 | +- ``static6``: Configure this interface with a static IPv6 . |
593 | + |
594 | +When making use of ``dhcp`` types, no additional configuration is needed in the |
595 | +subnet dictionary. |
596 | + |
597 | + |
598 | +**Subnet DHCP Example**:: |
599 | + |
600 | + network: |
601 | + version: 1 |
602 | + config: |
603 | + - type: physical |
604 | + name: interface0 |
605 | + mac_address: 00:11:22:33:44:55 |
606 | + subnets: |
607 | + - type: dhcp |
608 | + |
609 | + |
610 | +**Subnet Static Example**:: |
611 | + |
612 | + network: |
613 | + version: 1 |
614 | + config: |
615 | + - type: physical |
616 | + name: interface0 |
617 | + mac_address: 00:11:22:33:44:55 |
618 | + subnets: |
619 | + - type: static |
620 | + address: 192.168.23.14/27 |
621 | + gateway: 192.168.23.1 |
622 | + dns_nameservers: |
623 | + - 192.168.23.2 |
624 | + - 8.8.8.8 |
625 | + dns_search: |
626 | + - exemplary.maas |
627 | + |
628 | +The following will result in an ``interface0`` using DHCP and ``interface0:1`` |
629 | +using the static subnet configuration. |
630 | + |
631 | +**Multiple subnet Example**:: |
632 | + |
633 | + network: |
634 | + version: 1 |
635 | + config: |
636 | + - type: physical |
637 | + name: interface0 |
638 | + mac_address: 00:11:22:33:44:55 |
639 | + subnets: |
640 | + - type: dhcp |
641 | + - type: static |
642 | + address: 192.168.23.14/27 |
643 | + gateway: 192.168.23.1 |
644 | + dns_nameservers: |
645 | + - 192.168.23.2 |
646 | + - 8.8.8.8 |
647 | + dns_search: |
648 | + - exemplary |
649 | + |
650 | +**Subnet with routes Example**:: |
651 | + |
652 | + network: |
653 | + version: 1 |
654 | + config: |
655 | + - type: physical |
656 | + name: interface0 |
657 | + mac_address: 00:11:22:33:44:55 |
658 | + subnets: |
659 | + - type: dhcp |
660 | + - type: static |
661 | + address: 10.184.225.122 |
662 | + netmask: 255.255.255.252 |
663 | + routes: |
664 | + - gateway: 10.184.225.121 |
665 | + netmask: 255.240.0.0 |
666 | + network: 10.176.0.0 |
667 | + - gateway: 10.184.225.121 |
668 | + netmask: 255.240.0.0 |
669 | + network: 10.208.0.0 |
670 | + |
671 | + |
672 | +Multi-layered configurations |
673 | +---------------------------- |
674 | + |
675 | +Complex networking sometimes uses layers of configuration. The syntax allows |
676 | +users to build those layers one at a time. All of the virtual network devices |
677 | +supported allow specifying an underlying device by their ``name`` value. |
678 | + |
679 | +**Bonded VLAN Example**:: |
680 | + |
681 | + network: |
682 | + version: 1 |
683 | + config: |
684 | + # 10G pair |
685 | + - type: physical |
686 | + name: gbe0 |
687 | + mac_address: cd:11:22:33:44:00 |
688 | + - type: physical |
689 | + name: gbe1 |
690 | + mac_address: cd:11:22:33:44:02 |
691 | + # Bond. |
692 | + - type: bond |
693 | + name: bond0 |
694 | + bond_interfaces: |
695 | + - gbe0 |
696 | + - gbe1 |
697 | + params: |
698 | + bond-mode: 802.3ad |
699 | + bond-lacp-rate: fast |
700 | + # A Bond VLAN. |
701 | + - type: vlan |
702 | + name: bond0.200 |
703 | + vlan_link: bond0 |
704 | + vlan_id: 200 |
705 | + subnets: |
706 | + - type: dhcp4 |
707 | + |
708 | +More Examples |
709 | +------------- |
710 | +Some more examples to explore the various options available. |
711 | + |
712 | +**Multiple VLAN example**:: |
713 | + |
714 | + network: |
715 | + version: 1 |
716 | + config: |
717 | + - id: eth0 |
718 | + mac_address: d4:be:d9:a8:49:13 |
719 | + mtu: 1500 |
720 | + name: eth0 |
721 | + subnets: |
722 | + - address: 10.245.168.16/21 |
723 | + dns_nameservers: |
724 | + - 10.245.168.2 |
725 | + gateway: 10.245.168.1 |
726 | + type: static |
727 | + type: physical |
728 | + - id: eth1 |
729 | + mac_address: d4:be:d9:a8:49:15 |
730 | + mtu: 1500 |
731 | + name: eth1 |
732 | + subnets: |
733 | + - address: 10.245.188.2/24 |
734 | + dns_nameservers: [] |
735 | + type: static |
736 | + type: physical |
737 | + - id: eth1.2667 |
738 | + mtu: 1500 |
739 | + name: eth1.2667 |
740 | + subnets: |
741 | + - address: 10.245.184.2/24 |
742 | + dns_nameservers: [] |
743 | + type: static |
744 | + type: vlan |
745 | + vlan_id: 2667 |
746 | + vlan_link: eth1 |
747 | + - id: eth1.2668 |
748 | + mtu: 1500 |
749 | + name: eth1.2668 |
750 | + subnets: |
751 | + - address: 10.245.185.1/24 |
752 | + dns_nameservers: [] |
753 | + type: static |
754 | + type: vlan |
755 | + vlan_id: 2668 |
756 | + vlan_link: eth1 |
757 | + - id: eth1.2669 |
758 | + mtu: 1500 |
759 | + name: eth1.2669 |
760 | + subnets: |
761 | + - address: 10.245.186.1/24 |
762 | + dns_nameservers: [] |
763 | + type: static |
764 | + type: vlan |
765 | + vlan_id: 2669 |
766 | + vlan_link: eth1 |
767 | + - id: eth1.2670 |
768 | + mtu: 1500 |
769 | + name: eth1.2670 |
770 | + subnets: |
771 | + - address: 10.245.187.2/24 |
772 | + dns_nameservers: [] |
773 | + type: static |
774 | + type: vlan |
775 | + vlan_id: 2670 |
776 | + vlan_link: eth1 |
777 | + - address: 10.245.168.2 |
778 | + search: |
779 | + - dellstack |
780 | + type: nameserver |
781 | + |
782 | +.. vi: textwidth=78 |
783 | diff --git a/doc/rtd/topics/network-config-format-v2.rst b/doc/rtd/topics/network-config-format-v2.rst |
784 | new file mode 100644 |
785 | index 0000000..335d236 |
786 | --- /dev/null |
787 | +++ b/doc/rtd/topics/network-config-format-v2.rst |
788 | @@ -0,0 +1,503 @@ |
789 | +.. _network_config_v2: |
790 | + |
791 | +Networking Config Version 2 |
792 | +=========================== |
793 | + |
794 | +Cloud-init's support for Version 2 network config is a subset of the |
795 | +version 2 format defined for the `netplan`_ tool. Cloud-init supports |
796 | +both reading and writing of Version 2; the latter support requires a |
797 | +distro with `netplan`_ present. |
798 | + |
799 | +The ``network`` key has at least two required elements. First |
800 | +it must include ``version: 2`` and one or more of possible device |
801 | +``types``.. |
802 | + |
803 | +Cloud-init will read this format from system config. |
804 | +For example the following could be present in |
805 | +``/etc/cloud/cloud.cfg.d/custom-networking.cfg``: |
806 | + |
807 | + network: |
808 | + version: 2 |
809 | + ethernets: [] |
810 | + |
811 | +It may also be provided in other locations including the |
812 | +:ref:`datasource_nocloud`, see :ref:`default_behavior` for other places. |
813 | + |
814 | +Supported device ``types`` values are as follows: |
815 | + |
816 | +- Ethernets (``ethernets``) |
817 | +- Bonds (``bonds``) |
818 | +- Bridges (``bridges``) |
819 | +- VLANs (``vlans``) |
820 | + |
821 | +Each type block contains device definitions as a map where the keys (called |
822 | +"configuration IDs"). Each entry under the ``types`` may include IP and/or |
823 | +device configuration. |
824 | + |
825 | +Cloud-init does not current support ``wifis`` type that is present in native |
826 | +`netplan`_. |
827 | + |
828 | + |
829 | +Device configuration IDs |
830 | +------------------------ |
831 | + |
832 | +The key names below the per-device-type definition maps (like ``ethernets:``) |
833 | +are called "ID"s. They must be unique throughout the entire set of |
834 | +configuration files. Their primary purpose is to serve as anchor names for |
835 | +composite devices, for example to enumerate the members of a bridge that is |
836 | +currently being defined. |
837 | + |
838 | +There are two physically/structurally different classes of device definitions, |
839 | +and the ID field has a different interpretation for each: |
840 | + |
841 | +Physical devices |
842 | + |
843 | +: (Examples: ethernet, wifi) These can dynamically come and go between |
844 | + reboots and even during runtime (hotplugging). In the generic case, they |
845 | + can be selected by ``match:`` rules on desired properties, such as name/name |
846 | + pattern, MAC address, driver, or device paths. In general these will match |
847 | + any number of devices (unless they refer to properties which are unique |
848 | + such as the full path or MAC address), so without further knowledge about |
849 | + the hardware these will always be considered as a group. |
850 | + |
851 | + It is valid to specify no match rules at all, in which case the ID field is |
852 | + simply the interface name to be matched. This is mostly useful if you want |
853 | + to keep simple cases simple, and it's how network device configuration has |
854 | + been done for a long time. |
855 | + |
856 | + If there are ``match``: rules, then the ID field is a purely opaque name |
857 | + which is only being used for references from definitions of compound |
858 | + devices in the config. |
859 | + |
860 | +Virtual devices |
861 | + |
862 | +: (Examples: veth, bridge, bond) These are fully under the control of the |
863 | + config file(s) and the network stack. I. e. these devices are being created |
864 | + instead of matched. Thus ``match:`` and ``set-name:`` are not applicable for |
865 | + these, and the ID field is the name of the created virtual device. |
866 | + |
867 | +Common properties for physical device types |
868 | +------------------------------------------- |
869 | + |
870 | +**match**: *<(mapping)>* |
871 | + |
872 | +This selects a subset of available physical devices by various hardware |
873 | +properties. The following configuration will then apply to all matching |
874 | +devices, as soon as they appear. *All* specified properties must match. |
875 | +The following properties for creating matches are supported: |
876 | + |
877 | +**name**: *<(scalar)>* |
878 | + |
879 | +Current interface name. Globs are supported, and the primary use case |
880 | +for matching on names, as selecting one fixed name can be more easily |
881 | +achieved with having no ``match:`` at all and just using the ID (see |
882 | +above). Note that currently only networkd supports globbing, |
883 | +NetworkManager does not. |
884 | + |
885 | +**macaddress**: *<(scalar)>* |
886 | + |
887 | +Device's MAC address in the form "XX:XX:XX:XX:XX:XX". Globs are not allowed. |
888 | + |
889 | +**driver**: *<(scalar)>* |
890 | + |
891 | +Kernel driver name, corresponding to the ``DRIVER`` udev property. Globs are |
892 | +supported. Matching on driver is *only* supported with networkd. |
893 | + |
894 | +**Examples**:: |
895 | + |
896 | + # all cards on second PCI bus |
897 | + match: |
898 | + name: enp2* |
899 | + |
900 | + # fixed MAC address |
901 | + match: |
902 | + macaddress: 11:22:33:AA:BB:FF |
903 | + |
904 | + # first card of driver ``ixgbe`` |
905 | + match: |
906 | + driver: ixgbe |
907 | + name: en*s0 |
908 | + |
909 | +**set-name**: *<(scalar)>* |
910 | + |
911 | +When matching on unique properties such as path or MAC, or with additional |
912 | +assumptions such as "there will only ever be one wifi device", |
913 | +match rules can be written so that they only match one device. Then this |
914 | +property can be used to give that device a more specific/desirable/nicer |
915 | +name than the default from udev’s ifnames. Any additional device that |
916 | +satisfies the match rules will then fail to get renamed and keep the |
917 | +original kernel name (and dmesg will show an error). |
918 | + |
919 | +**wakeonlan**: *<(bool)>* |
920 | + |
921 | +Enable wake on LAN. Off by default. |
922 | + |
923 | + |
924 | +Common properties for all device types |
925 | +-------------------------------------- |
926 | + |
927 | +**renderer**: *<(scalar)>* |
928 | + |
929 | +Use the given networking backend for this definition. Currently supported are |
930 | +``networkd`` and ``NetworkManager``. This property can be specified globally |
931 | +in ``networks:``, for a device type (in e. g. ``ethernets:``) or |
932 | +for a particular device definition. Default is ``networkd``. |
933 | + |
934 | +.. note:: |
935 | + |
936 | + Cloud-init only supports networkd backend if rendering version2 config |
937 | + to the instance. |
938 | + |
939 | +**dhcp4**: *<(bool)>* |
940 | + |
941 | +Enable DHCP for IPv4. Off by default. |
942 | + |
943 | +**dhcp6**: *<(bool)>* |
944 | + |
945 | +Enable DHCP for IPv6. Off by default. |
946 | + |
947 | +**addresses**: *<(sequence of scalars)>* |
948 | + |
949 | +Add static addresses to the interface in addition to the ones received |
950 | +through DHCP or RA. Each sequence entry is in CIDR notation, i. e. of the |
951 | +form ``addr/prefixlen`` . ``addr`` is an IPv4 or IPv6 address as recognized |
952 | +by ``inet_pton``(3) and ``prefixlen`` the number of bits of the subnet. |
953 | + |
954 | +Example: ``addresses: [192.168.14.2/24, 2001:1::1/64]`` |
955 | + |
956 | +**gateway4**: or **gateway6**: *<(scalar)>* |
957 | + |
958 | +Set default gateway for IPv4/6, for manual address configuration. This |
959 | +requires setting ``addresses`` too. Gateway IPs must be in a form |
960 | +recognized by ``inet_pton(3)`` |
961 | + |
962 | +Example for IPv4: ``gateway4: 172.16.0.1`` |
963 | +Example for IPv6: ``gateway6: 2001:4::1`` |
964 | + |
965 | +**nameservers**: *<(mapping)>* |
966 | + |
967 | +Set DNS servers and search domains, for manual address configuration. There |
968 | +are two supported fields: ``addresses:`` is a list of IPv4 or IPv6 addresses |
969 | +similar to ``gateway*``, and ``search:`` is a list of search domains. |
970 | + |
971 | +Example: :: |
972 | + |
973 | + nameservers: |
974 | + search: [lab, home] |
975 | + addresses: [8.8.8.8, FEDC::1] |
976 | + |
977 | +**routes**: *<(sequence of mapping)>* |
978 | + |
979 | +Add device specific routes. Each mapping includes a ``to``, ``via`` key |
980 | +with an IPv4 or IPv6 address as value. ``metric`` is an optional value. |
981 | + |
982 | +Example: :: |
983 | + |
984 | + routes: |
985 | + - to: 0.0.0.0/0 |
986 | + via: 10.23.2.1 |
987 | + metric: 3 |
988 | + |
989 | +Ethernets |
990 | +~~~~~~~~~ |
991 | +Ethernet device definitions do not support any specific properties beyond the |
992 | +common ones described above. |
993 | + |
994 | +Bonds |
995 | +~~~~~ |
996 | + |
997 | +**interfaces** *<(sequence of scalars)>* |
998 | + |
999 | +All devices matching this ID list will be added to the bond. |
1000 | + |
1001 | +Example: :: |
1002 | + |
1003 | + ethernets: |
1004 | + switchports: |
1005 | + match: {name: "enp2*"} |
1006 | + [...] |
1007 | + bonds: |
1008 | + bond0: |
1009 | + interfaces: [switchports] |
1010 | + |
1011 | +**parameters**: *<(mapping)>* |
1012 | + |
1013 | +Customization parameters for special bonding options. Time values are specified |
1014 | +in seconds unless otherwise specified. |
1015 | + |
1016 | +**mode**: *<(scalar)>* |
1017 | + |
1018 | +Set the bonding mode used for the interfaces. The default is |
1019 | +``balance-rr`` (round robin). Possible values are ``balance-rr``, |
1020 | +``active-backup``, ``balance-xor``, ``broadcast``, ``802.3ad``, |
1021 | +``balance-tlb``, and ``balance-alb``. |
1022 | + |
1023 | +**lacp-rate**: *<(scalar)>* |
1024 | + |
1025 | +Set the rate at which LACPDUs are transmitted. This is only useful |
1026 | +in 802.3ad mode. Possible values are ``slow`` (30 seconds, default), |
1027 | +and ``fast`` (every second). |
1028 | + |
1029 | +**mii-monitor-interval**: *<(scalar)>* |
1030 | + |
1031 | +Specifies the interval for MII monitoring (verifying if an interface |
1032 | +of the bond has carrier). The default is ``0``; which disables MII |
1033 | +monitoring. |
1034 | + |
1035 | +**min-links**: *<(scalar)>* |
1036 | + |
1037 | +The minimum number of links up in a bond to consider the bond |
1038 | +interface to be up. |
1039 | + |
1040 | +**transmit-hash-policy**: <*(scalar)>* |
1041 | + |
1042 | +Specifies the transmit hash policy for the selection of slaves. This |
1043 | +is only useful in balance-xor, 802.3ad and balance-tlb modes. |
1044 | +Possible values are ``layer2``, ``layer3+4``, ``layer2+3``, |
1045 | +``encap2+3``, and ``encap3+4``. |
1046 | + |
1047 | +**ad-select**: <*(scalar)>* |
1048 | + |
1049 | +Set the aggregation selection mode. Possible values are ``stable``, |
1050 | +``bandwidth``, and ``count``. This option is only used in 802.3ad mode. |
1051 | + |
1052 | +**all-slaves-active**: <*(bool)>* |
1053 | + |
1054 | +If the bond should drop duplicate frames received on inactive ports, |
1055 | +set this option to ``false``. If they should be delivered, set this |
1056 | +option to ``true``. The default value is false, and is the desirable |
1057 | +behavior in most situations. |
1058 | + |
1059 | +**arp-interval**: <*(scalar)>* |
1060 | + |
1061 | +Set the interval value for how frequently ARP link monitoring should |
1062 | +happen. The default value is ``0``, which disables ARP monitoring. |
1063 | + |
1064 | +**arp-ip-targets**: <*(sequence of scalars)>* |
1065 | + |
1066 | +IPs of other hosts on the link which should be sent ARP requests in |
1067 | +order to validate that a slave is up. This option is only used when |
1068 | +``arp-interval`` is set to a value other than ``0``. At least one IP |
1069 | +address must be given for ARP link monitoring to function. Only IPv4 |
1070 | +addresses are supported. You can specify up to 16 IP addresses. The |
1071 | +default value is an empty list. |
1072 | + |
1073 | +**arp-validate**: <*(scalar)>* |
1074 | + |
1075 | +Configure how ARP replies are to be validated when using ARP link |
1076 | +monitoring. Possible values are ``none``, ``active``, ``backup``, |
1077 | +and ``all``. |
1078 | + |
1079 | +**arp-all-targets**: <*(scalar)>* |
1080 | + |
1081 | +Specify whether to use any ARP IP target being up as sufficient for |
1082 | +a slave to be considered up; or if all the targets must be up. This |
1083 | +is only used for ``active-backup`` mode when ``arp-validate`` is |
1084 | +enabled. Possible values are ``any`` and ``all``. |
1085 | + |
1086 | +**up-delay**: <*(scalar)>* |
1087 | + |
1088 | +Specify the delay before enabling a link once the link is physically |
1089 | +up. The default value is ``0``. |
1090 | + |
1091 | +**down-delay**: <*(scalar)>* |
1092 | + |
1093 | +Specify the delay before disabling a link once the link has been |
1094 | +lost. The default value is ``0``. |
1095 | + |
1096 | +**fail-over-mac-policy**: <*(scalar)>* |
1097 | + |
1098 | +Set whether to set all slaves to the same MAC address when adding |
1099 | +them to the bond, or how else the system should handle MAC addresses. |
1100 | +The possible values are ``none``, ``active``, and ``follow``. |
1101 | + |
1102 | +**gratuitious-arp**: <*(scalar)>* |
1103 | + |
1104 | +Specify how many ARP packets to send after failover. Once a link is |
1105 | +up on a new slave, a notification is sent and possibly repeated if |
1106 | +this value is set to a number greater than ``1``. The default value |
1107 | +is ``1`` and valid values are between ``1`` and ``255``. This only |
1108 | +affects ``active-backup`` mode. |
1109 | + |
1110 | +**packets-per-slave**: <*(scalar)>* |
1111 | + |
1112 | +In ``balance-rr`` mode, specifies the number of packets to transmit |
1113 | +on a slave before switching to the next. When this value is set to |
1114 | +``0``, slaves are chosen at random. Allowable values are between |
1115 | +``0`` and ``65535``. The default value is ``1``. This setting is |
1116 | +only used in ``balance-rr`` mode. |
1117 | + |
1118 | +**primary-reselect-policy**: <*(scalar)>* |
1119 | + |
1120 | +Set the reselection policy for the primary slave. On failure of the |
1121 | +active slave, the system will use this policy to decide how the new |
1122 | +active slave will be chosen and how recovery will be handled. The |
1123 | +possible values are ``always``, ``better``, and ``failure``. |
1124 | + |
1125 | +**learn-packet-interval**: <*(scalar)>* |
1126 | + |
1127 | +Specify the interval between sending learning packets to each slave. |
1128 | +The value range is between ``1`` and ``0x7fffffff``. The default |
1129 | +value is ``1``. This option only affects ``balance-tlb`` and |
1130 | +``balance-alb`` modes. |
1131 | + |
1132 | + |
1133 | +Bridges |
1134 | +~~~~~~~ |
1135 | + |
1136 | +**interfaces**: <*(sequence of scalars)>* |
1137 | + |
1138 | +All devices matching this ID list will be added to the bridge. |
1139 | + |
1140 | +Example: :: |
1141 | + |
1142 | + ethernets: |
1143 | + switchports: |
1144 | + match: {name: "enp2*"} |
1145 | + [...] |
1146 | + bridges: |
1147 | + br0: |
1148 | + interfaces: [switchports] |
1149 | + |
1150 | +**parameters**: <*(mapping)>* |
1151 | + |
1152 | +Customization parameters for special bridging options. Time values are specified |
1153 | +in seconds unless otherwise specified. |
1154 | + |
1155 | +**ageing-time**: <*(scalar)>* |
1156 | + |
1157 | +Set the period of time to keep a MAC address in the forwarding |
1158 | +database after a packet is received. |
1159 | + |
1160 | +**priority**: <*(scalar)>* |
1161 | + |
1162 | +Set the priority value for the bridge. This value should be an |
1163 | +number between ``0`` and ``65535``. Lower values mean higher |
1164 | +priority. The bridge with the higher priority will be elected as |
1165 | +the root bridge. |
1166 | + |
1167 | +**forward-delay**: <*(scalar)>* |
1168 | + |
1169 | +Specify the period of time the bridge will remain in Listening and |
1170 | +Learning states before getting to the Forwarding state. This value |
1171 | +should be set in seconds for the systemd backend, and in milliseconds |
1172 | +for the NetworkManager backend. |
1173 | + |
1174 | +**hello-time**: <*(scalar)>* |
1175 | + |
1176 | +Specify the interval between two hello packets being sent out from |
1177 | +the root and designated bridges. Hello packets communicate |
1178 | +information about the network topology. |
1179 | + |
1180 | +**max-age**: <*(scalar)>* |
1181 | + |
1182 | +Set the maximum age of a hello packet. If the last hello packet is |
1183 | +older than that value, the bridge will attempt to become the root |
1184 | +bridge. |
1185 | + |
1186 | +**path-cost**: <*(scalar)>* |
1187 | + |
1188 | +Set the cost of a path on the bridge. Faster interfaces should have |
1189 | +a lower cost. This allows a finer control on the network topology |
1190 | +so that the fastest paths are available whenever possible. |
1191 | + |
1192 | +**stp**: <*(bool)>* |
1193 | + |
1194 | +Define whether the bridge should use Spanning Tree Protocol. The |
1195 | +default value is "true", which means that Spanning Tree should be |
1196 | +used. |
1197 | + |
1198 | + |
1199 | +VLANs |
1200 | +~~~~~ |
1201 | + |
1202 | +**id**: <*(scalar)>* |
1203 | + |
1204 | +VLAN ID, a number between 0 and 4094. |
1205 | + |
1206 | +**link**: <*(scalar)>* |
1207 | + |
1208 | +ID of the underlying device definition on which this VLAN gets |
1209 | +created. |
1210 | + |
1211 | +Example: :: |
1212 | + |
1213 | + ethernets: |
1214 | + eno1: {...} |
1215 | + vlans: |
1216 | + en-intra: |
1217 | + id: 1 |
1218 | + link: eno1 |
1219 | + dhcp4: yes |
1220 | + en-vpn: |
1221 | + id: 2 |
1222 | + link: eno1 |
1223 | + address: ... |
1224 | + |
1225 | + |
1226 | +Examples |
1227 | +-------- |
1228 | +Configure an ethernet device with networkd, identified by its name, and enable |
1229 | +DHCP: :: |
1230 | + |
1231 | + network: |
1232 | + version: 2 |
1233 | + ethernets: |
1234 | + eno1: |
1235 | + dhcp4: true |
1236 | + |
1237 | +This is a complex example which shows most available features: :: |
1238 | + |
1239 | + network: |
1240 | + version: 2 |
1241 | + ethernets: |
1242 | + # opaque ID for physical interfaces, only referred to by other stanzas |
1243 | + id0: |
1244 | + match: |
1245 | + macaddress: 00:11:22:33:44:55 |
1246 | + wakeonlan: true |
1247 | + dhcp4: true |
1248 | + addresses: |
1249 | + - 192.168.14.2/24 |
1250 | + - 2001:1::1/64 |
1251 | + gateway4: 192.168.14.1 |
1252 | + gateway6: 2001:1::2 |
1253 | + nameservers: |
1254 | + search: [foo.local, bar.local] |
1255 | + addresses: [8.8.8.8] |
1256 | + lom: |
1257 | + match: |
1258 | + driver: ixgbe |
1259 | + # you are responsible for setting tight enough match rules |
1260 | + # that only match one device if you use set-name |
1261 | + set-name: lom1 |
1262 | + dhcp6: true |
1263 | + switchports: |
1264 | + # all cards on second PCI bus; unconfigured by themselves, will be added |
1265 | + # to br0 below |
1266 | + match: |
1267 | + name: enp2* |
1268 | + mtu: 1280 |
1269 | + bonds: |
1270 | + bond0: |
1271 | + interfaces: [id0, lom] |
1272 | + bridges: |
1273 | + # the key name is the name for virtual (created) interfaces; no match: and |
1274 | + # set-name: allowed |
1275 | + br0: |
1276 | + # IDs of the components; switchports expands into multiple interfaces |
1277 | + interfaces: [wlp1s0, switchports] |
1278 | + dhcp4: true |
1279 | + vlans: |
1280 | + en-intra: |
1281 | + id: 1 |
1282 | + link: id0 |
1283 | + dhcp4: yes |
1284 | + # static routes |
1285 | + routes: |
1286 | + - to: 0.0.0.0/0 |
1287 | + via: 11.0.0.1 |
1288 | + metric: 3 |
1289 | + |
1290 | +.. _netplan: https://launchpad.net/netplan |
1291 | +.. vi: textwidth=78 |
1292 | diff --git a/doc/rtd/topics/network-config.rst b/doc/rtd/topics/network-config.rst |
1293 | new file mode 100644 |
1294 | index 0000000..cd2480a |
1295 | --- /dev/null |
1296 | +++ b/doc/rtd/topics/network-config.rst |
1297 | @@ -0,0 +1,252 @@ |
1298 | +********************* |
1299 | +Network Configuration |
1300 | +********************* |
1301 | + |
1302 | +- Default Behavior |
1303 | +- Disabling Network Configuration |
1304 | +- Fallback Networking |
1305 | +- Network Configuration Sources |
1306 | +- Network Configuration Outputs |
1307 | +- Network Output Policy |
1308 | +- Network Configuration Tools |
1309 | +- Examples |
1310 | + |
1311 | +.. _default_behavior: |
1312 | + |
1313 | +Default Behavior |
1314 | +================ |
1315 | + |
1316 | +`Cloud-init`_ 's searches for network configuration in order of increasing |
1317 | +precedence; each item overriding the previous. |
1318 | + |
1319 | +**Datasource** |
1320 | + |
1321 | +For example, OpenStack may provide network config in the MetaData Service. |
1322 | + |
1323 | +**System Config** |
1324 | + |
1325 | +A ``network:`` entry in /etc/cloud/cloud.cfg.d/* configuration files. |
1326 | + |
1327 | +**Kernel Command Line** |
1328 | + |
1329 | +``ip=`` or ``network-config=<YAML config string>`` |
1330 | + |
1331 | +User-data cannot change an instance's network configuration. In the absense |
1332 | +of network configuration in any of the above sources , `Cloud-init`_ will |
1333 | +write out a network configuration that will issue a DHCP request on a "first" |
1334 | +network interface. |
1335 | + |
1336 | + |
1337 | +Disabling Network Configuration |
1338 | +=============================== |
1339 | + |
1340 | +Users may disable `Cloud-init`_ 's network configuration capability and rely |
1341 | +on other methods, such as embedded configuration or other customizations. |
1342 | + |
1343 | +`Cloud-init`_ supports the following methods for disabling cloud-init. |
1344 | + |
1345 | + |
1346 | +**Kernel Command Line** |
1347 | + |
1348 | +`Cloud-init`_ will check for a parameter ``network-config`` and the |
1349 | +value is expected to be YAML string in the :ref:`network_config_v1` format. |
1350 | +The YAML string may optionally be ``Base64`` encoded, and optionally |
1351 | +compressed with ``gzip``. |
1352 | + |
1353 | +Example disabling kernel command line entry: :: |
1354 | + |
1355 | + network-config={config: disabled} |
1356 | + |
1357 | + |
1358 | +**cloud config** |
1359 | + |
1360 | +In the combined cloud-init configuration dictionary. :: |
1361 | + |
1362 | + network: |
1363 | + config: disabled |
1364 | + |
1365 | +If `Cloud-init`_ 's networking config has not been disabled, and |
1366 | +no other network information is found, then it will proceed |
1367 | +to generate a fallback networking configuration. |
1368 | + |
1369 | + |
1370 | +Fallback Network Configuration |
1371 | +============================== |
1372 | + |
1373 | +`Cloud-init`_ will attempt to determine which of any attached network devices |
1374 | +is most likely to have a connection and then generate a network |
1375 | +configuration to issue a DHCP request on that interface. |
1376 | + |
1377 | +`Cloud-init`_ runs during early boot and does not expect composed network |
1378 | +devices (such as Bridges) to be available. `Cloud-init`_ does not consider |
1379 | +the following interface devices as likely 'first' network interfaces for |
1380 | +fallback configuration; they are filtered out from being selected. |
1381 | + |
1382 | +- **loopback**: ``name=lo`` |
1383 | +- **Virtual Ethernet**: ``name=veth*`` |
1384 | +- **Software Bridges**: ``type=bridge`` |
1385 | +- **Software VLANs**: ``type=vlan`` |
1386 | + |
1387 | + |
1388 | +`Cloud-init`_ will prefer network interfaces that indicate they are connected |
1389 | +via the Linux ``carrier`` flag being set. If no interfaces are marked |
1390 | +connected, then all unfiltered interfaces are potential connections. |
1391 | + |
1392 | +Of the potential interfaces, `Cloud-init`_ will attempt to pick the "right" |
1393 | +interface given the information it has available. |
1394 | + |
1395 | +Finally after selecting the "right" interface, a configuration is |
1396 | +generated and applied to the system. |
1397 | + |
1398 | + |
1399 | +Network Configuration Sources |
1400 | +============================= |
1401 | + |
1402 | +`Cloud-init`_ accepts a number of different network configuration formats in |
1403 | +support of different cloud substrates. The Datasource for these clouds in |
1404 | +`Cloud-init`_ will detect and consume Datasource-specific network configuration |
1405 | +formats for use when writing an instance's network configuration. |
1406 | + |
1407 | +The following Datasources optionally provide network configuration: |
1408 | + |
1409 | +- :ref:`datasource_config_drive` |
1410 | + |
1411 | + - `OpenStack Metadata Service Network`_ |
1412 | + - :ref:`network_config_eni` |
1413 | + |
1414 | +- :ref:`datasource_digital_ocean` |
1415 | + |
1416 | + - `DigitalOcean JSON metadata`_ |
1417 | + |
1418 | +- :ref:`datasource_nocloud` |
1419 | + |
1420 | + - :ref:`network_config_v1` |
1421 | + - :ref:`network_config_v2` |
1422 | + - :ref:`network_config_eni` |
1423 | + |
1424 | +- :ref:`datasource_opennebula` |
1425 | + |
1426 | + - :ref:`network_config_eni` |
1427 | + |
1428 | +- :ref:`datasource_openstack` |
1429 | + |
1430 | + - :ref:`network_config_eni` |
1431 | + - `OpenStack Metadata Service Network`_ |
1432 | + |
1433 | +- :ref:`datasource_smartos` |
1434 | + |
1435 | + - `SmartOS JSON Metadata`_ |
1436 | + |
1437 | +For more information on network configuration formats |
1438 | + |
1439 | +.. toctree:: |
1440 | + :maxdepth: 1 |
1441 | + |
1442 | + network-config-format-eni.rst |
1443 | + network-config-format-v1.rst |
1444 | + network-config-format-v2.rst |
1445 | + |
1446 | + |
1447 | +Network Configuration Outputs |
1448 | +============================= |
1449 | + |
1450 | +`Cloud-init`_ converts various forms of user supplied or automatically |
1451 | +generated configuration into an internal network configuration state. From |
1452 | +this state `Cloud-init`_ delegates rendering of the configuration to Distro |
1453 | +supported formats. The following ``renderers`` are supported in cloud-init: |
1454 | + |
1455 | +- **ENI** |
1456 | + |
1457 | +/etc/network/interfaces or ``ENI`` is supported by the ``ifupdown`` package |
1458 | +found in Ubuntu and Debian. |
1459 | + |
1460 | +- **Netplan** |
1461 | + |
1462 | +Since Ubuntu 16.10, codename Yakkety, the ``netplan`` project has been an |
1463 | +optional network configuration tool which consumes :ref:`network_config_v2` |
1464 | +input and renders network configuration for supported backends such as |
1465 | +``systemd-networkd`` and ``NetworkManager``. |
1466 | + |
1467 | +- **Sysconfig** |
1468 | + |
1469 | +Sysconfig format is used by RHEL, CentOS, Fedora and other derivatives. |
1470 | + |
1471 | + |
1472 | +Network Output Policy |
1473 | +===================== |
1474 | + |
1475 | +The default policy for selecting a network ``renderer`` in order of preference |
1476 | +is as follows: |
1477 | + |
1478 | +- ENI |
1479 | +- Sysconfig |
1480 | +- Netplan |
1481 | + |
1482 | +When applying the policy, `Cloud-init`_ checks if the current instance has the |
1483 | +correct binaries and paths to support the renderer. The first renderer that |
1484 | +can be used is selected. Users may override the network renderer policy by |
1485 | +supplying an updated configuration in cloud-config. :: |
1486 | + |
1487 | + system_info: |
1488 | + network: |
1489 | + renderers: ['netplan', 'eni', 'sysconfig'] |
1490 | + |
1491 | + |
1492 | +Network Configuration Tools |
1493 | +=========================== |
1494 | + |
1495 | +`Cloud-init`_ contains one tool used to test input/output conversion between |
1496 | +formats. The ``tools/net-convert.py`` in the `Cloud-init`_ source repository |
1497 | +is helpful for examining expected output for a given input format. |
1498 | + |
1499 | +CLI Interface : |
1500 | + |
1501 | +.. code-block:: bash |
1502 | + |
1503 | + % tools/net-convert.py --help |
1504 | + usage: net-convert.py [-h] --network-data PATH --kind |
1505 | + {eni,network_data.json,yaml} -d PATH [-m name,mac] |
1506 | + --output-kind {eni,netplan,sysconfig} |
1507 | + |
1508 | + optional arguments: |
1509 | + -h, --help show this help message and exit |
1510 | + --network-data PATH, -p PATH |
1511 | + --kind {eni,network_data.json,yaml}, -k {eni,network_data.json,yaml} |
1512 | + -d PATH, --directory PATH |
1513 | + directory to place output in |
1514 | + -m name,mac, --mac name,mac |
1515 | + interface name to mac mapping |
1516 | + --output-kind {eni,netplan,sysconfig}, -ok {eni,netplan,sysconfig} |
1517 | + |
1518 | + |
1519 | +Example output convertion V2 to sysconfig: |
1520 | + |
1521 | +.. code-block:: bash |
1522 | + |
1523 | + % tools/net-convert.py --network-data v2.yaml --kind yaml --output-kind sysconfig -d target |
1524 | + % cat target/etc/sysconfig/network-scripts/ifcfg-eth* |
1525 | + # Created by cloud-init on instance boot automatically, do not edit. |
1526 | + # |
1527 | + BOOTPROTO=static |
1528 | + DEVICE=eth7 |
1529 | + IPADDR=192.168.1.5/255.255.255.0 |
1530 | + NM_CONTROLLED=no |
1531 | + ONBOOT=yes |
1532 | + TYPE=Ethernet |
1533 | + USERCTL=no |
1534 | + # Created by cloud-init on instance boot automatically, do not edit. |
1535 | + # |
1536 | + BOOTPROTO=dhcp |
1537 | + DEVICE=eth9 |
1538 | + NM_CONTROLLED=no |
1539 | + ONBOOT=yes |
1540 | + TYPE=Ethernet |
1541 | + USERCTL=no |
1542 | + |
1543 | + |
1544 | +.. _Cloud-init: https://launchpad.net/cloud-init |
1545 | +.. _DigitalOcean JSON metadata: https://developers.digitalocean.com/documentation/metadata/#network-interfaces-index |
1546 | +.. _OpenStack Metadata Service Network: https://specs.openstack.org/openstack/nova-specs/specs/liberty/implemented/metadata-service-network-info.html |
1547 | +.. _SmartOS JSON Metadata: https://eng.joyent.com/mdata/datadict.html |
1548 | + |
1549 | +.. vi: textwidth=78 |
PASSED: Continuous integration, rev:74058c611b4 7210e697aa965f0 75d43013dbdeed /jenkins. ubuntu. com/server/ job/cloud- init-ci/ 184/ /jenkins. ubuntu. com/server/ job/cloud- init-ci/ nodes=metal- amd64/184 /jenkins. ubuntu. com/server/ job/cloud- init-ci/ nodes=metal- arm64/184 /jenkins. ubuntu. com/server/ job/cloud- init-ci/ nodes=metal- ppc64el/ 184 /jenkins. ubuntu. com/server/ job/cloud- init-ci/ nodes=metal- s390x/184 /jenkins. ubuntu. com/server/ job/cloud- init-ci/ nodes=vm- i386/184
https:/
Executed test runs:
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
SUCCESS: https:/
Click here to trigger a rebuild: /jenkins. ubuntu. com/server/ job/cloud- init-ci/ 184/rebuild
https:/