]>
Commit | Line | Data |
---|---|---|
2c8c4ce7 RP |
1 | .. index:: ifupdown |
2 | ||
3 | .. _ifupdown: | |
4 | ||
5 | ********** | |
6 | User Guide | |
7 | ********** | |
8 | ||
9 | Keep the following points in mind before you start configuring interfaces using | |
10 | ``ifupdown2``: | |
11 | ||
12 | * IPv4 and IPv6 addresses for an interface can be listed in the same ``iface`` | |
d486dd0d | 13 | section. For examples, see ``/usr/share/doc/ifupdown2/examples/``. |
2c8c4ce7 RP |
14 | |
15 | * Do not use a legacy interface alias. They are only supported for backward | |
16 | compatibility with ``ifupdown``. They do get configured, but ``ifquery`` has | |
17 | problems recognizing them. | |
18 | ||
19 | * ``ifupdown`` only understands interfaces that were configured using | |
20 | ``ifupdown``. Any interfaces created with a command other than ``ifupdown`` | |
21 | (like ``brctl``) must be de-configured in the same manner. | |
22 | ||
23 | * Use globs for port lists wherever applicable. Regular expressions work as well, | |
24 | however regular expressions require all matching interfaces to be present in | |
25 | the ``interfaces`` file. And declaring all interfaces in the ``interfaces`` | |
26 | file leads to losing all the advantages that built-in interfaces provide. | |
27 | ||
28 | * Extensions to ``ifquery`` help with validation and debugging. | |
29 | ||
30 | * By default, ``ifupdown`` is quiet; use the verbose option ``-v`` when you want | |
31 | to know what is going on when bringing an interface down or up. | |
32 | ||
33 | Contents | |
34 | ======== | |
35 | * `Commands`_ | |
36 | * `Man Pages`_ | |
37 | * `Configuration Files`_ | |
38 | * `ifupdown Built-in Interfaces`_ | |
39 | * `ifupdown Interface Dependencies`_ | |
40 | * `Configuring IP Addresses`_ | |
41 | * `Specifying User Commands`_ | |
42 | * `Sourcing Interface File Snippets`_ | |
43 | * `Using Globs for Port Lists`_ | |
44 | * `Using Templates`_ | |
45 | * `Using ifquery to Validate and Debug Interface Configurations`_ | |
46 | * `Useful Links`_ | |
47 | ||
48 | Commands | |
49 | ======== | |
50 | ||
51 | * ifdown | |
52 | * ifquery | |
53 | * ifreload | |
54 | * ifup | |
55 | ||
56 | Man Pages | |
57 | ========= | |
58 | ||
59 | * man ifdown(8) | |
60 | * man ifquery(8) | |
61 | * man ifreload | |
62 | * man ifup(8) | |
63 | * man ifupdown-addons-interfaces(5) | |
64 | * man interfaces(5) | |
65 | ||
66 | Configuration Files | |
67 | =================== | |
68 | ||
1e6d7bd7 | 69 | * config file defined in ifupdown2.conf (default /etc/network/interfaces) |
2c8c4ce7 RP |
70 | |
71 | ||
72 | ifupdown Built-in Interfaces | |
73 | ============================ | |
74 | ||
75 | ``ifupdown`` understands VLAN interfaces and physical interfaces that may appear | |
76 | as dependents. There is no need to list them unless they need the specific | |
77 | configuration or they need to match a regular expression used in the | |
78 | ``interfaces`` file. Use globs to avoid limitations with regular expressions. | |
79 | ||
80 | For example, swp1.100 and swp2.100 below do not need an entry in the | |
81 | ``interfaces`` file:: | |
82 | ||
83 | auto br-100 | |
84 | iface br-100 | |
85 | address 10.0.12.2/24 | |
86 | address 2001:dad:beef::3/64 | |
87 | bridge-ports swp1.100 swp2.100 | |
88 | bridge-stp on | |
89 | ||
90 | ||
91 | ||
92 | ifupdown Interface Dependencies | |
93 | =============================== | |
94 | ||
95 | ``ifupdown`` understands interface dependency relationships. When ``ifup`` and | |
96 | ``ifdown`` are run with all interfaces, they always run with all interfaces | |
97 | in dependency order. When run with the interface list on the command line, the | |
98 | default behavior is to not run with dependents. But if there are any built-in | |
99 | dependents, they will be brought up or down. | |
100 | ||
101 | To run with dependents when you specify the interface list, use the | |
102 | ``--with-depends`` option. ``--with-depends`` walks through all dependents | |
103 | in the dependency tree rooted at the interface you specify. Consider the | |
104 | following example configuration:: | |
105 | ||
106 | auto bond1 | |
107 | iface bond1 | |
108 | address 100.0.0.2/16 | |
109 | bond-slaves swp29 swp30 | |
110 | bond-mode 802.3ad | |
111 | bond-miimon 100 | |
594fb088 | 112 | bond-use-carrier yes |
2c8c4ce7 RP |
113 | bond-lacp-rate 1 |
114 | bond-min-links 1 | |
115 | bond-xmit-hash-policy layer3+4 | |
116 | ||
117 | auto bond2 | |
118 | iface bond2 | |
119 | address 100.0.0.5/16 | |
120 | bond-slaves swp31 swp32 | |
121 | bond-mode 802.3ad | |
122 | bond-miimon 100 | |
594fb088 | 123 | bond-use-carrier yes |
2c8c4ce7 RP |
124 | bond-lacp-rate 1 |
125 | bond-min-links 1 | |
126 | bond-xmit-hash-policy layer3+4 | |
127 | ||
128 | auto br2001 | |
129 | iface br2001 | |
130 | address 12.0.1.3/24 | |
131 | bridge-ports bond1.2001 bond2.2001 | |
132 | bridge-stp on | |
133 | ||
134 | Specifying ``ifup --with-depends br2001`` brings up all dependents: bond1.2001, | |
135 | bond2.2001, bond1, bond2, bond1.2001, bond2.2001, swp29, swp30, swp31, swp32. | |
136 | ||
137 | Similarly, specifying ``ifdown --with-depends br2001`` brings down all | |
138 | dependents: bond1.2001, bond2.2001, bond1, bond2, bond1.2001, bond2.2001, swp29, | |
139 | swp30, swp31, swp32. | |
140 | ||
141 | .. warning:: ``ifdown`` always deletes logical interfaces after bringing them | |
142 | down. Use the ``--admin-state`` option if you only want to administratively | |
143 | bring the interface up or down. In terms of the above example, | |
144 | ``ifdown br2001`` deletes ``br2001``. | |
145 | ||
146 | To guide you through which interfaces will be brought down and up, use the | |
147 | ``--print-dependency`` option to get the list of dependents. | |
148 | ||
149 | Use ``ifup --print-dependency=list -a`` to get the dependency list of all | |
150 | interfaces:: | |
151 | ||
152 | cumulus@switch:~$ sudo ifup --print-dependency=list -a | |
153 | lo : None | |
154 | eth0 : None | |
155 | bond0 : ['swp25', 'swp26'] | |
156 | bond1 : ['swp29', 'swp30'] | |
157 | bond2 : ['swp31', 'swp32'] | |
158 | br0 : ['bond1', 'bond2'] | |
159 | bond1.2000 : ['bond1'] | |
160 | bond2.2000 : ['bond2'] | |
161 | br2000 : ['bond1.2000', 'bond2.2000'] | |
162 | bond1.2001 : ['bond1'] | |
163 | bond2.2001 : ['bond2'] | |
164 | br2001 : ['bond1.2001', 'bond2.2001'] | |
165 | swp40 : None | |
166 | swp25 : None | |
167 | swp26 : None | |
168 | swp29 : None | |
169 | swp30 : None | |
170 | swp31 : None | |
171 | swp32 : None | |
172 | ||
173 | To print the dependency list of a single interface, use:: | |
174 | ||
175 | cumulus@switch:~$ sudo ifup --print-dependency=list br2001 | |
176 | br2001 : ['bond1.2001', 'bond2.2001'] | |
177 | bond1.2001 : ['bond1'] | |
178 | bond2.2001 : ['bond2'] | |
179 | bond1 : ['swp29', 'swp30'] | |
180 | bond2 : ['swp31', 'swp32'] | |
181 | swp29 : None | |
182 | swp30 : None | |
183 | swp31 : None | |
184 | swp32 : None | |
185 | ||
186 | ||
187 | To print the dependency information of an interface in ``dot`` format:: | |
188 | ||
189 | cumulus@switch:~$ sudo ifup --print-dependency=dot br2001 | |
190 | /* Generated by GvGen v.0.9 (http://software.inl.fr/trac/wiki/GvGen) */ | |
191 | digraph G { | |
192 | compound=true; | |
193 | node1 [label="br2001"]; | |
194 | node2 [label="bond1.2001"]; | |
195 | node3 [label="bond2.2001"]; | |
196 | node4 [label="bond1"]; | |
197 | node5 [label="bond2"]; | |
198 | node6 [label="swp29"]; | |
199 | node7 [label="swp30"]; | |
200 | node8 [label="swp31"]; | |
201 | node9 [label="swp32"]; | |
202 | node1->node2; | |
203 | node1->node3; | |
204 | node2->node4; | |
205 | node3->node5; | |
206 | node4->node6; | |
207 | node4->node7; | |
208 | node5->node8; | |
209 | node5->node9; | |
210 | } | |
211 | ||
212 | You can use ``dot`` to render the graph on an external system where ``dot`` is | |
213 | installed. | |
214 | ||
215 | .. image:: images/interfaces.png | |
216 | ||
217 | ||
218 | To print the dependency information of the entire ``interfaces`` file:: | |
219 | ||
220 | cumulus@switch:~$ sudo ifup --print-dependency=dot -a >interfaces_all.dot | |
221 | ||
222 | .. image:: images/interfaces_all.png | |
223 | :width: 800px | |
224 | ||
225 | ||
226 | .. note: The '--print-dependency' option is available with the ``ifup``, | |
227 | ``ifdown`` and ``ifquery`` commands. | |
228 | ||
229 | ||
230 | Configuring IP Addresses | |
231 | ======================== | |
232 | ||
233 | In ``/etc/network/interfaces``, list all IP addresses as shown below under the | |
234 | ``iface`` section (see ``man interfaces`` for more information):: | |
235 | ||
236 | auto swp1 | |
237 | iface swp1 | |
238 | address 12.0.0.1/30 | |
239 | address 12.0.0.2/30 | |
240 | ||
241 | The address method and address family are not mandatory. They default to | |
242 | ``inet``/``inet6`` and ``static`` by default, but ``inet``/``inet6`` **must** be | |
243 | specified if you need to specify ``dhcp`` or ``loopback``. | |
244 | ||
245 | You can specify both IPv4 and IPv6 addresses under the same ``iface`` section:: | |
246 | ||
247 | auto swp1 | |
248 | iface swp1 | |
249 | address 12.0.0.1/30 | |
250 | address 12.0.0.2/30 | |
251 | address 2001:dee:eeef:2::1/64 | |
252 | ||
253 | Specifying User Commands | |
254 | ======================== | |
255 | ||
256 | You can specify additional user commands in the ``interfaces`` file. As shown in | |
257 | the example below, the interface stanzas in ``/etc/network/interfaces`` can have | |
258 | a command that runs at pre-up, up, post-up, pre-down, down, and post-down:: | |
259 | ||
260 | auto swp1 | |
261 | iface swp1 | |
262 | address 12.0.0.1/30 | |
263 | up /sbin/foo bar | |
264 | ||
265 | Any valid command can be hooked in the sequencing of bringing an interface up or | |
266 | down, although commands should be limited in scope to network-related commands | |
267 | associated with the particular interface. | |
268 | ||
269 | For example, it wouldn't make sense to install some Debian package on ``ifup`` | |
270 | of swp1, even though that is technically possible. See ``man interfaces`` for | |
271 | more details. | |
272 | ||
273 | Sourcing Interface File Snippets | |
274 | ================================ | |
275 | ||
276 | Sourcing interface files helps organize and manage the ``interfaces(5)`` file. | |
277 | For example:: | |
278 | ||
279 | cumulus@switch:~$ cat /etc/network/interfaces | |
280 | # The loopback network interface | |
281 | auto lo | |
282 | iface lo inet loopback | |
283 | ||
284 | # The primary network interface | |
285 | auto eth0 | |
286 | iface eth0 inet dhcp | |
287 | ||
288 | source /etc/network/interfaces.d/bond0 | |
289 | ||
290 | ||
291 | The contents of the sourced file used above are:: | |
292 | ||
293 | cumulus@switch:~$ cat /etc/network/interfaces.d/bond0 | |
294 | auto bond0 | |
295 | iface bond0 | |
296 | address 14.0.0.9/30 | |
297 | address 2001:ded:beef:2::1/64 | |
298 | bond-slaves swp25 swp26 | |
299 | bond-mode 802.3ad | |
300 | bond-miimon 100 | |
594fb088 | 301 | bond-use-carrier yes |
2c8c4ce7 RP |
302 | bond-lacp-rate 1 |
303 | bond-min-links 1 | |
304 | bond-xmit-hash-policy layer3+4 | |
305 | ||
306 | Using Globs for Port Lists | |
307 | ========================== | |
308 | ||
309 | Some modules support globs to describe port lists. You can use globs to specify | |
310 | bridge ports and bond slaves:: | |
311 | ||
312 | auto br0 | |
313 | iface br0 | |
314 | bridge-ports glob swp1-6.100 | |
315 | ||
316 | auto br1 | |
317 | iface br1 | |
318 | bridge-ports glob swp7-9.100 swp11.100 glob swp15-18.100 | |
319 | ||
139662ee ST |
320 | auto br2 |
321 | iface br2 | |
322 | bridge-ports glob swp[1-6]s[0-3].100 | |
323 | ||
2c8c4ce7 RP |
324 | Using Templates |
325 | =============== | |
326 | ||
327 | ``ifupdown2`` supports Mako-style templates. For more information see | |
328 | `www.makotemplates.org <http://www.makotemplates.org/>`_. The Mako template | |
329 | engine is run over the ``interfaces`` file before parsing. | |
330 | ||
331 | Use the template to declare cookie-cutter bridges in the ``interfaces`` file:: | |
332 | ||
333 | %for v in [11,12]: | |
334 | auto vlan${v} | |
335 | iface vlan${v} | |
336 | address 10.20.${v}.3/24 | |
337 | bridge-ports glob swp19-20.${v} | |
338 | bridge-stp on | |
339 | %endfor | |
340 | ||
341 | ||
342 | And use it to declare addresses in the ``interfaces`` file:: | |
343 | ||
344 | %for i in [1,12]: | |
345 | auto swp${i} | |
346 | iface swp${i} | |
347 | address 10.20.${i}.3/24 | |
348 | ||
349 | ||
350 | Using ifquery to Validate and Debug Interface Configurations | |
351 | ============================================================ | |
352 | ||
353 | You use ``ifquery`` to print parsed ``interfaces`` file entries. | |
354 | ||
355 | To use ``ifquery`` to pretty print ``iface`` entries from the ``interfaces`` | |
356 | file, run:: | |
357 | ||
358 | cumulus@switch:~$ sudo ifquery bond0 | |
359 | auto bond0 | |
360 | iface bond0 | |
361 | address 14.0.0.9/30 | |
362 | address 2001:ded:beef:2::1/64 | |
363 | bond-slaves swp25 swp26 | |
364 | bond-mode 802.3ad | |
365 | bond-miimon 100 | |
594fb088 | 366 | bond-use-carrier yes |
2c8c4ce7 RP |
367 | bond-lacp-rate 1 |
368 | bond-min-links 1 | |
369 | bond-xmit-hash-policy layer3+4 | |
370 | ||
371 | .. Use ``ifquery -a`` to pretty print all ``iface`` entries from the | |
372 | ``interfaces`` file. | |
373 | ||
374 | Use ``ifquery --check`` to check the current running state of an interface within | |
375 | the ``interfaces`` file. It returns exit code ``0`` or ``1`` if the configuration | |
376 | does not match:: | |
377 | ||
378 | cumulus@switch:~$ sudo ifquery --check bond0 | |
379 | iface bond0 | |
380 | bond-mode 802.3ad (✓) | |
381 | bond-miimon 100 (✓) | |
594fb088 | 382 | bond-use-carrier yes (✓) |
2c8c4ce7 RP |
383 | bond-lacp-rate 1 (✓) |
384 | bond-min-links 1 (✓) | |
385 | bond-xmit-hash-policy layer3+4 (✓) | |
386 | bond-slaves swp25 swp26 (✓) | |
387 | address 14.0.0.9/30 (✓) | |
388 | address 2001:ded:beef:2::1/64 (✓) | |
389 | ||
390 | .. note:: ``ifquery --check`` is an experimental feature. | |
391 | ||
392 | .. Use ``ifquery --check -a`` to check all interfaces. | |
393 | ||
394 | Use ``ifquery --running`` to print the running state of interfaces in the | |
395 | ``interfaces`` file format:: | |
396 | ||
397 | cumulus@switch:~$ sudo ifquery --running bond0 | |
398 | auto bond0 | |
399 | iface bond0 | |
400 | bond-xmit-hash-policy layer3+4 | |
401 | bond-miimon 100 | |
402 | bond-lacp-rate 1 | |
403 | bond-min-links 1 | |
404 | bond-slaves swp25 swp26 | |
405 | bond-mode 802.3ad | |
406 | address 14.0.0.9/30 | |
407 | address 2001:ded:beef:2::1/64 | |
408 | ||
409 | ||
410 | ``ifquery --syntax-help`` provides help on all possible attributes supported in | |
411 | the ``interfaces`` file. For complete syntax on the ``interfaces`` file, see | |
412 | ``man interfaces`` and ``man ifupdown-addons-interfaces``. | |
413 | ||
414 | ``ifquery`` can dump information in JSON format:: | |
415 | ||
416 | cumulus@switch:~$ sudo ifquery --format=json bond0 | |
417 | { | |
418 | "auto": true, | |
419 | "config": { | |
594fb088 | 420 | "bond-use-carrier": "yes", |
2c0ad8b3 RP |
421 | "bond-xmit-hash-policy": "layer3+4", |
422 | "bond-miimon": "100", | |
594fb088 | 423 | "bond-lacp-rate": "1", |
2c8c4ce7 RP |
424 | "bond-min-links": "1", |
425 | "bond-slaves": "swp25 swp26", | |
426 | "bond-mode": "802.3ad", | |
427 | "address": [ | |
428 | "14.0.0.9/30", | |
429 | "2001:ded:beef:2::1/64" | |
430 | ] | |
431 | }, | |
432 | "addr_method": null, | |
433 | "name": "bond0", | |
434 | "addr_family": null | |
435 | } | |
436 | ||
437 | .. By default ``ifquery`` outputs information in the ``interfaces`` format. Some | |
438 | options do take the ``--format`` option and can output in JSON format. | |
439 | ||
440 | ||
441 | Useful Links | |
442 | ============ | |
443 | ||
444 | * `<http://wiki.debian.org/NetworkConfiguration>`_ | |
445 | * `<http://www.linuxfoundation.org/collaborate/workgroups/networking/bonding>`_ | |
446 | * `<http://www.linuxfoundation.org/collaborate/workgroups/networking/bridge>`_ | |
447 | * `<http://www.linuxfoundation.org/collaborate/workgroups/networking/vlan>`_ | |
448 | ||
449 | .. Caveats and Errata | |
450 | .. ================== | |
451 |