Debian Codegraph @

upstream/debian-unstable/man1/networkctl.1

raw
1 '\" t
2 .TH "NETWORKCTL" "1" "" "systemd 261~rc3" "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 \fBdhcp\-lease\fR \fIINTERFACE\fR [\fICODE\fR\fI[\fI:FORMAT\fR]\fR] \&...
245 .RS 4
246 Show the DHCP message of the acquired lease (i\&.e\&. the received DHCPACK message)\&. Takes an interface name and optional DHCP option codes\&. If no option code is specified, both the DHCP message header and all options are shown\&. If one or more option codes are specified, only the specified options are shown\&.
247 .sp
248 When called with the
249 \fB\-\-json=\fR
250 option, the entire DHCP message is shown in JSON format\&. In that case, any specified option codes are ignored\&.
251 .sp
252 By default, each option is displayed in a human\-readable format, depending on the option\&. For example, DNS server addresses are shown as a list of IP addresses (e\&.g\&.
253 "192\&.0\&.2\&.1"), and the lease time is shown as a human\-readable duration (e\&.g\&.
254 "8h")\&.
255 .sp
256 Each option code may optionally be followed by a formatter, separated by a colon (e\&.g\&.
257 "42:address")\&. This can be useful if the default formatting is not appropriate\&.
258 .sp
259 The following formatters are supported:
260 .PP
261 \fBauto\fR
262 .RS 4
263 Use the default formatting\&.
264 .RE
265 .PP
266 \fBhex\fR
267 .RS 4
268 Show the raw bytes in hexadecimal, separated by colons\&.
269 .RE
270 .PP
271 \fBflag\fR
272 .RS 4
273 Treat the option as having zero\-length data and display
274 "yes"\&.
275 .RE
276 .PP
277 \fBbool\fR
278 .RS 4
279 Treat the option as a 1\-byte boolean and display
280 "yes"
281 or
282 "no"\&.
283 .RE
284 .PP
285 \fBuint8\fR
286 .RS 4
287 Treat the option as a 1\-byte unsigned integer\&.
288 .RE
289 .PP
290 \fBuint16\fR
291 .RS 4
292 Treat the option as a 2\-byte unsigned integer\&.
293 .RE
294 .PP
295 \fBtime\fR
296 .RS 4
297 Treat the option as a 4\-byte time value in seconds and display it as a human\-readable duration\&.
298 .RE
299 .PP
300 \fBstring\fR
301 .RS 4
302 Treat the option as a string\&.
303 .RE
304 .PP
305 \fBaddress\fR
306 .RS 4
307 Treat the option as one or more IPv4 addresses and display them in human\-readable form\&.
308 .RE
309 .sp
310 Produces output similar to:
311 .sp
312 .if n \{\
313 .RS 4
314 .\}
315 .nf
316 $ networkctl dhcp\-lease eth0
317 Header:
318 KEY VALUE
319 Hardware Type: ETHER
320 Hardware Address: 41:42:43:31:32:33
321 Client Address: 192\&.0\&.2\&.123
322 Server Address: 192\&.0\&.2\&.1
323
324 Options:
325 CODE NAME DATA
326 1 subnet mask 255\&.255\&.255\&.0
327 3 router 192\&.0\&.2\&.1
328 6 domain name server 192\&.0\&.2\&.1
329 12 hostname test\-node
330 15 domain name lan
331 28 broadcast address 192\&.0\&.2\&.255
332 42 NTP server 192\&.0\&.2\&.11
333 192\&.0\&.2\&.12
334 51 lease time 1d
335 53 message type 5
336 54 server identifier 192\&.0\&.2\&.1
337 58 renewal time 11h 5min 38s
338 59 rebinding time 20h 5min 38s
339 119 domain search hoge\&.example\&.com
340 foo\&.example\&.com
341 .fi
342 .if n \{\
343 .RE
344 .\}
345 .sp
346 Added in version 261\&.
347 .RE
348 .PP
349 \fBlldp\fR [\fIPATTERN\&...\fR]
350 .RS 4
351 Show discovered LLDP (Link Layer Discovery Protocol) neighbors\&. If one or more
352 \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,
353 \fILLDP=\fR
354 must be turned on for the specific interface, see
355 \fBsystemd.network\fR(5)
356 for details\&.
357 .sp
358 Produces output similar to:
359 .sp
360 .if n \{\
361 .RS 4
362 .\}
363 .nf
364 LINK SYSTEM\-NAME SYSTEM\-DESCRIPTION CHASSIS\-ID PORT\-ID PORT\-DESCRIPTION CAPS
365 enp0s25 GS1900 \- 00:e0:4c:00:00:00 2 Port #2 \&.\&.b\&.\&.\&.\&.\&.\&.\&.\&.
366
367 Capability Flags:
368 o \- Other; p \- Repeater; b \- Bridge; w \- WLAN Access Point; r \- Router;
369 t \- Telephone; d \- DOCSIS cable device; a \- Station; c \- Customer VLAN;
370 s \- Service VLAN, m \- Two\-port MAC Relay (TPMR)
371
372 1 neighbor(s) listed\&.
373 .fi
374 .if n \{\
375 .RE
376 .\}
377 .sp
378 Added in version 219\&.
379 .RE
380 .PP
381 \fBlabel\fR
382 .RS 4
383 Show numerical address labels that can be used for address selection\&. This is the same information that
384 \fBip-addrlabel\fR(8)
385 shows\&. See
386 \m[blue]\fBRFC 3484\fR\m[]\&\s-2\u[1]\d\s+2
387 for a discussion of address labels\&.
388 .sp
389 Produces output similar to:
390 .sp
391 .if n \{\
392 .RS 4
393 .\}
394 .nf
395 Prefix/Prefixlen Label
396 ::/0 1
397 fc00::/7 5
398 fec0::/10 11
399 2002::/16 2
400 3ffe::/16 12
401 2001:10::/28 7
402 2001::/32 6
403 ::ffff:0\&.0\&.0\&.0/96 4
404 ::/96 3
405 ::1/128 0
406 .fi
407 .if n \{\
408 .RE
409 .\}
410 .sp
411 Added in version 234\&.
412 .RE
413 .PP
414 \fBdelete\fR \fIDEVICE\&...\fR
415 .RS 4
416 Deletes virtual netdevs\&. Takes interface name or index number\&.
417 .sp
418 Added in version 243\&.
419 .RE
420 .PP
421 \fBup\fR \fIDEVICE\&...\fR
422 .RS 4
423 Bring devices up\&. Takes interface name or index number\&.
424 .sp
425 Added in version 246\&.
426 .RE
427 .PP
428 \fBdown\fR \fIDEVICE\&...\fR
429 .RS 4
430 Bring devices down\&. Takes interface name or index number\&.
431 .sp
432 Added in version 246\&.
433 .RE
434 .PP
435 \fBrenew\fR \fIDEVICE\&...\fR
436 .RS 4
437 Renew dynamic configurations e\&.g\&. addresses received from DHCP server\&. Takes interface name or index number\&.
438 .sp
439 Added in version 244\&.
440 .RE
441 .PP
442 \fBforcerenew\fR \fIDEVICE\&...\fR
443 .RS 4
444 Send a FORCERENEW message to all connected clients, triggering DHCP reconfiguration\&. Takes interface name or index number\&.
445 .sp
446 Added in version 246\&.
447 .RE
448 .PP
449 \fBreconfigure\fR \fIDEVICE\&...\fR
450 .RS 4
451 Reconfigure network interfaces\&. Takes interface name or index number\&. Note that this does not reload
452 \&.netdev
453 or
454 \&.network
455 corresponding to the specified interface\&. So, if you edit config files, it is necessary to call
456 \fBnetworkctl reload\fR
457 first to apply new settings\&.
458 .sp
459 Added in version 244\&.
460 .RE
461 .PP
462 \fBreload\fR
463 .RS 4
464 Reload
465 \&.netdev
466 and
467 \&.network
468 files\&.
469 .sp
470 If a new or modified
471 \&.netdev
472 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]
473 \fIId=\fR
474 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
475 \&.netdev
476 file is removed,
477 \fBsystemd-networkd\fR(8)
478 does not remove the existing netdev corresponding to the file\&.
479 .sp
480 If a new, modified, or removed
481 \&.network
482 file is found, then all interfaces that matched the file are reconfigured\&.
483 .sp
484 Added in version 244\&.
485 .RE
486 .PP
487 \fBedit\fR \fIFILE\fR|\fI@DEVICE\fR\&...
488 .RS 4
489 Edit network configuration files, which include
490 \&.network,
491 \&.netdev, and
492 \&.link
493 files\&. If no network config file matching the given name is found, a new one will be created under
494 /etc/
495 or
496 /run/, depending on whether
497 \fB\-\-runtime\fR
498 is specified\&. Specially, if the name is prefixed by
499 "@", 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
500 ":network"
501 (default),
502 ":link", or
503 ":netdev", in order to choose the type of network config to operate on\&.
504 .sp
505 If
506 \fB\-\-drop\-in=\fR
507 is specified, edit the drop\-in file instead of the main configuration file\&. Unless
508 \fB\-\-no\-reload\fR
509 is specified,
510 \fBsystemd-networkd\fR(8)
511 will be reloaded after the edit of the
512 \&.network
513 or
514 \&.netdev
515 files finishes\&. The same applies for
516 \&.link
517 files and
518 \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
519 \fBsystemd.link\fR(5)
520 for more information\&.
521 .sp
522 If
523 \fB\-\-stdin\fR
524 is specified, the new content will be read from standard input\&. In this mode, the old content of the file is discarded\&.
525 .sp
526 Added in version 254\&.
527 .RE
528 .PP
529 \fBcat\fR [\fIFILE\fR|\fI@DEVICE\fR\&...]
530 .RS 4
531 Show network configuration files\&. This command honors the
532 "@"
533 prefix in a similar way as
534 \fBedit\fR, with support for an additional suffix
535 ":all"
536 for showing all types of configuration files associated with the interface at once\&. When no argument is specified,
537 \fBnetworkd.conf\fR(5)
538 and its drop\-in files will be shown\&.
539 .sp
540 Added in version 254\&.
541 .RE
542 .PP
543 \fBmask\fR \fIFILE\fR\&...
544 .RS 4
545 Mask network configuration files, which include
546 \&.network,
547 \&.netdev, and
548 \&.link
549 files\&. A symlink of the given name will be created under
550 /etc/
551 or
552 /run/, depending on whether
553 \fB\-\-runtime\fR
554 is specified, that points to
555 /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\&.
556 \fB\-\-runtime\fR
557 is used while an existing config resides in
558 /etc/), the operation is aborted\&.
559 .sp
560 This command honors
561 \fB\-\-no\-reload\fR
562 in the same way as
563 \fBedit\fR\&.
564 .sp
565 Added in version 256\&.
566 .RE
567 .PP
568 \fBunmask\fR \fIFILE\fR\&...
569 .RS 4
570 Unmask network configuration files, i\&.e\&. reverting the effect of
571 \fBmask\fR\&. Note that this command operates regardless of the scope of the directory, i\&.e\&.
572 \fB\-\-runtime\fR
573 is of no effect\&.
574 .sp
575 This command honors
576 \fB\-\-no\-reload\fR
577 in the same way as
578 \fBedit\fR
579 and
580 \fBmask\fR\&.
581 .sp
582 Added in version 256\&.
583 .RE
584 .PP
585 \fBpersistent\-storage\fR \fIBOOL\fR
586 .RS 4
587 Notify
588 \fBsystemd-networkd.service\fR(8)
589 that the persistent storage for the service is ready\&. This is called by
590 systemd\-networkd\-persistent\-storage\&.service\&. Usually, this command should not be called manually by users or administrators\&.
591 .sp
592 Added in version 256\&.
593 .RE
594 .SH "OPTIONS"
595 .PP
596 The following options are understood:
597 .PP
598 \fB\-a\fR \fB\-\-all\fR
599 .RS 4
600 Show all links with
601 \fBstatus\fR\&.
602 .sp
603 Added in version 219\&.
604 .RE
605 .PP
606 \fB\-s\fR \fB\-\-stats\fR
607 .RS 4
608 Show link statistics with
609 \fBstatus\fR\&.
610 .sp
611 Added in version 243\&.
612 .RE
613 .PP
614 \fB\-l\fR, \fB\-\-full\fR
615 .RS 4
616 Do not ellipsize the output\&.
617 .sp
618 Added in version 245\&.
619 .RE
620 .PP
621 \fB\-n\fR, \fB\-\-lines=\fR
622 .RS 4
623 When used with
624 \fBstatus\fR, controls the number of journal lines to show, counting from the most recent ones\&. Takes a positive integer argument\&. Defaults to 10\&.
625 .sp
626 Added in version 245\&.
627 .RE
628 .PP
629 \fB\-\-drop\-in=\fR\fB\fINAME\fR\fR
630 .RS 4
631 When used with
632 \fBedit\fR, edit the drop\-in file
633 \fINAME\fR
634 instead of the main configuration file\&.
635 .sp
636 Added in version 254\&.
637 .RE
638 .PP
639 \fB\-\-no\-reload\fR
640 .RS 4
641 When used with
642 \fBedit\fR,
643 \fBmask\fR, or
644 \fBunmask\fR,
645 \fBsystemd-networkd.service\fR(8)
646 or
647 \fBsystemd-udevd.service\fR(8)
648 will not be reloaded after the operation finishes\&.
649 .sp
650 Added in version 254\&.
651 .RE
652 .PP
653 \fB\-\-runtime\fR
654 .RS 4
655 When used with
656 \fBedit\fR
657 or
658 \fBmask\fR, operate on the file under
659 /run/
660 instead of
661 /etc/\&.
662 .sp
663 Added in version 256\&.
664 .RE
665 .PP
666 \fB\-\-stdin\fR
667 .RS 4
668 When used with
669 \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\&.
670 .sp
671 Multiple drop\-ins may be "edited" in this mode with
672 \fB\-\-drop\-in=\fR, and the same contents will be written to all of them\&. Otherwise, exactly one main configuration file is expected\&.
673 .sp
674 Added in version 257\&.
675 .RE
676 .PP
677 \fB\-\-no\-ask\-password\fR
678 .RS 4
679 Do not query the user for authentication for privileged operations\&.
680 .RE
681 .PP
682 \fB\-\-json=\fR\fB\fIMODE\fR\fR
683 .RS 4
684 Shows output formatted as JSON\&. Expects one of
685 "short"
686 (for the shortest possible output without any redundant whitespace or line breaks),
687 "pretty"
688 (for a pretty version of the same, with indentation and line breaks) or
689 "off"
690 (to turn off JSON output, the default)\&.
691 .RE
692 .PP
693 \fB\-h\fR, \fB\-\-help\fR
694 .RS 4
695 Print a short help text and exit\&.
696 .RE
697 .PP
698 \fB\-\-version\fR
699 .RS 4
700 Print a short version string and exit\&.
701 .RE
702 .PP
703 \fB\-\-no\-legend\fR
704 .RS 4
705 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
706 .RE
707 .PP
708 \fB\-\-no\-pager\fR
709 .RS 4
710 Do not pipe output into a pager\&.
711 .RE
712 .SH "EXIT STATUS"
713 .PP
714 On success, 0 is returned, a non\-zero failure code otherwise\&.
715 .SH "SEE ALSO"
716 .PP
717 \fBsystemd-networkd.service\fR(8), \fBsystemd.network\fR(5), \fBsystemd.netdev\fR(5), \fBip\fR(8)
718 .SH "NOTES"
719 .IP " 1." 4
720 RFC 3484
721 .RS 4
722 \%https://tools.ietf.org/html/rfc3484
723 .RE