Package: ifupdown Version: 0.8.41 Severity: minor Tags: patch Dear Maintainer,
here are some notes and fixes for the manual. Input file is ifup.8 Output from "mandoc -T lint ifup.8": mandoc: ifup.8:9:9: STYLE: whitespace at end of input line mandoc: ifup.8:18:9: STYLE: whitespace at end of input line mandoc: ifup.8:21:9: STYLE: whitespace at end of input line mandoc: ifup.8:91:8: STYLE: whitespace at end of input line mandoc: ifup.8:95:32: STYLE: whitespace at end of input line mandoc: ifup.8:107:82: STYLE: input text line longer than 80 bytes: Exclude interfaces f... mandoc: ifup.8:128:86: STYLE: input text line longer than 80 bytes: Disable special hand... mandoc: ifup.8:129:85: STYLE: input text line longer than 80 bytes: (\fIlo\fR on Linux) ... mandoc: ifup.8:130:85: STYLE: input text line longer than 80 bytes: on \fBifup -a\fR aut... mandoc: ifup.8:131:84: STYLE: input text line longer than 80 bytes: the interface is con... mandoc: ifup.8:132:83: STYLE: input text line longer than 80 bytes: defined as loopback,... mandoc: ifup.8:146:82: STYLE: input text line longer than 80 bytes: For \fBifquery\fR, d... mandoc: ifup.8:147:85: STYLE: input text line longer than 80 bytes: lists all interfaces... mandoc: ifup.8:148:81: STYLE: input text line longer than 80 bytes: exits with a status ... mandoc: ifup.8:149:88: STYLE: input text line longer than 80 bytes: display state of the... mandoc: ifup.8:156:3: STYLE: whitespace at end of input line mandoc: ifup.8:218:124: STYLE: input text line longer than 80 bytes: Ifupdown uses per-in... mandoc: ifup.8:225:120: STYLE: input text line longer than 80 bytes: the exit status will... mandoc: ifup.8:228:92: STYLE: input text line longer than 80 bytes: on an interface that... mandoc: ifup.8:233:119: STYLE: input text line longer than 80 bytes: will normally return... mandoc: ifup.8:235:84: STYLE: input text line longer than 80 bytes: will also return wit... mandoc: ifup.8:275:56: STYLE: whitespace at end of input line ####### Remove space characters at the end of lines. Use "git apply ... --whitespace=fix" to fix extra space issues, or use global configuration "core.whitespace". 9:.B ifup 18:.B ifup 21:.B ifup 91:line in 95:Read interface definitions from 156:in 275:that appear as a result of hardware being installed and ##### Mark a full stop (.) with "\&", if it does not mean an end of a sentence. This is a preventive action, the paragraph could be reshaped, e.g., after changes. When typing, one does not always notice when the line wraps after the period. There are too many examples of input lines in manual pages, that end with an abbreviation point. This marking is robust, and independent of the position on the line. It corresponds to "\ " in TeX, and to "@:" in Texinfo. 60:.IR /etc/network/interfaces ". " ##### Change -- in x--y to \(em (em-dash), or, if an option, to \-\- 175:.B ifquery -l --allow=hotplug 234:.B ifquery --state ##### Use the correct macro for the font change of a single argument or split the argument into two. 145:.BR \-\-state 186:.BR ifquery 191:.BR ip 203:.BR ifdown ##### Change a HYPHEN-MINUS (code 0x55, 2D) to a minus (\-), if in front of a name for an option. 130:on \fBifup -a\fR automatically. In the case the loopback device is redefined by user, 153:.B ifup -a 169:.B ifdown -a 172:.B ifquery -l 175:.B ifquery -l --allow=hotplug ##### Wrong distance between sentences. Separate the sentences and subordinate clauses; each begins on a new line. See man-pages(7) ("Conventions for source file layout") and "info groff" ("Input Conventions"). The best procedure is to always start a new sentence on a new line, at least, if you are typing on a computer. Remember coding: Only one command ("sentence") on each (logical) line. E-mail: Easier to quote exactly the relevant lines. Generally: Easier to edit the sentence. Patches: Less unaffected text. The amount of space between sentences in the output can then be controlled with the ".ss" request. 74:currently listed in the state file. Only interfaces defined 108:\fIPATTERN\fR uses a usual shell glob syntax. If shell wildcards are not used, it 109:must match the exact interface name. This option may be specified multiple times 128:Disable special handling of the loopback interface. By default, the loopback interface 130:on \fBifup -a\fR automatically. In the case the loopback device is redefined by user, 131:the interface is configured just once anyway. If, however, another interface is also 132:defined as loopback, it's configured as usual. Specifying this option disables this 146:For \fBifquery\fR, dump the state of the interfaces. When no interfaces specified, 148:exits with a status code indicating success. If one or more interfaces specified, 150:given as arguments are up. Otherwise, 0 is returned. 180:configuration. Each key-value pair is printed out on individual 198:is still running. In that case, ##### Add a thin space (\|) around "|" to increase readability 13:[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] 16:\fB\-a\fR|\fIIFACE\fR... 19:\fB\-h\fR|\fB\-\-help\fR 22:\fB\-V\fR|\fB\-\-version\fR 28:[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] 31:\fB\-a\fR|\fIIFACE\fR... 36:[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] 42:\fB\-l\fR|\fB\-\-list\fR 45:[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] 48:[\fB\-a\fR|\fIIFACE\fR...] 54:[\fB\-a\fR|\fIIFACE\fR...] ##### Split lines longer than 100 characters into two or more lines. Appropriate break points are the end of a sentence and a subordinate clause; after punctuation marks. ifup.8: line 218 length 124 Ifupdown uses per-interface locking to ensure that concurrent ifup and ifdown calls to the same interface are run in serial. ifup.8: line 225 length 120 the exit status will be 0 if the given interface(s) have all been (de)configured successfully, 1 if there was any error. ifup.8: line 233 length 119 will normally return with exit status 0 if an interface with a matching iface stanza, 1 if there is no matching stanza. ##### Split a punctuation from a single argument, if a two-font macro is meant 224:.B ifdown\fR, ##### --- ifup.8 2023-06-18 23:16:08.000000000 +0000 +++ ifup.8.new 2023-06-19 01:29:10.000000000 +0000 @@ -6,59 +6,61 @@ ifdown \- take a network interface down .PP ifquery \- parse interface configuration .SH SYNOPSIS -.B ifup +.B ifup [\fB\-nv\fR] [\fB\-\-no\-act\fR] [\fB\-\-verbose\fR] -[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] +[\fB\-i\fR \fIFILE\fR\||\|\fB\-\-interfaces=\fR\fIFILE\fR\/] [\fB\-\-state-dir=\fR\fIDIR\fR] [\fB\-\-allow\fR \fICLASS\fR] -\fB\-a\fR|\fIIFACE\fR... +\fB\-a\fR\||\|\fIIFACE\fR... .br -.B ifup -\fB\-h\fR|\fB\-\-help\fR +.B ifup +\fB\-h\fR\||\|\fB\-\-help\fR .br -.B ifup -\fB\-V\fR|\fB\-\-version\fR +.B ifup +\fB\-V\fR\||\|\fB\-\-version\fR .PP .B ifdown [\fB\-nv\fR] [\fB\-\-no\-act\fR] [\fB\-\-verbose\fR] -[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] +[\fB\-i\fR \fIFILE\fR\||\|\fB\-\-interfaces=\fR\fIFILE\fR\/] [\fB\-\-state-dir=\fR\fIDIR\fR] [\fB\-\-allow\fR \fICLASS\fR] -\fB\-a\fR|\fIIFACE\fR... +\fB\-a\fR\||\|\fIIFACE\fR... .PP .B ifquery [\fB\-nv\fR] [\fB\-\-verbose\fR] -[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] +[\fB\-i\fR \fIFILE\fR\||\|\fB\-\-interfaces=\fR\fIFILE\fR\/] [\fB\-\-state-dir=\fR\fIDIR\fR] [\fB\-\-allow\fR \fICLASS\fR] \fIIFACE\fR... .PP .B ifquery -\fB\-l\fR|\fB\-\-list\fR +\fB\-l\fR\||\|\fB\-\-list\fR [\fB\-nv\fR] [\fB\-\-verbose\fR] -[\fB\-i\fR \fIFILE\fR|\fB\-\-interfaces=\fR\fIFILE\fR] +[\fB\-i\fR \fIFILE\fR\||\|\fB\-\-interfaces=\fR\fIFILE\fR\/] [\fB\-\-state-dir=\fR\fIDIR\fR] [\fB\-\-allow\fR \fICLASS\fR] -[\fB\-a\fR|\fIIFACE\fR...] +[\fB\-a\fR\||\|\fIIFACE\fR\/...] .PP .B ifquery \fB\-\-state\fR [\fB\-\-state-dir=\fR\fIDIR\fR] [\fB\-\-allow\fR \fICLASS\fR] -[\fB\-a\fR|\fIIFACE\fR...] +[\fB\-a\fR\,\fIIFACE\fR...] .SH DESCRIPTION The .BR ifup " and " ifdown commands may be used to configure (or, respectively, deconfigure) network interfaces based on interface definitions in the file -.IR /etc/network/interfaces ". " -.BR ifquery " command may be used to parse interfaces configuration." +.IR /etc/network/interfaces . +.br +.B ifquery +command may be used to parse interfaces configuration. .SH OPTIONS A summary of options is included below. .TP @@ -71,8 +73,8 @@ Combined with \fB-\-allow\fP, acts on al instead. If given to \fBifdown\fP, affect all defined interfaces. Interfaces are brought down in the order in which they are -currently listed in the state file. Only interfaces defined -in +currently listed in the state file. +Only interfaces defined in .I /etc/network/interfaces will be brought down. .TP @@ -88,11 +90,11 @@ Show summary of options. \fB\-\-allow=\fR\fICLASS\fR Only allow interfaces listed in an .I allow\-CLASS -line in +line in .IR /etc/network/interfaces " to be acted upon." .TP \fB\-i\fR \fIFILE\fR, \fB\-\-interfaces=\fR\fIFILE\fR -Read interface definitions from +Read interface definitions from .I FILE instead of from .IR /etc/network/interfaces "." @@ -105,8 +107,10 @@ instead of in .TP .BI \-X " PATTERN\fR, " "\-\-exclude=" PATTERN Exclude interfaces from the list of interfaces to operate on by the \fIPATTERN\fR. -\fIPATTERN\fR uses a usual shell glob syntax. If shell wildcards are not used, it -must match the exact interface name. This option may be specified multiple times +\fIPATTERN\fR uses a usual shell glob syntax. +If shell wildcards are not used, +it must match the exact interface name. +This option may be specified multiple times resulting in more than one pattern being excluded. .TP .BI \-o " OPTION" "\fB=" VALUE @@ -125,12 +129,16 @@ for more information about the mapping f Don't run any scripts under /etc/network/if-*.d/ .TP .B \-\-no\-loopback -Disable special handling of the loopback interface. By default, the loopback interface -(\fIlo\fR on Linux) is predefined internally as an auto interface, so it's brought up -on \fBifup -a\fR automatically. In the case the loopback device is redefined by user, -the interface is configured just once anyway. If, however, another interface is also -defined as loopback, it's configured as usual. Specifying this option disables this -behaviour, so the loopback interface won't be configured automatically. +Disable special handling of the loopback interface. +By default, the loopback interface +(\fIlo\fR on Linux) is predefined internally as an auto interface, +so it's brought up on \fBifup \-a\fR automatically. +In the case the loopback device is redefined by user, +the interface is configured just once anyway. +If, however, another interface is also defined as loopback, +it's configured as usual. +Specifying this option disables this behaviour, +so the loopback interface won't be configured automatically. .TP .BR \-V ", " \-\-version Show copyright and version information. @@ -142,18 +150,22 @@ Show commands as they are executed. For \fBifquery\fR, list all the interfaces which match the specified class. If no class specified, prints all the interfaces listed as \fBauto\fR. .TP -.BR \-\-state -For \fBifquery\fR, dump the state of the interfaces. When no interfaces specified, +.B \-\-state +For \fBifquery\fR, dump the state of the interfaces. +When no interfaces specified, lists all interfaces brought up together with logical interfaces assigned to them and -exits with a status code indicating success. If one or more interfaces specified, -display state of these interfaces only; successful code is returned if all of interfaces -given as arguments are up. Otherwise, 0 is returned. +exits with a status code indicating success. +If one or more interfaces specified, +display state of these interfaces only; +successful code is returned if all of interfaces +given as arguments are up. +Otherwise, 0 is returned. .SH EXAMPLES .TP -.B ifup -a +.B ifup \-a Bring up all the interfaces defined with .I auto -in +in .I /etc/network/interfaces .TP .B ifup eth0 @@ -166,41 +178,43 @@ Bring up interface as logical interface .B home .TP -.B ifdown -a +.B ifdown \-a Bring down all interfaces that are currently up. .TP -.B ifquery -l +.B ifquery \-l Print names of all interfaces specified with the \fBauto\fR keyword. .TP -.B ifquery -l --allow=hotplug +.B ifquery \-l \-\-allow=hotplug Print names of all interfaces specified with the \fBallow-hotplug\fR keyword. .TP .B ifquery eth0 Display the interface options as specified in the \fBifupdown\fR -configuration. Each key-value pair is printed out on individual +configuration. +Each key-value pair is printed out on individual line using "\fB: \fR" as separator. .SH NOTES .BR ifup , .BR ifdown , and -.BR ifquery +.B ifquery are actually the same program called by different names. .P The program does not configure network interfaces directly; it runs low level utilities such as -.BR ip +.B ip to do its dirty work. .P When invoked, .B ifdown checks if .B ifup -is still running. In that case, +is still running. +In that case, .B SIGTERM is sent to ifup. .P During interface deconfiguration, -.BR ifdown +.B ifdown ignores errors the same way as if .B \-\-ignore\-errors was specified. @@ -215,14 +229,17 @@ for more information. .I /run/network/ifstate current state of network interfaces .SH CONCURRENCY -Ifupdown uses per-interface locking to ensure that concurrent ifup and ifdown calls to the same interface are run in serial. +Ifupdown uses per-interface locking to ensure that concurrent ifup and +ifdown calls to the same interface are run in serial. However, calls to different interfaces will be able to run in parallel. .SH EXIT STATUS For .B ifup and -.B ifdown\fR, -the exit status will be 0 if the given interface(s) have all been (de)configured successfully, 1 if there was any error. +.BR ifdown , +the exit status will be 0 +if the given interface(s) have all been (de)configured successfully, +1 if there was any error. The result of these commands is idempotent; running .B ifup on an interface that is already up will result in an exit status of 0, and similarly running @@ -230,8 +247,10 @@ on an interface that is already up will on an interface that is not up will also result in an exit status of 0. .P .B ifquery -will normally return with exit status 0 if an interface with a matching iface stanza, 1 if there is no matching stanza. -.B ifquery --state +will normally return with exit status 0 +if an interface with a matching iface stanza, +1 if there is no matching stanza. +.B ifquery \-\-state will also return with exit status 1 if the given interface was known but was not up. .SH KNOWN BUGS/LIMITATIONS The program keeps records of whether network interfaces are up or down. @@ -272,7 +291,7 @@ without updating the file. Note that the program does not run automatically: .B ifup alone does not bring up interfaces -that appear as a result of hardware being installed and +that appear as a result of hardware being installed and .B ifdown alone does not bring down interfaces that disappear as a result of hardware being removed. -- System Information: Debian Release: trixie/sid APT prefers testing APT policy: (500, 'testing') Architecture: amd64 (x86_64) Kernel: Linux 6.1.27-1 (SMP w/2 CPU threads; PREEMPT) Locale: LANG=is_IS.iso88591, LC_CTYPE=is_IS.iso88591 (charmap=ISO-8859-1), LANGUAGE not set Shell: /bin/sh linked to /usr/bin/dash Init: sysvinit (via /sbin/init) Versions of packages ifupdown depends on: ii adduser 3.134 ii iproute2 6.1.0-3 ii libc6 2.36-9 Versions of packages ifupdown recommends: ii isc-dhcp-client [dhcp-client] 4.4.3-P1-2 Versions of packages ifupdown suggests: pn ppp <none> pn rdnssd <none> -- Configuration Files: /etc/default/networking changed [not included] /etc/init.d/networking changed [not included] -- no debconf information