Debian Codegraph @

upstream/debian-trixie/man1/networkctl.1

raw
1 '\" t
2 .TH "NETWORKCTL" "1" "" "systemd 257.13" "networkctl"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 networkctl \- Query or modify the status of network links
24 .SH "SYNOPSIS"
25 .HP \w'\fBnetworkctl\fR\ 'u
26 \fBnetworkctl\fR [OPTIONS...] COMMAND [LINK...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBnetworkctl\fR
30 may be used to query or modify the state of the network links as seen by
31 \fBsystemd\-networkd\fR\&. Please refer to
32 \fBsystemd-networkd.service\fR(8)
33 for an introduction to the basic concepts, functionality, and configuration syntax\&.
34 .SH "COMMANDS"
35 .PP
36 The following commands are understood:
37 .PP
38 \fBlist\fR [\fIPATTERN\&...\fR]
39 .RS 4
40 Show a list of existing links and their status\&. If one or more
41 \fIPATTERN\fRs are specified, only links matching one of them are shown\&. If no further arguments are specified shows all links, otherwise just the specified links\&. Produces output similar to:
42 .sp
43 .if n \{\
44 .RS 4
45 .\}
46 .nf
47 IDX LINK TYPE OPERATIONAL SETUP
48 1 lo loopback carrier unmanaged
49 2 eth0 ether routable configured
50 3 virbr0 ether no\-carrier unmanaged
51 4 virbr0\-nic ether off unmanaged
52
53 4 links listed\&.
54 .fi
55 .if n \{\
56 .RE
57 .\}
58 .sp
59 The operational status is one of the following:
60 .PP
61 missing
62 .RS 4
63 The device is missing\&.
64 .sp
65 Added in version 245\&.
66 .RE
67 .PP
68 off
69 .RS 4
70 The device is powered down\&.
71 .sp
72 Added in version 240\&.
73 .RE
74 .PP
75 no\-carrier
76 .RS 4
77 The device is powered up, but does not yet have a carrier\&.
78 .sp
79 Added in version 240\&.
80 .RE
81 .PP
82 dormant
83 .RS 4
84 The device has a carrier, but is not yet ready for normal traffic\&.
85 .sp
86 Added in version 240\&.
87 .RE
88 .PP
89 degraded\-carrier
90 .RS 4
91 One of the bonding or bridge slave network interfaces is in off, no\-carrier, or dormant state, and the master interface has no address\&.
92 .sp
93 Added in version 242\&.
94 .RE
95 .PP
96 carrier
97 .RS 4
98 The link has carrier, or for bond or bridge master, all bonding or bridge slave network interfaces are enslaved to the master\&.
99 .sp
100 Added in version 240\&.
101 .RE
102 .PP
103 degraded
104 .RS 4
105 The link has carrier and addresses valid on the local link configured\&. For bond or bridge master this means that not all slave network interfaces have carrier but at least one does\&.
106 .sp
107 Added in version 240\&.
108 .RE
109 .PP
110 enslaved
111 .RS 4
112 The link has carrier and is enslaved to bond or bridge master network interface\&.
113 .sp
114 Added in version 242\&.
115 .RE
116 .PP
117 routable
118 .RS 4
119 The link has carrier and routable address configured\&. For bond or bridge master it is not necessary for all slave network interfaces to have carrier, but at least one must\&.
120 .sp
121 Added in version 240\&.
122 .RE
123 .sp
124 The setup status is one of the following:
125 .PP
126 pending
127 .RS 4
128 \fBsystemd-udevd\fR(8)
129 is still processing the link, we do not yet know if we will manage it\&.
130 .sp
131 Added in version 240\&.
132 .RE
133 .PP
134 initialized
135 .RS 4
136 \fBsystemd-udevd\fR(8)
137 has processed the link, but we do not yet know if we will manage it\&.
138 .sp
139 Added in version 251\&.
140 .RE
141 .PP
142 configuring
143 .RS 4
144 Configuration for the link is being retrieved or the link is being configured\&.
145 .sp
146 Added in version 240\&.
147 .RE
148 .PP
149 configured
150 .RS 4
151 Link has been configured successfully\&.
152 .sp
153 Added in version 240\&.
154 .RE
155 .PP
156 unmanaged
157 .RS 4
158 \fBsystemd\-networkd\fR
159 is not handling the link\&.
160 .sp
161 Added in version 240\&.
162 .RE
163 .PP
164 failed
165 .RS 4
166 \fBsystemd\-networkd\fR
167 failed to configure the link\&.
168 .sp
169 Added in version 240\&.
170 .RE
171 .PP
172 linger
173 .RS 4
174 The link is gone, but has not yet been dropped by
175 \fBsystemd\-networkd\fR\&.
176 .sp
177 Added in version 240\&.
178 .RE
179 .sp
180 Added in version 219\&.
181 .RE
182 .PP
183 \fBstatus\fR [\fIPATTERN\&...\fR]
184 .RS 4
185 Show information about the specified links: type, state, kernel module driver, hardware and IP address, configured DNS servers, etc\&. If one or more
186 \fIPATTERN\fRs are specified, only links matching one of them are shown\&.
187 .sp
188 When no links are specified, an overall network status is shown\&. Also see the option
189 \fB\-\-all\fR\&.
190 .sp
191 Produces output similar to:
192 .sp
193 .if n \{\
194 .RS 4
195 .\}
196 .nf
197 ● State: routable
198 Online state: online
199 Address: 10\&.193\&.76\&.5 on eth0
200 192\&.168\&.122\&.1 on virbr0
201 169\&.254\&.190\&.105 on eth0
202 fe80::5054:aa:bbbb:cccc on eth0
203 Gateway: 10\&.193\&.11\&.1 (CISCO SYSTEMS, INC\&.) on eth0
204 DNS: 8\&.8\&.8\&.8
205 8\&.8\&.4\&.4
206 .fi
207 .if n \{\
208 .RE
209 .\}
210 .sp
211 In the overall network status, the online state depends on the individual online state of all required links\&. Managed links are required for online by default\&. In this case, the online state is one of the following:
212 .PP
213 unknown
214 .RS 4
215 All links have unknown online status (i\&.e\&. there are no required links)\&.
216 .sp
217 Added in version 249\&.
218 .RE
219 .PP
220 offline
221 .RS 4
222 All required links are offline\&.
223 .sp
224 Added in version 249\&.
225 .RE
226 .PP
227 partial
228 .RS 4
229 Some, but not all, required links are online\&.
230 .sp
231 Added in version 249\&.
232 .RE
233 .PP
234 online
235 .RS 4
236 All required links are online\&.
237 .sp
238 Added in version 249\&.
239 .RE
240 .sp
241 Added in version 219\&.
242 .RE
243 .PP
244 \fBlldp\fR [\fIPATTERN\&...\fR]
245 .RS 4
246 Show discovered LLDP (Link Layer Discovery Protocol) neighbors\&. If one or more
247 \fIPATTERN\fRs are specified only neighbors on those interfaces are shown\&. Otherwise, shows discovered neighbors on all interfaces\&. Note that for this feature to work,
248 \fILLDP=\fR
249 must be turned on for the specific interface, see
250 \fBsystemd.network\fR(5)
251 for details\&.
252 .sp
253 Produces output similar to:
254 .sp
255 .if n \{\
256 .RS 4
257 .\}
258 .nf
259 LINK SYSTEM\-NAME SYSTEM\-DESCRIPTION CHASSIS\-ID PORT\-ID PORT\-DESCRIPTION CAPS
260 enp0s25 GS1900 \- 00:e0:4c:00:00:00 2 Port #2 \&.\&.b\&.\&.\&.\&.\&.\&.\&.\&.
261
262 Capability Flags:
263 o \- Other; p \- Repeater; b \- Bridge; w \- WLAN Access Point; r \- Router;
264 t \- Telephone; d \- DOCSIS cable device; a \- Station; c \- Customer VLAN;
265 s \- Service VLAN, m \- Two\-port MAC Relay (TPMR)
266
267 1 neighbor(s) listed\&.
268 .fi
269 .if n \{\
270 .RE
271 .\}
272 .sp
273 Added in version 219\&.
274 .RE
275 .PP
276 \fBlabel\fR
277 .RS 4
278 Show numerical address labels that can be used for address selection\&. This is the same information that
279 \fBip-addrlabel\fR(8)
280 shows\&. See
281 \m[blue]\fBRFC 3484\fR\m[]\&\s-2\u[1]\d\s+2
282 for a discussion of address labels\&.
283 .sp
284 Produces output similar to:
285 .sp
286 .if n \{\
287 .RS 4
288 .\}
289 .nf
290 Prefix/Prefixlen Label
291 ::/0 1
292 fc00::/7 5
293 fec0::/10 11
294 2002::/16 2
295 3ffe::/16 12
296 2001:10::/28 7
297 2001::/32 6
298 ::ffff:0\&.0\&.0\&.0/96 4
299 ::/96 3
300 ::1/128 0
301 .fi
302 .if n \{\
303 .RE
304 .\}
305 .sp
306 Added in version 234\&.
307 .RE
308 .PP
309 \fBdelete\fR \fIDEVICE\&...\fR
310 .RS 4
311 Deletes virtual netdevs\&. Takes interface name or index number\&.
312 .sp
313 Added in version 243\&.
314 .RE
315 .PP
316 \fBup\fR \fIDEVICE\&...\fR
317 .RS 4
318 Bring devices up\&. Takes interface name or index number\&.
319 .sp
320 Added in version 246\&.
321 .RE
322 .PP
323 \fBdown\fR \fIDEVICE\&...\fR
324 .RS 4
325 Bring devices down\&. Takes interface name or index number\&.
326 .sp
327 Added in version 246\&.
328 .RE
329 .PP
330 \fBrenew\fR \fIDEVICE\&...\fR
331 .RS 4
332 Renew dynamic configurations e\&.g\&. addresses received from DHCP server\&. Takes interface name or index number\&.
333 .sp
334 Added in version 244\&.
335 .RE
336 .PP
337 \fBforcerenew\fR \fIDEVICE\&...\fR
338 .RS 4
339 Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration\&. Takes interface name or index number\&.
340 .sp
341 Added in version 246\&.
342 .RE
343 .PP
344 \fBreconfigure\fR \fIDEVICE\&...\fR
345 .RS 4
346 Reconfigure network interfaces\&. Takes interface name or index number\&. Note that this does not reload
347 \&.netdev
348 or
349 \&.network
350 corresponding to the specified interface\&. So, if you edit config files, it is necessary to call
351 \fBnetworkctl reload\fR
352 first to apply new settings\&.
353 .sp
354 Added in version 244\&.
355 .RE
356 .PP
357 \fBreload\fR
358 .RS 4
359 Reload
360 \&.netdev
361 and
362 \&.network
363 files\&.
364 .sp
365 If a new or modified
366 \&.netdev
367 file is found, then the corresponding netdev is created or updated, respectively\&. Note, if the corresponding interface already exists, then some of new settings may not be applied\&. E\&.g\&., VLAN ID cannot be changed after the interface was created, so changing [VLAN]
368 \fIId=\fR
369 will not take effect if the matching VLAN interface already exists\&. To apply such settings, the interfaces need to be removed manually before reload\&. Also note that even if a
370 \&.netdev
371 file is removed,
372 \fBsystemd-networkd\fR(8)
373 does not remove the existing netdev corresponding to the file\&.
374 .sp
375 If a new, modified, or removed
376 \&.network
377 file is found, then all interfaces that matched the file are reconfigured\&.
378 .sp
379 Added in version 244\&.
380 .RE
381 .PP
382 \fBedit\fR \fIFILE\fR|\fI@DEVICE\fR\&...
383 .RS 4
384 Edit network configuration files, which include
385 \&.network,
386 \&.netdev, and
387 \&.link
388 files\&. If no network config file matching the given name is found, a new one will be created under
389 /etc/
390 or
391 /run/, depending on whether
392 \fB\-\-runtime\fR
393 is specified\&. Specially, if the name is prefixed by
394 "@", it will be treated as a network interface, and editing will be performed on the network config files associated with it\&. Additionally, the interface name can be suffixed with
395 ":network"
396 (default),
397 ":link", or
398 ":netdev", in order to choose the type of network config to operate on\&.
399 .sp
400 If
401 \fB\-\-drop\-in=\fR
402 is specified, edit the drop\-in file instead of the main configuration file\&. Unless
403 \fB\-\-no\-reload\fR
404 is specified,
405 \fBsystemd-networkd\fR(8)
406 will be reloaded after the edit of the
407 \&.network
408 or
409 \&.netdev
410 files finishes\&. The same applies for
411 \&.link
412 files and
413 \fBsystemd-udevd\fR(8)\&. Note that the changed link settings are not automatically applied after reloading\&. To achieve that, trigger uevents for the corresponding interface\&. Refer to
414 \fBsystemd.link\fR(5)
415 for more information\&.
416 .sp
417 If
418 \fB\-\-stdin\fR
419 is specified, the new content will be read from standard input\&. In this mode, the old content of the file is discarded\&.
420 .sp
421 Added in version 254\&.
422 .RE
423 .PP
424 \fBcat\fR [\fIFILE\fR|\fI@DEVICE\fR\&...]
425 .RS 4
426 Show network configuration files\&. This command honors the
427 "@"
428 prefix in a similar way as
429 \fBedit\fR, with support for an additional suffix
430 ":all"
431 for showing all types of configuration files associated with the interface at once\&. When no argument is specified,
432 \fBnetworkd.conf\fR(5)
433 and its drop\-in files will be shown\&.
434 .sp
435 Added in version 254\&.
436 .RE
437 .PP
438 \fBmask\fR \fIFILE\fR\&...
439 .RS 4
440 Mask network configuration files, which include
441 \&.network,
442 \&.netdev, and
443 \&.link
444 files\&. A symlink of the given name will be created under
445 /etc/
446 or
447 /run/, depending on whether
448 \fB\-\-runtime\fR
449 is specified, that points to
450 /dev/null\&. If a non\-empty config file with the specified name exists under the target directory or a directory with higher priority (e\&.g\&.
451 \fB\-\-runtime\fR
452 is used while an existing config resides in
453 /etc/), the operation is aborted\&.
454 .sp
455 This command honors
456 \fB\-\-no\-reload\fR
457 in the same way as
458 \fBedit\fR\&.
459 .sp
460 Added in version 256\&.
461 .RE
462 .PP
463 \fBunmask\fR \fIFILE\fR\&...
464 .RS 4
465 Unmask network configuration files, i\&.e\&. reverting the effect of
466 \fBmask\fR\&. Note that this command operates regardless of the scope of the directory, i\&.e\&.
467 \fB\-\-runtime\fR
468 is of no effect\&.
469 .sp
470 This command honors
471 \fB\-\-no\-reload\fR
472 in the same way as
473 \fBedit\fR
474 and
475 \fBmask\fR\&.
476 .sp
477 Added in version 256\&.
478 .RE
479 .PP
480 \fBpersistent\-storage\fR \fIBOOL\fR
481 .RS 4
482 Notify
483 \fBsystemd-networkd.service\fR(8)
484 that the persistent storage for the service is ready\&. This is called by
485 systemd\-networkd\-persistent\-storage\&.service\&. Usually, this command should not be called manually by users or administrators\&.
486 .sp
487 Added in version 256\&.
488 .RE
489 .SH "OPTIONS"
490 .PP
491 The following options are understood:
492 .PP
493 \fB\-a\fR \fB\-\-all\fR
494 .RS 4
495 Show all links with
496 \fBstatus\fR\&.
497 .sp
498 Added in version 219\&.
499 .RE
500 .PP
501 \fB\-s\fR \fB\-\-stats\fR
502 .RS 4
503 Show link statistics with
504 \fBstatus\fR\&.
505 .sp
506 Added in version 243\&.
507 .RE
508 .PP
509 \fB\-l\fR, \fB\-\-full\fR
510 .RS 4
511 Do not ellipsize the output\&.
512 .sp
513 Added in version 245\&.
514 .RE
515 .PP
516 \fB\-n\fR, \fB\-\-lines=\fR
517 .RS 4
518 When used with
519 \fBstatus\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument\&. Defaults to 10\&.
520 .sp
521 Added in version 245\&.
522 .RE
523 .PP
524 \fB\-\-drop\-in=\fR\fB\fINAME\fR\fR
525 .RS 4
526 When used with
527 \fBedit\fR, edit the drop\-in file
528 \fINAME\fR
529 instead of the main configuration file\&.
530 .sp
531 Added in version 254\&.
532 .RE
533 .PP
534 \fB\-\-no\-reload\fR
535 .RS 4
536 When used with
537 \fBedit\fR,
538 \fBmask\fR, or
539 \fBunmask\fR,
540 \fBsystemd-networkd.service\fR(8)
541 or
542 \fBsystemd-udevd.service\fR(8)
543 will not be reloaded after the operation finishes\&.
544 .sp
545 Added in version 254\&.
546 .RE
547 .PP
548 \fB\-\-runtime\fR
549 .RS 4
550 When used with
551 \fBedit\fR
552 or
553 \fBmask\fR, operate on the file under
554 /run/
555 instead of
556 /etc/\&.
557 .sp
558 Added in version 256\&.
559 .RE
560 .PP
561 \fB\-\-stdin\fR
562 .RS 4
563 When used with
564 \fBedit\fR, the contents of the file will be read from standard input and the editor will not be launched\&. In this mode, the old contents of the file are automatically replaced\&. This is useful to "edit" configuration from scripts, especially so that drop\-in directories are created and populated in one go\&.
565 .sp
566 Multiple drop\-ins may be "edited" in this mode with
567 \fB\-\-drop\-in=\fR, and the same contents will be written to all of them\&. Otherwise, exactly one main configuration file is expected\&.
568 .sp
569 Added in version 257\&.
570 .RE
571 .PP
572 \fB\-\-no\-ask\-password\fR
573 .RS 4
574 Do not query the user for authentication for privileged operations\&.
575 .RE
576 .PP
577 \fB\-\-json=\fR\fB\fIMODE\fR\fR
578 .RS 4
579 Shows output formatted as JSON\&. Expects one of
580 "short"
581 (for the shortest possible output without any redundant whitespace or line breaks),
582 "pretty"
583 (for a pretty version of the same, with indentation and line breaks) or
584 "off"
585 (to turn off JSON output, the default)\&.
586 .RE
587 .PP
588 \fB\-h\fR, \fB\-\-help\fR
589 .RS 4
590 Print a short help text and exit\&.
591 .RE
592 .PP
593 \fB\-\-version\fR
594 .RS 4
595 Print a short version string and exit\&.
596 .RE
597 .PP
598 \fB\-\-no\-legend\fR
599 .RS 4
600 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
601 .RE
602 .PP
603 \fB\-\-no\-pager\fR
604 .RS 4
605 Do not pipe output into a pager\&.
606 .RE
607 .SH "EXIT STATUS"
608 .PP
609 On success, 0 is returned, a non\-zero failure code otherwise\&.
610 .SH "SEE ALSO"
611 .PP
612 \fBsystemd-networkd.service\fR(8), \fBsystemd.network\fR(5), \fBsystemd.netdev\fR(5), \fBip\fR(8)
613 .SH "NOTES"
614 .IP " 1." 4
615 RFC 3484
616 .RS 4
617 \%https://tools.ietf.org/html/rfc3484
618 .RE