From a0e0018c9a7ef5ce7f6d2c3ae16aecbbd16a8f67 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sat, 4 May 2024 16:18:53 +0200 Subject: Adding upstream version 6.1.0. Signed-off-by: Daniel Baumann --- man/Makefile | 20 + man/man3/Makefile | 18 + man/man3/libnetlink.3 | 200 +++ man/man7/Makefile | 18 + man/man7/tc-hfsc.7 | 563 +++++++++ man/man8/.gitignore | 5 + man/man8/Makefile | 28 + man/man8/arpd.8 | 69 ++ man/man8/bridge.8 | 1291 +++++++++++++++++++ man/man8/ctstat.8 | 1 + man/man8/dcb-app.8 | 237 ++++ man/man8/dcb-buffer.8 | 126 ++ man/man8/dcb-dcbx.8 | 108 ++ man/man8/dcb-ets.8 | 194 +++ man/man8/dcb-maxrate.8 | 94 ++ man/man8/dcb-pfc.8 | 127 ++ man/man8/dcb.8 | 156 +++ man/man8/devlink-dev.8 | 354 ++++++ man/man8/devlink-dpipe.8 | 99 ++ man/man8/devlink-health.8 | 256 ++++ man/man8/devlink-lc.8 | 101 ++ man/man8/devlink-monitor.8 | 39 + man/man8/devlink-port.8 | 367 ++++++ man/man8/devlink-rate.8 | 270 ++++ man/man8/devlink-region.8 | 156 +++ man/man8/devlink-resource.8 | 79 ++ man/man8/devlink-sb.8 | 324 +++++ man/man8/devlink-trap.8 | 195 +++ man/man8/devlink.8 | 147 +++ man/man8/genl.8 | 77 ++ man/man8/ifstat.8 | 77 ++ man/man8/ip-address.8.in | 467 +++++++ man/man8/ip-addrlabel.8 | 56 + man/man8/ip-fou.8 | 126 ++ man/man8/ip-gue.8 | 1 + man/man8/ip-ioam.8 | 72 ++ man/man8/ip-l2tp.8 | 412 +++++++ man/man8/ip-link.8.in | 2863 +++++++++++++++++++++++++++++++++++++++++++ man/man8/ip-macsec.8 | 186 +++ man/man8/ip-maddress.8 | 59 + man/man8/ip-monitor.8 | 133 ++ man/man8/ip-mptcp.8 | 225 ++++ man/man8/ip-mroute.8 | 58 + man/man8/ip-neighbour.8 | 303 +++++ man/man8/ip-netconf.8 | 36 + man/man8/ip-netns.8.in | 271 ++++ man/man8/ip-nexthop.8 | 327 +++++ man/man8/ip-ntable.8 | 106 ++ man/man8/ip-route.8.in | 1386 +++++++++++++++++++++ man/man8/ip-rule.8 | 358 ++++++ man/man8/ip-sr.8 | 58 + man/man8/ip-stats.8 | 208 ++++ man/man8/ip-tcp_metrics.8 | 143 +++ man/man8/ip-token.8 | 75 ++ man/man8/ip-tunnel.8 | 281 +++++ man/man8/ip-vrf.8 | 111 ++ man/man8/ip-xfrm.8 | 760 ++++++++++++ man/man8/ip.8 | 445 +++++++ man/man8/lnstat.8 | 262 ++++ man/man8/nstat.8 | 1 + man/man8/rdma-dev.8 | 98 ++ man/man8/rdma-link.8 | 104 ++ man/man8/rdma-resource.8 | 125 ++ man/man8/rdma-statistic.8 | 255 ++++ man/man8/rdma-system.8 | 82 ++ man/man8/rdma.8 | 137 +++ man/man8/routel.8 | 33 + man/man8/rtacct.8 | 61 + man/man8/rtmon.8 | 68 + man/man8/rtstat.8 | 1 + man/man8/ss.8 | 602 +++++++++ man/man8/tc-actions.8 | 312 +++++ man/man8/tc-basic.8 | 34 + man/man8/tc-bfifo.8 | 74 ++ man/man8/tc-bpf.8 | 986 +++++++++++++++ man/man8/tc-cake.8 | 726 +++++++++++ man/man8/tc-cbq-details.8 | 423 +++++++ man/man8/tc-cbq.8 | 351 ++++++ man/man8/tc-cbs.8 | 124 ++ man/man8/tc-cgroup.8 | 80 ++ man/man8/tc-choke.8 | 63 + man/man8/tc-codel.8 | 122 ++ man/man8/tc-connmark.8 | 55 + man/man8/tc-csum.8 | 72 ++ man/man8/tc-ct.8 | 107 ++ man/man8/tc-ctinfo.8 | 171 +++ man/man8/tc-drr.8 | 94 ++ man/man8/tc-ematch.8 | 160 +++ man/man8/tc-etf.8 | 151 +++ man/man8/tc-ets.8 | 192 +++ man/man8/tc-flow.8 | 267 ++++ man/man8/tc-flower.8 | 515 ++++++++ man/man8/tc-fq.8 | 107 ++ man/man8/tc-fq_codel.8 | 143 +++ man/man8/tc-fq_pie.8 | 166 +++ man/man8/tc-fw.8 | 104 ++ man/man8/tc-gate.8 | 123 ++ man/man8/tc-hfsc.8 | 61 + man/man8/tc-htb.8 | 173 +++ man/man8/tc-ife.8 | 143 +++ man/man8/tc-matchall.8 | 87 ++ man/man8/tc-mirred.8 | 99 ++ man/man8/tc-mpls.8 | 194 +++ man/man8/tc-mqprio.8 | 150 +++ man/man8/tc-nat.8 | 78 ++ man/man8/tc-netem.8 | 236 ++++ man/man8/tc-pedit.8 | 402 ++++++ man/man8/tc-pfifo.8 | 1 + man/man8/tc-pfifo_fast.8 | 57 + man/man8/tc-pie.8 | 148 +++ man/man8/tc-police.8 | 168 +++ man/man8/tc-prio.8 | 185 +++ man/man8/tc-red.8 | 180 +++ man/man8/tc-route.8 | 74 ++ man/man8/tc-sample.8 | 122 ++ man/man8/tc-sfb.8 | 213 ++++ man/man8/tc-sfq.8 | 222 ++++ man/man8/tc-simple.8 | 98 ++ man/man8/tc-skbedit.8 | 74 ++ man/man8/tc-skbmod.8 | 160 +++ man/man8/tc-skbprio.8 | 70 ++ man/man8/tc-stab.8 | 163 +++ man/man8/tc-taprio.8 | 223 ++++ man/man8/tc-tbf.8 | 141 +++ man/man8/tc-tcindex.8 | 58 + man/man8/tc-tunnel_key.8 | 172 +++ man/man8/tc-u32.8 | 674 ++++++++++ man/man8/tc-vlan.8 | 164 +++ man/man8/tc-xt.8 | 42 + man/man8/tc.8 | 915 ++++++++++++++ man/man8/tipc-bearer.8 | 250 ++++ man/man8/tipc-link.8 | 383 ++++++ man/man8/tipc-media.8 | 87 ++ man/man8/tipc-nametable.8 | 110 ++ man/man8/tipc-node.8 | 72 ++ man/man8/tipc-peer.8 | 52 + man/man8/tipc-socket.8 | 59 + man/man8/tipc.8 | 109 ++ man/man8/vdpa-dev.8 | 166 +++ man/man8/vdpa-mgmtdev.8 | 53 + man/man8/vdpa.8 | 76 ++ 141 files changed, 30237 insertions(+) create mode 100644 man/Makefile create mode 100644 man/man3/Makefile create mode 100644 man/man3/libnetlink.3 create mode 100644 man/man7/Makefile create mode 100644 man/man7/tc-hfsc.7 create mode 100644 man/man8/.gitignore create mode 100644 man/man8/Makefile create mode 100644 man/man8/arpd.8 create mode 100644 man/man8/bridge.8 create mode 100644 man/man8/ctstat.8 create mode 100644 man/man8/dcb-app.8 create mode 100644 man/man8/dcb-buffer.8 create mode 100644 man/man8/dcb-dcbx.8 create mode 100644 man/man8/dcb-ets.8 create mode 100644 man/man8/dcb-maxrate.8 create mode 100644 man/man8/dcb-pfc.8 create mode 100644 man/man8/dcb.8 create mode 100644 man/man8/devlink-dev.8 create mode 100644 man/man8/devlink-dpipe.8 create mode 100644 man/man8/devlink-health.8 create mode 100644 man/man8/devlink-lc.8 create mode 100644 man/man8/devlink-monitor.8 create mode 100644 man/man8/devlink-port.8 create mode 100644 man/man8/devlink-rate.8 create mode 100644 man/man8/devlink-region.8 create mode 100644 man/man8/devlink-resource.8 create mode 100644 man/man8/devlink-sb.8 create mode 100644 man/man8/devlink-trap.8 create mode 100644 man/man8/devlink.8 create mode 100644 man/man8/genl.8 create mode 100644 man/man8/ifstat.8 create mode 100644 man/man8/ip-address.8.in create mode 100644 man/man8/ip-addrlabel.8 create mode 100644 man/man8/ip-fou.8 create mode 100644 man/man8/ip-gue.8 create mode 100644 man/man8/ip-ioam.8 create mode 100644 man/man8/ip-l2tp.8 create mode 100644 man/man8/ip-link.8.in create mode 100644 man/man8/ip-macsec.8 create mode 100644 man/man8/ip-maddress.8 create mode 100644 man/man8/ip-monitor.8 create mode 100644 man/man8/ip-mptcp.8 create mode 100644 man/man8/ip-mroute.8 create mode 100644 man/man8/ip-neighbour.8 create mode 100644 man/man8/ip-netconf.8 create mode 100644 man/man8/ip-netns.8.in create mode 100644 man/man8/ip-nexthop.8 create mode 100644 man/man8/ip-ntable.8 create mode 100644 man/man8/ip-route.8.in create mode 100644 man/man8/ip-rule.8 create mode 100644 man/man8/ip-sr.8 create mode 100644 man/man8/ip-stats.8 create mode 100644 man/man8/ip-tcp_metrics.8 create mode 100644 man/man8/ip-token.8 create mode 100644 man/man8/ip-tunnel.8 create mode 100644 man/man8/ip-vrf.8 create mode 100644 man/man8/ip-xfrm.8 create mode 100644 man/man8/ip.8 create mode 100644 man/man8/lnstat.8 create mode 100644 man/man8/nstat.8 create mode 100644 man/man8/rdma-dev.8 create mode 100644 man/man8/rdma-link.8 create mode 100644 man/man8/rdma-resource.8 create mode 100644 man/man8/rdma-statistic.8 create mode 100644 man/man8/rdma-system.8 create mode 100644 man/man8/rdma.8 create mode 100644 man/man8/routel.8 create mode 100644 man/man8/rtacct.8 create mode 100644 man/man8/rtmon.8 create mode 100644 man/man8/rtstat.8 create mode 100644 man/man8/ss.8 create mode 100644 man/man8/tc-actions.8 create mode 100644 man/man8/tc-basic.8 create mode 100644 man/man8/tc-bfifo.8 create mode 100644 man/man8/tc-bpf.8 create mode 100644 man/man8/tc-cake.8 create mode 100644 man/man8/tc-cbq-details.8 create mode 100644 man/man8/tc-cbq.8 create mode 100644 man/man8/tc-cbs.8 create mode 100644 man/man8/tc-cgroup.8 create mode 100644 man/man8/tc-choke.8 create mode 100644 man/man8/tc-codel.8 create mode 100644 man/man8/tc-connmark.8 create mode 100644 man/man8/tc-csum.8 create mode 100644 man/man8/tc-ct.8 create mode 100644 man/man8/tc-ctinfo.8 create mode 100644 man/man8/tc-drr.8 create mode 100644 man/man8/tc-ematch.8 create mode 100644 man/man8/tc-etf.8 create mode 100644 man/man8/tc-ets.8 create mode 100644 man/man8/tc-flow.8 create mode 100644 man/man8/tc-flower.8 create mode 100644 man/man8/tc-fq.8 create mode 100644 man/man8/tc-fq_codel.8 create mode 100644 man/man8/tc-fq_pie.8 create mode 100644 man/man8/tc-fw.8 create mode 100644 man/man8/tc-gate.8 create mode 100644 man/man8/tc-hfsc.8 create mode 100644 man/man8/tc-htb.8 create mode 100644 man/man8/tc-ife.8 create mode 100644 man/man8/tc-matchall.8 create mode 100644 man/man8/tc-mirred.8 create mode 100644 man/man8/tc-mpls.8 create mode 100644 man/man8/tc-mqprio.8 create mode 100644 man/man8/tc-nat.8 create mode 100644 man/man8/tc-netem.8 create mode 100644 man/man8/tc-pedit.8 create mode 100644 man/man8/tc-pfifo.8 create mode 100644 man/man8/tc-pfifo_fast.8 create mode 100644 man/man8/tc-pie.8 create mode 100644 man/man8/tc-police.8 create mode 100644 man/man8/tc-prio.8 create mode 100644 man/man8/tc-red.8 create mode 100644 man/man8/tc-route.8 create mode 100644 man/man8/tc-sample.8 create mode 100644 man/man8/tc-sfb.8 create mode 100644 man/man8/tc-sfq.8 create mode 100644 man/man8/tc-simple.8 create mode 100644 man/man8/tc-skbedit.8 create mode 100644 man/man8/tc-skbmod.8 create mode 100644 man/man8/tc-skbprio.8 create mode 100644 man/man8/tc-stab.8 create mode 100644 man/man8/tc-taprio.8 create mode 100644 man/man8/tc-tbf.8 create mode 100644 man/man8/tc-tcindex.8 create mode 100644 man/man8/tc-tunnel_key.8 create mode 100644 man/man8/tc-u32.8 create mode 100644 man/man8/tc-vlan.8 create mode 100644 man/man8/tc-xt.8 create mode 100644 man/man8/tc.8 create mode 100644 man/man8/tipc-bearer.8 create mode 100644 man/man8/tipc-link.8 create mode 100644 man/man8/tipc-media.8 create mode 100644 man/man8/tipc-nametable.8 create mode 100644 man/man8/tipc-node.8 create mode 100644 man/man8/tipc-peer.8 create mode 100644 man/man8/tipc-socket.8 create mode 100644 man/man8/tipc.8 create mode 100644 man/man8/vdpa-dev.8 create mode 100644 man/man8/vdpa-mgmtdev.8 create mode 100644 man/man8/vdpa.8 (limited to 'man') diff --git a/man/Makefile b/man/Makefile new file mode 100644 index 0000000..0c759dd --- /dev/null +++ b/man/Makefile @@ -0,0 +1,20 @@ +# SPDX-License-Identifier: GPL-2.0 +INSTALL=install +INSTALLDIR=install -m 0755 -d +INSTALLMAN=install -m 0644 +# Pass the same parameters as Lintian uses on Debian. +MAN_CHECK=LC_ALL=en_US.UTF-8 MANROFFSEQ='' MANWIDTH=80 man --warnings \ + --encoding=UTF-8 --local-file --troff-device=utf8 --ditroff +# Hide man output, count and print errors. +MAN_REDIRECT=2>&1 >/dev/null | tee /dev/fd/2 | wc -l + +SUBDIRS = man3 man7 man8 + +all clean install check: + @for subdir in $(SUBDIRS); do $(MAKE) -C $$subdir $@ || exit $$?; done + +distclean: clean + +.PHONY: install clean distclean check + +.EXPORT_ALL_VARIABLES: diff --git a/man/man3/Makefile b/man/man3/Makefile new file mode 100644 index 0000000..1732be2 --- /dev/null +++ b/man/man3/Makefile @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: GPL-2.0 +MAN3PAGES = $(wildcard *.3) + +all: + +distclean: clean + +clean: + +install: + $(INSTALLDIR) $(DESTDIR)$(MANDIR)/man3 + $(INSTALLMAN) $(MAN3PAGES) $(DESTDIR)$(MANDIR)/man3 + +check: + @for page in $(MAN3PAGES); do test 0 -eq $$($(MAN_CHECK) $$page \ + $(MAN_REDIRECT)) || { echo "Error in $$page"; exit 1; }; done + +.PHONY: install clean distclean check diff --git a/man/man3/libnetlink.3 b/man/man3/libnetlink.3 new file mode 100644 index 0000000..9a2c801 --- /dev/null +++ b/man/man3/libnetlink.3 @@ -0,0 +1,200 @@ +.TH libnetlink 3 +.SH NAME +libnetlink \- A library for accessing the netlink service +.SH SYNOPSIS +.nf +#include +.br +#include +.br +#include +.br +#include +.sp +int rtnl_open(struct rtnl_handle *rth, unsigned subscriptions) +.sp +int rtnl_wilddump_request(struct rtnl_handle *rth, int family, int type) +.sp +int rtnl_send(struct rtnl_handle *rth, char *buf, int len) +.sp +int rtnl_dump_request(struct rtnl_handle *rth, int type, void *req, int len) +.sp +int rtnl_dump_filter(struct rtnl_handle *rth, + int (*filter)(struct sockaddr_nl *, struct nlmsghdr *n, void *), + void *arg1, + int (*junk)(struct sockaddr_nl *,struct nlmsghdr *n, void *), + void *arg2) +.sp +int rtnl_talk(struct rtnl_handle *rtnl, struct nlmsghdr *n, pid_t peer, + unsigned groups, struct nlmsghdr *answer, +.br + int (*junk)(struct sockaddr_nl *,struct nlmsghdr *n, void *), +.br + void *jarg) +.sp +int rtnl_listen(struct rtnl_handle *rtnl, + int (*handler)(struct sockaddr_nl *, struct rtnl_ctrl_data *, + struct nlmsghdr *n, void *), + void *jarg) +.sp +int rtnl_from_file(FILE *rtnl, + int (*handler)(struct sockaddr_nl *,struct nlmsghdr *n, void *), + void *jarg) +.sp +int addattr32(struct nlmsghdr *n, int maxlen, int type, __u32 data) +.sp +int addattr_l(struct nlmsghdr *n, int maxlen, int type, void *data, int alen) +.sp +int rta_addattr32(struct rtattr *rta, int maxlen, int type, __u32 data) +.sp +int rta_addattr_l(struct rtattr *rta, int maxlen, int type, void *data, int alen) +.SH DESCRIPTION +libnetlink provides a higher level interface to +.BR rtnetlink (7). +The read functions return 0 on success and a negative errno on failure. +The send functions return the amount of data sent, or -1 on error. +.TP +rtnl_open +Open a rtnetlink socket and save the state into the +.B rth +handle. This handle is passed to all subsequent calls. +.B subscriptions +is a bitmap of the rtnetlink multicast groups the socket will be +a member of. + +.TP +rtnl_wilddump_request +Request a full dump of the +.B type +database for +.B family +addresses. +.B type +is a rtnetlink message type. +.\" XXX + +.TP +rtnl_dump_request +Request a full dump of the +.B type +data buffer into +.B buf +with maximum length of +.B len. +.B type +is a rtnetlink message type. + +.TP +rtnl_dump_filter +Receive netlink data after a request and filter it. +The +.B filter +callback checks if the received message is wanted. It gets the source +address of the message, the message itself and +.B arg1 +as arguments. 0 as return means that the filter passed, a negative +value is returned +by +.I rtnl_dump_filter +in case of error. NULL for +.I filter +means to not use a filter. +.B junk +is used to filter messages not destined to the local socket. +Only one message bundle is received. If there is a message +pending, this function does not block. + +.TP +rtnl_listen +Receive netlink data after a request and pass it to +.I handler. +.B handler +is a callback that gets the message source address, anscillary data, the message +itself, and the +.B jarg +cookie as arguments. It will get called for all received messages. +Only one message bundle is received. If there is a message +pending this function does not block. + +.TP +rtnl_from_file +Works like +.I rtnl_listen, +but reads a netlink message bundle from the file +.B file +and passes the messages to +.B handler +for parsing. The file should contain raw data as received from a rtnetlink socket. +.PP +The following functions are useful to construct custom rtnetlink messages. For +simple database dumping with filtering it is better to use the higher level +functions above. See +.BR rtnetlink (3) +and +.BR netlink (3) +on how to generate a rtnetlink message. The following utility functions +require a continuous buffer that already contains a netlink message header +and a rtnetlink request. + +.TP +rtnl_send +Send the rtnetlink message in +.B buf +of length +.B len +to handle +.B rth. + +.TP +addattr32 +Add a __u32 attribute of type +.B type +and with value +.B data +to netlink message +.B n, +which is part of a buffer of length +.B maxlen. + +.TP +addattr_l +Add a variable length attribute of type +.B type +and with value +.B data +and +.B alen +length to netlink message +.B n, +which is part of a buffer of length +.B maxlen. +.B data +is copied. + +.TP +rta_addattr32 +Initialize the rtnetlink attribute +.B rta +with a __u32 data value. + +.TP +rta_addattr32 +Initialize the rtnetlink attribute +.B rta +with a variable length data value. + +.SH BUGS +This library is meant for internal use, use libmnl for new programs. + +The functions sometimes use fprintf and exit when a fatal error occurs. +This library should be named librtnetlink. + +.SH AUTHORS +netlink/rtnetlink was designed and written by Alexey Kuznetsov. +Andi Kleen wrote the man page. + +.SH SEE ALSO +.BR netlink (7), +.BR rtnetlink (7) +.br +/usr/include/linux/rtnetlink.h diff --git a/man/man7/Makefile b/man/man7/Makefile new file mode 100644 index 0000000..c0e545a --- /dev/null +++ b/man/man7/Makefile @@ -0,0 +1,18 @@ +# SPDX-License-Identifier: GPL-2.0 +MAN7PAGES = $(wildcard *.7) + +all: + +distclean: clean + +clean: + +install: + $(INSTALLDIR) $(DESTDIR)$(MANDIR)/man7 + $(INSTALLMAN) $(MAN7PAGES) $(DESTDIR)$(MANDIR)/man7 + +check: + @for page in $(MAN7PAGES); do test 0 -eq $$($(MAN_CHECK) $$page \ + $(MAN_REDIRECT)) || { echo "Error in $$page"; exit 1; }; done + +.PHONY: install clean distclean check diff --git a/man/man7/tc-hfsc.7 b/man/man7/tc-hfsc.7 new file mode 100644 index 0000000..412b4c3 --- /dev/null +++ b/man/man7/tc-hfsc.7 @@ -0,0 +1,563 @@ +.TH "TC\-HFSC" 7 "31 October 2011" iproute2 Linux +.SH "NAME" +tc-hfcs \- Hierarchical Fair Service Curve +. +.SH "HISTORY & INTRODUCTION" +. +HFSC (Hierarchical Fair Service Curve) is a network packet scheduling algorithm that was first presented at +SIGCOMM'97. Developed as a part of ALTQ (ALTernative Queuing) on NetBSD, found +its way quickly to other BSD systems, and then a few years ago became part of +the linux kernel. Still, it's not the most popular scheduling algorithm \- +especially if compared to HTB \- and it's not well documented for the enduser. This introduction aims to explain how HFSC works without using +too much math (although some math it will be +inevitable). + +In short HFSC aims to: +. +.RS 4 +.IP \fB1)\fR 4 +guarantee precise bandwidth and delay allocation for all leaf classes (realtime +criterion) +.IP \fB2)\fR +allocate excess bandwidth fairly as specified by class hierarchy (linkshare & +upperlimit criterion) +.IP \fB3)\fR +minimize any discrepancy between the service curve and the actual amount of +service provided during linksharing +.RE +.PP +. +The main "selling" point of HFSC is feature \fB(1)\fR, which is achieved by +using nonlinear service curves (more about what it actually is later). This is +particularly useful in VoIP or games, where not only a guarantee of consistent +bandwidth is important, but also limiting the initial delay of a data stream. Note that +it matters only for leaf classes (where the actual queues are) \- thus class +hierarchy is ignored in the realtime case. + +Feature \fB(2)\fR is well, obvious \- any algorithm featuring class hierarchy +(such as HTB or CBQ) strives to achieve that. HFSC does that well, although +you might end with unusual situations, if you define service curves carelessly +\- see section CORNER CASES for examples. + +Feature \fB(3)\fR is mentioned due to the nature of the problem. There may be +situations where it's either not possible to guarantee service of all curves at +the same time, and/or it's impossible to do so fairly. Both will be explained +later. Note that this is mainly related to interior (aka aggregate) classes, as +the leafs are already handled by \fB(1)\fR. Still, it's perfectly possible to +create a leaf class without realtime service, and in such a case the caveats will +naturally extend to leaf classes as well. + +.SH ABBREVIATIONS +For the remaining part of the document, we'll use following shortcuts: +.nf +.RS 4 + +RT \- realtime +LS \- linkshare +UL \- upperlimit +SC \- service curve +.RE +.fi +. +.SH "BASICS OF HFSC" +. +To understand how HFSC works, we must first introduce a service curve. +Overall, it's a nondecreasing function of some time unit, returning the amount +of +service (an allowed or allocated amount of bandwidth) at some specific point in +time. The purpose of it should be subconsciously obvious: if a class was +allowed to transfer not less than the amount specified by its service curve, +then the service curve is not violated. + +Still, we need more elaborate criterion than just the above (although in +the most generic case it can be reduced to it). The criterion has to take two +things into account: +. +.RS 4 +.IP \(bu 4 +idling periods +.IP \(bu +the ability to "look back", so if during current active period the service curve is violated, maybe it +isn't if we count excess bandwidth received during earlier active period(s) +.RE +.PP +Let's define the criterion as follows: +.RS 4 +.nf +.IP "\fB(1)\fR" 4 +For each t1, there must exist t0 in set B, so S(t1\-t0)\~<=\~w(t0,t1) +.fi +.RE +. +.PP +Here 'w' denotes the amount of service received during some time period between t0 +and t1. B is a set of all times, where a session becomes active after idling +period (further denoted as 'becoming backlogged'). For a clearer picture, +imagine two situations: +. +.RS 4 +.IP \fBa)\fR 4 +our session was active during two periods, with a small time gap between them +.IP \fBb)\fR +as in (a), but with a larger gap +.RE +. +.PP +Consider \fB(a)\fR: if the service received during both periods meets +\fB(1)\fR, then all is well. But what if it doesn't do so during the 2nd +period? If the amount of service received during the 1st period is larger +than the service curve, then it might compensate for smaller service during +the 2nd period \fIand\fR the gap \- if the gap is small enough. + +If the gap is larger \fB(b)\fR \- then it's less likely to happen (unless the +excess bandwidth allocated during the 1st part was really large). Still, the +larger the gap \- the less interesting is what happened in the past (e.g. 10 +minutes ago) \- what matters is the current traffic that just started. + +From HFSC's perspective, more interesting is answering the following question: +when should we start transferring packets, so a service curve of a class is not +violated. Or rephrasing it: How much X() amount of service should a session +receive by time t, so the service curve is not violated. Function X() defined +as below is the basic building block of HFSC, used in: eligible, deadline, +virtual\-time and fit\-time curves. Of course, X() is based on equation +\fB(1)\fR and is defined recursively: + +.RS 4 +.IP \(bu 4 +At the 1st backlogged period beginning function X is initialized to generic +service curve assigned to a class +.IP \(bu +At any subsequent backlogged period, X() is: +.nf +\fBmin(X() from previous period ; w(t0)+S(t\-t0) for t>=t0),\fR +.fi +\&... where t0 denotes the beginning of the current backlogged period. +.RE +. +.PP +HFSC uses either linear, or two\-piece linear service curves. In case of +linear or two\-piece linear convex functions (first slope < second slope), +min() in X's definition reduces to the 2nd argument. But in case of two\-piece +concave functions, the 1st argument might quickly become lesser for some +t>=t0. Note, that for some backlogged period, X() is defined only from that +period's beginning. We also define X^(\-1)(w) as smallest t>=t0, for which +X(t)\~=\~w. We have to define it this way, as X() is usually not an injection. + +The above generic X() can be one of the following: +. +.RS 4 +.IP "E()" 4 +In realtime criterion, selects packets eligible for sending. If none are +eligible, HFSC will use linkshare criterion. Eligible time \&'et' is calculated +with reference to packets' heads ( et\~=\~E^(\-1)(w) ). It's based on RT +service curve, \fIbut in case of a convex curve, uses its 2nd slope only.\fR +.IP "D()" +In realtime criterion, selects the most suitable packet from the ones chosen +by E(). Deadline time \&'dt' corresponds to packets' tails +(dt\~=\~D^(\-1)(w+l), where \&'l' is packet's length). Based on RT service +curve. +.IP "V()" +In linkshare criterion, arbitrates which packet to send next. Note that V() is +function of a virtual time \- see \fBLINKSHARE CRITERION\fR section for +details. Virtual time \&'vt' corresponds to packets' heads +(vt\~=\~V^(\-1)(w)). Based on LS service curve. +.IP "F()" +An extension to linkshare criterion, used to limit at which speed linkshare +criterion is allowed to dequeue. Fit\-time 'ft' corresponds to packets' heads +as well (ft\~=\~F^(\-1)(w)). Based on UL service curve. +.RE + +Be sure to make clean distinction between session's RT, LS and UL service +curves and the above "utility" functions. +. +.SH "REALTIME CRITERION" +. +RT criterion \fIignores class hierarchy\fR and guarantees precise bandwidth and +delay allocation. We say that a packet is eligible for sending, when the +current real +time is later than the eligible time of the packet. From all eligible packets, the one most +suited for sending is the one with the shortest deadline time. This sounds +simple, but consider the following example: + +Interface 10Mbit, two classes, both with two\-piece linear service curves: +.RS 4 +.IP \(bu 4 +1st class \- 2Mbit for 100ms, then 7Mbit (convex \- 1st slope < 2nd slope) +.IP \(bu +2nd class \- 7Mbit for 100ms, then 2Mbit (concave \- 1st slope > 2nd slope) +.RE +.PP +Assume for a moment, that we only use D() for both finding eligible packets, +and choosing the most fitting one, thus eligible time would be computed as +D^(\-1)(w) and deadline time would be computed as D^(\-1)(w+l). If the 2nd +class starts sending packets 1 second after the 1st class, it's of course +impossible to guarantee 14Mbit, as the interface capability is only 10Mbit. +The only workaround in this scenario is to allow the 1st class to send the +packets earlier that would normally be allowed. That's where separate E() comes +to help. Putting all the math aside (see HFSC paper for details), E() for RT +concave service curve is just like D(), but for the RT convex service curve \- +it's constructed using \fIonly\fR RT service curve's 2nd slope (in our example + 7Mbit). + +The effect of such E() \- packets will be sent earlier, and at the same time +D() \fIwill\fR be updated \- so the current deadline time calculated from it +will be later. Thus, when the 2nd class starts sending packets later, both +the 1st and the 2nd class will be eligible, but the 2nd session's deadline +time will be smaller and its packets will be sent first. When the 1st class +becomes idle at some later point, the 2nd class will be able to "buffer" up +again for later active period of the 1st class. + +A short remark \- in a situation, where the total amount of bandwidth +available on the interface is larger than the allocated total realtime parts +(imagine a 10 Mbit interface, but 1Mbit/2Mbit and 2Mbit/1Mbit classes), the sole +speed of the interface could suffice to guarantee the times. + +Important part of RT criterion is that apart from updating its D() and E(), +also V() used by LS criterion is updated. Generally the RT criterion is +secondary to LS one, and used \fIonly\fR if there's a risk of violating precise +realtime requirements. Still, the "participation" in bandwidth distributed by +LS criterion is there, so V() has to be updated along the way. LS criterion can +than properly compensate for non\-ideal fair sharing situation, caused by RT +scheduling. If you use UL service curve its F() will be updated as well (UL +service curve is an extension to LS one \- see \fBUPPERLIMIT CRITERION\fR +section). + +Anyway \- careless specification of LS and RT service curves can lead to +potentially undesired situations (see CORNER CASES for examples). This wasn't +the case in HFSC paper where LS and RT service curves couldn't be specified +separately. + +.SH "LINKSHARING CRITERION" +. +LS criterion's task is to distribute bandwidth according to specified class +hierarchy. Contrary to RT criterion, there're no comparisons between current +real time and virtual time \- the decision is based solely on direct comparison +of virtual times of all active subclasses \- the one with the smallest vt wins +and gets scheduled. One immediate conclusion from this fact is that absolute +values don't matter \- only ratios between them (so for example, two children +classes with simple linear 1Mbit service curves will get the same treatment +from LS criterion's perspective, as if they were 5Mbit). The other conclusion +is, that in perfectly fluid system with linear curves, all virtual times across +whole class hierarchy would be equal. + +Why is VC defined in term of virtual time (and what is it)? + +Imagine an example: class A with two children \- A1 and A2, both with let's say +10Mbit SCs. If A2 is idle, A1 receives all the bandwidth of A (and update its +V() in the process). When A2 becomes active, A1's virtual time is already +\fIfar\fR later than A2's one. Considering the type of decision made by LS +criterion, A1 would become idle for a long time. We can workaround this +situation by adjusting virtual time of the class becoming active \- we do that +by getting such time "up to date". HFSC uses a mean of the smallest and the +biggest virtual time of currently active children fit for sending. As it's not +real time anymore (excluding trivial case of situation where all classes become +active at the same time, and never become idle), it's called virtual time. + +Such approach has its price though. The problem is analogous to what was +presented in previous section and is caused by non\-linearity of service +curves: +.IP 1) 4 +either it's impossible to guarantee service curves and satisfy fairness +during certain time periods: + +.RS 4 +Recall the example from RT section, slightly modified (with 3Mbit slopes +instead of 2Mbit ones): + +.IP \(bu 4 +1st class \- 3Mbit for 100ms, then 7Mbit (convex \- 1st slope < 2nd slope) +.IP \(bu +2nd class \- 7Mbit for 100ms, then 3Mbit (concave \- 1st slope > 2nd slope) + +.PP +They sum up nicely to 10Mbit \- the interface's capacity. But if we wanted to only +use LS for guarantees and fairness \- it simply won't work. In LS context, +only V() is used for making decision which class to schedule. If the 2nd class +becomes active when the 1st one is in its second slope, the fairness will be +preserved \- ratio will be 1:1 (7Mbit:7Mbit), but LS itself is of course +unable to guarantee the absolute values themselves \- as it would have to go +beyond of what the interface is capable of. +.RE + +.IP 2) 4 +and/or it's impossible to guarantee service curves of all classes at the same +time [fairly or not]: + +.RS 4 + +This is similar to the above case, but a bit more subtle. We will consider two +subtrees, arbitrated by their common (root here) parent: + +.nf +R (root) -\ 10Mbit + +A \- 7Mbit, then 3Mbit +A1 \- 5Mbit, then 2Mbit +A2 \- 2Mbit, then 1Mbit + +B \- 3Mbit, then 7Mbit +.fi + +R arbitrates between left subtree (A) and right (B). Assume that A2 and B are +constantly backlogged, and at some later point A1 becomes backlogged (when all +other classes are in their 2nd linear part). + +What happens now? B (choice made by R) will \fIalways\fR get 7 Mbit as R is +only (obviously) concerned with the ratio between its direct children. Thus A +subtree gets 3Mbit, but its children would want (at the point when A1 became +backlogged) 5Mbit + 1Mbit. That's of course impossible, as they can only get +3Mbit due to interface limitation. + +In the left subtree \- we have the same situation as previously (fair split +between A1 and A2, but violated guarantees), but in the whole tree \- there's +no fairness (B got 7Mbit, but A1 and A2 have to fit together in 3Mbit) and +there's no guarantees for all classes (only B got what it wanted). Even if we +violated fairness in the A subtree and set A2's service curve to 0, A1 would +still not get the required bandwidth. +.RE +. +.SH "UPPERLIMIT CRITERION" +. +UL criterion is an extensions to LS one, that permits sending packets only +if current real time is later than fit\-time ('ft'). So the modified LS +criterion becomes: choose the smallest virtual time from all active children, +such that fit\-time < current real time also holds. Fit\-time is calculated +from F(), which is based on UL service curve. As you can see, its role is +kinda similar to E() used in RT criterion. Also, for obvious reasons \- you +can't specify UL service curve without LS one. + +The main purpose of the UL service curve is to limit HFSC to bandwidth available on the +upstream router (think adsl home modem/router, and linux server as +NAT/firewall/etc. with 100Mbit+ connection to mentioned modem/router). +Typically, it's used to create a single class directly under root, setting +a linear UL service curve to available bandwidth \- and then creating your class +structure from that class downwards. Of course, you're free to add a UL service +curve (linear or not) to any class with LS criterion. + +An important part about the UL service curve is that whenever at some point in time +a class doesn't qualify for linksharing due to its fit\-time, the next time it +does qualify it will update its virtual time to the smallest virtual time of +all active children fit for linksharing. This way, one of the main things the LS +criterion tries to achieve \- equality of all virtual times across whole +hierarchy \- is preserved (in perfectly fluid system with only linear curves, +all virtual times would be equal). + +Without that, 'vt' would lag behind other virtual times, and could cause +problems. Consider an interface with a capacity of 10Mbit, and the following leaf classes +(just in case you're skipping this text quickly \- this example shows behavior +that \f(BIdoesn't happen\fR): + +.nf +A \- ls 5.0Mbit +B \- ls 2.5Mbit +C \- ls 2.5Mbit, ul 2.5Mbit +.fi + +If B was idle, while A and C were constantly backlogged, A and C would normally +(as far as LS criterion is concerned) divide bandwidth in 2:1 ratio. But due +to UL service curve in place, C would get at most 2.5Mbit, and A would get the +remaining 7.5Mbit. The longer the backlogged period, the more the virtual times of +A and C would drift apart. If B became backlogged at some later point in time, +its virtual time would be set to (A's\~vt\~+\~C's\~vt)/2, thus blocking A from +sending any traffic until B's virtual time catches up with A. +. +.SH "SEPARATE LS / RT SCs" +. +Another difference from the original HFSC paper is that RT and LS SCs can be +specified separately. Moreover, leaf classes are allowed to have only either +RT SC or LS SC. For interior classes, only LS SCs make sense: any RT SC will +be ignored. +. +.SH "CORNER CASES" +. +Separate service curves for LS and RT criteria can lead to certain traps +that come from "fighting" between ideal linksharing and enforced realtime +guarantees. Those situations didn't exist in original HFSC paper, where +specifying separate LS / RT service curves was not discussed. + +Consider an interface with a 10Mbit capacity, with the following leaf classes: + +.nf +A \- ls 5.0Mbit, rt 8Mbit +B \- ls 2.5Mbit +C \- ls 2.5Mbit +.fi + +Imagine A and C are constantly backlogged. As B is idle, A and C would divide +bandwidth in 2:1 ratio, considering LS service curve (so in theory \- 6.66 and +3.33). Alas RT criterion takes priority, so A will get 8Mbit and LS will be +able to compensate class C for only 2 Mbit \- this will cause discrepancy +between virtual times of A and C. + +Assume this situation lasts for a long time with no idle periods, and +suddenly B becomes active. B's virtual time will be updated to +(A's\~vt\~+\~C's\~vt)/2, effectively landing in the middle between A's and C's +virtual time. The effect \- B, having no RT guarantees, will be punished and +will not be allowed to transfer until C's virtual time catches up. + +If the interface had a higher capacity, for example 100Mbit, this example +would behave perfectly fine though. + +Let's look a bit closer at the above example \- it "cleverly" invalidates one +of the basic things LS criterion tries to achieve \- equality of all virtual +times across class hierarchy. Leaf classes without RT service curves are +literally left to their own fate (governed by messed up virtual times). + +Also, it doesn't make much sense. Class A will always be guaranteed up to +8Mbit, and this is more than any absolute bandwidth that could happen from its +LS criterion (excluding trivial case of only A being active). If the bandwidth +taken by A is smaller than absolute value from LS criterion, the unused part +will be automatically assigned to other active classes (as A has idling periods +in such case). The only "advantage" is, that even in case of low bandwidth on +average, bursts would be handled at the speed defined by RT criterion. Still, +if extra speed is needed (e.g. due to latency), non linear service curves +should be used in such case. + +In the other words: the LS criterion is meaningless in the above example. + +You can quickly "workaround" it by making sure each leaf class has RT service +curve assigned (thus guaranteeing all of them will get some bandwidth), but it +doesn't make it any more valid. + +Keep in mind - if you use nonlinear curves and irregularities explained above +happen \fIonly\fR in the first segment, then there's little wrong with +"overusing" RT curve a bit: + +.nf +A \- ls 5.0Mbit, rt 9Mbit/30ms, then 1Mbit +B \- ls 2.5Mbit +C \- ls 2.5Mbit +.fi + +Here, the vt of A will "spike" in the initial period, but then A will never get more +than 1Mbit until B & C catch up. Then everything will be back to normal. +. +.SH "LINUX AND TIMER RESOLUTION" +. +In certain situations, the scheduler can throttle itself and setup so +called watchdog to wakeup dequeue function at some time later. In case of HFSC +it happens when for example no packet is eligible for scheduling, and UL +service curve is used to limit the speed at which LS criterion is allowed to +dequeue packets. It's called throttling, and accuracy of it is dependent on +how the kernel is compiled. + +There're 3 important options in modern kernels, as far as timers' resolution +goes: \&'tickless system', \&'high resolution timer support' and \&'timer +frequency'. + +If you have \&'tickless system' enabled, then the timer interrupt will trigger +as slowly as possible, but each time a scheduler throttles itself (or any +other part of the kernel needs better accuracy), the rate will be increased as +needed / possible. The ceiling is either \&'timer frequency' if \&'high +resolution timer support' is not available or not compiled in, or it's +hardware dependent and can go \fIfar\fR beyond the highest \&'timer frequency' +setting available. + +If \&'tickless system' is not enabled, the timer will trigger at a fixed rate +specified by \&'timer frequency' \- regardless if high resolution timers are +or aren't available. + +This is important to keep those settings in mind, as in scenario like: no +tickless, no HR timers, frequency set to 100hz \- throttling accuracy would be +at 10ms. It doesn't automatically mean you would be limited to ~0.8Mbit/s +(assuming packets at ~1KB) \- as long as your queues are prepared to cover for +timer inaccuracy. Of course, in case of e.g. locally generated UDP traffic \- +appropriate socket size is needed as well. Short example to make it more +understandable (assume hardcore anti\-schedule settings \- HZ=100, no HR +timers, no tickless): + +.nf +tc qdisc add dev eth0 root handle 1:0 hfsc default 1 +tc class add dev eth0 parent 1:0 classid 1:1 hfsc rt m2 10Mbit +.fi + +Assuming packet of ~1KB size and HZ=100, that averages to ~0.8Mbit \- anything +beyond it (e.g. the above example with specified rate over 10x larger) will +require appropriate queuing and cause bursts every ~10 ms. As you can +imagine, any HFSC's RT guarantees will be seriously invalidated by that. +Aforementioned example is mainly important if you deal with old hardware \- as +is particularly popular for home server chores. Even then, you can easily +set HZ=1000 and have very accurate scheduling for typical adsl speeds. + +Anything modern (apic or even hpet msi based timers + \&'tickless system') +will provide enough accuracy for superb 1Gbit scheduling. For example, on one +of my cheap dual-core AMD boards I have the following settings: + +.nf +tc qdisc add dev eth0 parent root handle 1:0 hfsc default 1 +tc class add dev eth0 parent 1:0 classid 1:1 hfsc rt m2 300mbit +.fi + +And a simple: + +.nf +nc \-u dst.host.com 54321 /dev/null +.fi + +\&...will yield the following effects over a period of ~10 seconds (taken from +/proc/interrupts): + +.nf +319: 42124229 0 HPET_MSI\-edge hpet2 (before) +319: 42436214 0 HPET_MSI\-edge hpet2 (after 10s.) +.fi + +That's roughly 31000/s. Now compare it with HZ=1000 setting. The obvious +drawback of it is that cpu load can be rather high with servicing that +many timer interrupts. The example with 300Mbit RT service curve on 1Gbit link is +particularly ugly, as it requires a lot of throttling with minuscule delays. + +Also note that it's just an example showing the capabilities of current hardware. +The above example (essentially a 300Mbit TBF emulator) is pointless on an internal +interface to begin with: you will pretty much always want a regular LS service +curve there, and in such a scenario HFSC simply doesn't throttle at all. + +300Mbit RT service curve (selected columns from mpstat \-P ALL 1): + +.nf +10:56:43 PM CPU %sys %irq %soft %idle +10:56:44 PM all 20.10 6.53 34.67 37.19 +10:56:44 PM 0 35.00 0.00 63.00 0.00 +10:56:44 PM 1 4.95 12.87 6.93 73.27 +.fi + +So, in the rare case you need those speeds with only a RT service curve, or with a UL +service curve: remember the drawbacks. +. +.SH "CAVEAT: RANDOM ONLINE EXAMPLES" +. +For reasons unknown (though well guessed), many examples you can google love to +overuse UL criterion and stuff it in every node possible. This makes no sense +and works against what HFSC tries to do (and does pretty damn well). Use UL +where it makes sense: on the uppermost node to match upstream router's uplink +capacity. Or in special cases, such as testing (limit certain subtree to some +speed), or customers that must never get more than certain speed. In the last +case you can usually achieve the same by just using a RT criterion without LS+UL +on leaf nodes. + +As for the router case - remember it's good to differentiate between "traffic to +router" (remote console, web config, etc.) and "outgoing traffic", so for +example: + +.nf +tc qdisc add dev eth0 root handle 1:0 hfsc default 0x8002 +tc class add dev eth0 parent 1:0 classid 1:999 hfsc rt m2 50Mbit +tc class add dev eth0 parent 1:0 classid 1:1 hfsc ls m2 2Mbit ul m2 2Mbit +.fi + +\&... so "internet" tree under 1:1 and "router itself" as 1:999 +. +.SH "LAYER2 ADAPTATION" +. +Please refer to \fBtc\-stab\fR(8) +. +.SH "SEE ALSO" +. +\fBtc\fR(8), \fBtc\-hfsc\fR(8), \fBtc\-stab\fR(8) + +Please direct bugreports and patches to: +. +.SH "AUTHOR" +. +Manpage created by Michal Soltys (soltys@ziu.info) diff --git a/man/man8/.gitignore b/man/man8/.gitignore new file mode 100644 index 0000000..7b08e91 --- /dev/null +++ b/man/man8/.gitignore @@ -0,0 +1,5 @@ +# these pages are built +ip-address.8 +ip-link.8 +ip-netns.8 +ip-route.8 diff --git a/man/man8/Makefile b/man/man8/Makefile new file mode 100644 index 0000000..b1fd87b --- /dev/null +++ b/man/man8/Makefile @@ -0,0 +1,28 @@ +# SPDX-License-Identifier: GPL-2.0 +TARGETS = ip-address.8 ip-link.8 ip-netns.8 ip-route.8 + +MAN8PAGES = $(TARGETS) $(filter-out $(TARGETS),$(wildcard *.8)) + +all: $(TARGETS) + +%: %.in + sed \ + -e "s|@NETNS_ETC_DIR@|$(NETNS_ETC_DIR)|g" \ + -e "s|@NETNS_RUN_DIR@|$(NETNS_RUN_DIR)|g" \ + -e "s|@SYSCONFDIR@|$(CONFDIR)|g" \ + $< > $@ + +distclean: clean + +clean: + @rm -f $(TARGETS) + +install: + $(INSTALLDIR) $(DESTDIR)$(MANDIR)/man8 + $(INSTALLMAN) $(MAN8PAGES) $(DESTDIR)$(MANDIR)/man8 + +check: all + @for page in $(MAN8PAGES); do test 0 -eq $$($(MAN_CHECK) $$page \ + $(MAN_REDIRECT)) || { echo "Error in $$page"; exit 1; }; done + +.PHONY: install clean distclean check diff --git a/man/man8/arpd.8 b/man/man8/arpd.8 new file mode 100644 index 0000000..5050a98 --- /dev/null +++ b/man/man8/arpd.8 @@ -0,0 +1,69 @@ +.TH ARPD 8 "28 June, 2007" + +.SH NAME +arpd \- userspace arp daemon. + +.SH SYNOPSIS +Usage: arpd [ -lkh? ] [ -a N ] [ -b dbase ] [ -B number ] [ -f file ] [-p interval ] [ -n time ] [ -R rate ] [ ] + +.SH DESCRIPTION +The +.B arpd +daemon collects gratuitous ARP information, saving it on local disk and feeding it to the kernel on demand to avoid redundant broadcasting due to limited size of the kernel ARP cache. + +.SH OPTIONS +.TP +-h -? +Print help +.TP +-l +Dump the arpd database to stdout and exit. The output consists of three columns: the interface index, the IP address of the interface, and the MAC address of the interface. Negative entries for dead hosts are also shown, in this case the MAC address is replaced by the word FAILED followed by a colon and the most recent time when the fact that the host is dead was proven. +.TP +-f +Read and load an arpd database from FILE in a text format similar to that dumped by option -l. Exit after load, possibly listing resulting database, if option -l is also given. If FILE is -, stdin is read to get the ARP table. +.TP +-b +the location of the database file. The default location is /var/lib/arpd/arpd.db +.TP +-a +With this option, arpd not only passively listens for ARP packets on the interface, but also sends broadcast queries itself. NUMBER is the number of such queries to make before a destination is considered dead. When arpd is started as kernel helper (i.e. with app_solicit enabled in sysctl or even with option -k) without this option and still did not learn enough information, you can observe 1 second gaps in service. Not fatal, but not good. +.TP +-k +Suppress sending broadcast queries by the kernel. This option only makes sense together with option -a. +.TP +-n