Debian Bug report logs - #481854
tc filters undocumented

Reply or subscribe to this bug.

Display info messages

Message #5 received at submit@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@debbugs.entuzijast.net>

To: submit@bugs.debian.org

Subject: tc filters undocumented

Date: Mon, 19 May 2008 02:28:20 +0200

Package: iproute
Version: 20061002-3

Hi,

tc-filters(8) is missing, even though it's referenced by tc(8). There were
bugs filed about both issues before, and they are all closed, yet the
situation is the same...

Please fix this. TIA.

-- 
     2. That which causes joy or happiness.

Message #10 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Andreas Henriksson <andreas@fatal.se>

To: Josip Rodin <joy@debbugs.entuzijast.net>, 481854@bugs.debian.org

Subject: Re: Bug#481854: tc filters undocumented

Date: Mon, 19 May 2008 08:29:12 +0200

tags 481854 etch
fixed 481854 20070313-1
thanks

On mån, 2008-05-19 at 02:28 +0200, Josip Rodin wrote:
> Package: iproute
> Version: 20061002-3
> 
> Hi,
> 
> tc-filters(8) is missing, even though it's referenced by tc(8). There were
> bugs filed about both issues before, and they are all closed, yet the
> situation is the same...
> 
> Please fix this. TIA.
> 

This has already been fixed in the above mentioned version (and
forwarded/merged upstream). kthxbye.

-- 
Regards,
Andreas Henriksson

Message #19 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@debbugs.entuzijast.net>

To: Andreas Henriksson <andreas@fatal.se>

Cc: 481854@bugs.debian.org

Subject: Re: Bug#481854: tc filters undocumented

Date: Mon, 19 May 2008 09:48:43 +0200

On Mon, May 19, 2008 at 08:29:12AM +0200, Andreas Henriksson wrote:
> tags 481854 etch
> fixed 481854 20070313-1
> thanks
> 
> On m??n, 2008-05-19 at 02:28 +0200, Josip Rodin wrote:
> > Package: iproute
> > Version: 20061002-3
> > 
> > Hi,
> > 
> > tc-filters(8) is missing, even though it's referenced by tc(8). There were
> > bugs filed about both issues before, and they are all closed, yet the
> > situation is the same...
> > 
> > Please fix this. TIA.
> > 
> 
> This has already been fixed in the above mentioned version (and
> forwarded/merged upstream). kthxbye.

Pity it's broken in stable. Oh well.

-- 
     2. That which causes joy or happiness.

Message #24 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@debbugs.entuzijast.net>

To: 481854@bugs.debian.org

Subject: tc filters still fairly undocumented

Date: Mon, 25 May 2009 22:17:54 +0200

Hi,

The lenny version of the tc(8) manual page no longer contains broken
references, but the situation didn't improve much otherwise.

The manual page says:

       tc filter [ add | change | replace ]
       dev DEV
       [ parent qdisc-id | root]
       protocol protocol
       prio priority
       filtertype [ filtertype specific parameters ]
       flowid flow-id

Whereas the tc binary says:

% sudo tc filter help
Usage: tc filter [ add | del | change | get ] dev STRING
       [ pref PRIO ] [ protocol PROTO ]
       [ estimator INTERVAL TIME_CONSTANT ]
       [ root | classid CLASSID ] [ handle FILTERID ]
       [ [ FILTER_TYPE ] [ help | OPTIONS ] ]

       tc filter show [ dev STRING ] [ root | parent CLASSID ]
Where:
FILTER_TYPE := { rsvp | u32 | fw | route | etc. }
FILTERID := ... format depends on classifier, see there
OPTIONS := ... try tc filter add <desired FILTER_KIND> help

% sudo tc filter add dev eth0 parent 1:0 protocol ip rsvp help
Usage: ... rsvp ipproto PROTOCOL session DST[/PORT | GPI ]
                [ sender SRC[/PORT | GPI ]
                [ classid CLASSID ] [ police POLICE_SPEC ]
                [ tunnelid ID ] [ tunnel ID skip NUMBER ]
Where: GPI := { flowlabel NUMBER | spi/ah SPI | spi/esp SPI |
                u{8|16|32} NUMBER mask MASK at OFFSET}
       POLICE_SPEC := ... look at TBF
       FILTERID := X:Y

NOTE: CLASSID is parsed as hexadecimal input.

% sudo tc filter add dev eth0 parent 1:0 protocol ip u32 help
Usage: ... u32 [ match SELECTOR ... ] [ link HTID ] [ classid CLASSID ]
               [ police POLICE_SPEC ] [ offset OFFSET_SPEC ]
               [ ht HTID ] [ hashkey HASHKEY_SPEC ]
               [ sample SAMPLE ]
or         u32 divisor DIVISOR

Where: SELECTOR := SAMPLE SAMPLE ...
       SAMPLE := { ip | ip6 | udp | tcp | icmp | u{32|16|8} | mark } SAMPLE_ARGS [divisor DIVISOR]
       FILTERID := X:Y:Z

NOTE: CLASSID is parsed at hexadecimal input.

% sudo tc filter add dev eth0 parent 1:0 protocol ip fw help  
Usage: ... fw [ classid CLASSID ] [ police POLICE_SPEC ]
       POLICE_SPEC := ... look at TBF
       CLASSID := X:Y

NOTE: CLASSID is parsed as hexadecimal input.

% sudo tc filter add dev eth0 parent 1:0 protocol ip route help
Usage: ... route [ from REALM | fromif TAG ] [ to REALM ]
                [ flowid CLASSID ] [ police POLICE_SPEC ]
       POLICE_SPEC := ... look at TBF
       CLASSID := X:Y

NOTE: CLASSID is parsed as hexadecimal input.

<end>

Just making these two consistent would be an improvement :)
But an actual explanation of how u32 and others work would
be necessary to make the documentation really useful.

-- 
     2. That which causes joy or happiness.

Message #29 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Andreas Henriksson <andreas@fatal.se>

To: Josip Rodin <joy@debbugs.entuzijast.net>, 481854@bugs.debian.org

Subject: Re: Bug#481854: tc filters still fairly undocumented

Date: Mon, 25 May 2009 23:16:19 +0200

Hello Josip!

Thanks for filing the documentation bugs and updating some more with
renewed information. Having the outstanding issues listed is a good
first step for anyone who's motivated to have a go at fixing them
instead of blindly/randomly looking for outdated manpages.

The manpages is a well known weak area of iproute. It would be very very
useful if someone was willing to take on this issue. I expect it to be a
pretty big one, because not only is there a massive work to do getting
the existing manpages up to date - it also needs to be an ongoing work
keeping them up to date since upstream changes happen frequently adding
new features and there's no established workflow that requires doc
updates with code changes. On top of this the documentation system has
fallen apart and there are some original sources that generate docs, but
the generated docs has been manually updated and some parts are just
manually written. A completely new grip on the entire situation would
probably be best to get a new and maintainable documentation system in
place, but that's just my very personal opinion..... Talking about
personal stuff, I don't think I will personally be able to tackle this,
since fixing code bugs is enough work for me already. Help would be
greatly appreciated!

So I'll finish off this mail with a classic comment:

On mån, 2009-05-25 at 22:17 +0200, Josip Rodin wrote:
[...]
> Just making these two consistent would be an improvement :)
[...]

Patches accepted!

;)

(I'll offer to forward them upstream for anyone willing to contribute
them.)

-- 
Regards,
Andreas Henriksson

Message #36 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Josip Rodin <joy@debbugs.entuzijast.net>

To: Andreas Henriksson <andreas@fatal.se>

Cc: 481854@bugs.debian.org

Subject: Re: Bug#481854: tc filters still fairly undocumented

Date: Tue, 26 May 2009 10:34:29 +0200

On Mon, May 25, 2009 at 11:16:19PM +0200, Andreas Henriksson wrote:
> Hello Josip!
> 
> Thanks for filing the documentation bugs and updating some more with
> renewed information. Having the outstanding issues listed is a good
> first step for anyone who's motivated to have a go at fixing them
> instead of blindly/randomly looking for outdated manpages.
> 
> The manpages is a well known weak area of iproute. It would be very very
> useful if someone was willing to take on this issue. I expect it to be a
> pretty big one, because not only is there a massive work to do getting
> the existing manpages up to date - it also needs to be an ongoing work
> keeping them up to date since upstream changes happen frequently adding
> new features and there's no established workflow that requires doc
> updates with code changes. On top of this the documentation system has
> fallen apart and there are some original sources that generate docs, but
> the generated docs has been manually updated and some parts are just
> manually written. A completely new grip on the entire situation would
> probably be best to get a new and maintainable documentation system in
> place, but that's just my very personal opinion..... Talking about
> personal stuff, I don't think I will personally be able to tackle this,
> since fixing code bugs is enough work for me already. Help would be
> greatly appreciated!
> 
> So I'll finish off this mail with a classic comment:
> 
> On m??n, 2009-05-25 at 22:17 +0200, Josip Rodin wrote:
> [...]
> > Just making these two consistent would be an improvement :)
> [...]
> 
> Patches accepted!
> 
> ;)
> 
> (I'll offer to forward them upstream for anyone willing to contribute
> them.)

It would be best if the upstream package would establish a system where all
options are extracted automatically from the help screens (or vice versa),
that way the manual pages would really start to serve their purpose - being
reference manuals, at least by listing the entire functionality. Obviously
we'd still need someone to actually explain anything, but it would be a step
in the right direction. This would also be a coding task, unrelated to any
possible dislike of writing documentation :) Please relay these wishes to
the upstream coders.

-- 
     2. That which causes joy or happiness.

Message #41 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Andreas Henriksson <andreas@fatal.se>

To: Josip Rodin <joy@debbugs.entuzijast.net>, 481854@bugs.debian.org

Subject: Re: Bug#481854: tc filters still fairly undocumented

Date: Tue, 26 May 2009 11:12:57 +0200

On Tue, May 26, 2009 at 10:34:29AM +0200, Josip Rodin wrote:
> 
> It would be best if the upstream package would establish a system where all
> options are extracted automatically from the help screens (or vice versa),

The help text is also incomplete.... Sometimes the option exists in the
manpages, sometimes in the help text, sometimes only in the code.

-- 
Andreas Henriksson

Message #48 received at 481854@bugs.debian.org (full text, mbox, reply):

From: Andreas Henriksson <andreas@fatal.se>

To: 481854@bugs.debian.org

Subject: tc filter documentation improved upstream

Date: Sun, 8 Nov 2015 00:09:23 +0100

Hello!

Just a short note to say that even if the docs might still not be perfect
they have been heavily improved upstream recently (and now included in
the 4.3.0 release).

See:
https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/commit/?id=a257bc7b4c481d4b2871508edfccc198d1e56c8a
+ previous related commits for sub-pages.

Maybe this bug can finally be closed soon.

Regards,
Andreas Henriksson

Message #61 received at 481854-done@bugs.debian.org (full text, mbox, reply):

From: Ben Hutchings <ben@decadent.org.uk>

To: 481854-done@bugs.debian.org

Subject: Re: tc filter documentation improved upstream

Date: Wed, 26 Mar 2025 19:27:58 +0100

[Message part 1 (text/plain, inline)]

Version: 4.3.0-1

On Sun, 8 Nov 2015 00:09:23 +0100 Andreas Henriksson <andreas@fatal.se>
wrote:
> Hello!
> 
> Just a short note to say that even if the docs might still not be
perfect
> they have been heavily improved upstream recently (and now included in
> the 4.3.0 release).
> 
> See:
>
https://git.kernel.org/cgit/linux/kernel/git/shemminger/iproute2.git/commit/?id=a257bc7b4c481d4b2871508edfccc198d1e56c8a
> + previous related commits for sub-pages.
> 
> Maybe this bug can finally be closed soon.

The manual pages were improved a lot, so let's call this fixed.

Ben.

-- 
Ben Hutchings
Everything should be made as simple as possible, but not simpler.
                                                      - Albert Einstein

[signature.asc (application/pgp-signature, inline)]

Send a report that this bug log contains spam.