Documentation!

Posted Mar 25, 2009 20:22 UTC (Wed) by nix (subscriber, #2304)
In reply to: Documentation! by dskoll
Parent article: Nftables: a new packet filtering engine

Seconded. I have no clue how to use the traffic control system: I tried to
learn, gave up when I realised how undocumented most of it was, and ended
up delegating the job to a Cisco router, which probably does a worse job
of it than the kernel could but at least is documented.

to post comments

Documentation!

Posted Mar 27, 2009 4:46 UTC (Fri) by rusty (guest, #26) [Link] (4 responses)

Actually, Alexey wrote excellent (if highly technical) documentation for the ip command. It's
called ip-cref.tex and it's in the source distribution of iproute2.

That said, I'd be happy to write a HOWTO for nftables, once it's ready for non-devs. Only takes
about a week to write a decent HOWTO.

Documentation!

Posted Mar 27, 2009 6:26 UTC (Fri) by ras (subscriber, #33059) [Link]

Yes. He did. I have read it many a time, along with its companion ip-tunnels.tex. However iproute has two main commands: ip and tc. ip-cref.tex and ip-tunnels.txt only cover ip. I have no problem with either of them, other than perhaps him not providing them in the form of a man page.

But ip is a relatively simple command compared to tc, and all he provided for it was README.iproute2+tc. I guess without it, I would not have known the purpose of the tc command. For the rest I had to read the source.

> That said, I'd be happy to write a HOWTO for nftables

Bugger future messes these people might create, how about fixing the ones they have left behind? I wrote my own doco when I decided to use tc in anger: http://www.stuart.id.au/russell/files/tc/doc so I am not asking for someone to do something I haven't done myself. And before you ask the obvious question: after dealing with the kernel devs once, I think Conroy must be easier to deal with. Perhaps I exaggerate, but only by a tiny bit.

Documentation!

Posted Mar 27, 2009 18:09 UTC (Fri) by kaber (guest, #18366) [Link] (1 responses)

pdf and man-generation from docbook source are integrated and I even already wrote a few lines :) While I'm not good at writing HOWTO's, I intend to write command reference, syntax etc. documentation.

Documentation!

Posted Mar 27, 2009 23:52 UTC (Fri) by ras (subscriber, #33059) [Link]

This is great news.

Writing reference documentation (like a man page) is something programmers do well. Writing concise (as in contains few redundancies), complete and unambiguous explanations is what most programmers do naturally - and it normally comes easily to them regardless of the language - C or English. I suspect this is why the man page system is one of the best sources of documentation around. There are notable exceptions of course - like the sudo man page, but even that manages to be clearer than some ISO specs I have read.

HOWTO's and tutorials - well rusty seems to have a remarkable talent for it, but he is the exception rather than the rule. The best HOWTO's seem to come from the users.

I see below you are talking of adding nftables as a classifier. This is even better news. It is a way of evolving the mess we have now into something sane.

Documentation!

Posted Jun 4, 2014 19:49 UTC (Wed) by pgoetz (guest, #4931) [Link]

I'm trying to use nftables now ... in 2014. How about that HOWTO?

Documentation!

Posted Mar 27, 2009 21:51 UTC (Fri) by giraffedata (guest, #1954) [Link] (2 responses)

But are you saying you'd be better off if there were no traffic control system? Because I believe that's what dskoll's point is: a patch that adds a feature should be rejected unless it additionally adds documentation to help people use it.

There is plenty of open source code I don't use because of lack of quality documentation, but I never fault the person who made the code available to me.

Documentation!

Posted Mar 28, 2009 0:59 UTC (Sat) by ras (subscriber, #33059) [Link] (1 responses)

> I never fault the person who made the code available to me.

There is no doubt in this case I _am_ faulting the person who provided the code. Well, to be more accurate, I fault the project. The project should not accept the code without documentation.

Evidently you think this is unreasonable. But my attitude is actually worse, if that is possible - I hold different projects to different standards. I am perfectly happy with a buggy, poorly documented 1000 line utility I found on sourceforge. Yet when it comes to large projects like samba, apache and gcc I expect so much more. I actually expect code and documentation that is at least as good as I get from a commercial vendor. Can you believe that! I actually expect the open source process to produce a better quality product than something I pay money for!

Well unreasonable or not, I write the occasional open source program and I hold myself to those standards. You sort of have to really, because if you produce crap everyone can see it - you ain't some anonymous coder hiding behind an organisation.

Still, I don't produce code as good as I see in the kernel. Patrick, rusty and friends - they hold each other to the highest standards. New code that makes it into the kernel core is usually beautifully written. And the kernel project has a savage review process that ensures it stays that way.

Yet no matter how beautiful the code is, there is no point it if nobody uses it. And that is the situation netfilter finds itself in. Out of all the potential uses it might have it is deployed in, it is in but a fraction of them. This is because figuring out how to use it is a huge effort. Because there is no doco you have to read the source to get a true understanding of how it works. Thus only C programmers who are prepared to troll the kernel and iproute2 source really have a clue. Actually it is even worse than that. In the case of the schedulers the code is (necessarily) so complex the code only gets you part way there. You have to read the original academic papers on the algorithms used. (HTB, being the only scheduler written outside of the kernel team, is the one exception.) The situation is so bad its even defeated all the book writers.

So, returning to the original point, we have arguably the largest open source project of them all, the kernel, churning out code almost no one uses because they don't regard documentation as an important part of the final product. And yeah, I think this means the kernel development process is broken. And yes, I hold the people who drive that development process accountable. They could do so much better.

Documentation!

Posted Apr 16, 2009 6:23 UTC (Thu) by zmi (guest, #4829) [Link]

It would be *so nice* to have documentation for "tc". I once tried to use
it, but didn't understand it really. There was a package "wondershaper" on
SUSE Linux, but still I never managed to do much more than add a port to
"higher priority".

Having a clean, logical and documented integration of traffic shaping and
firewalling would be a good reason to switch to nftables.

Of the GUI tools I really like "fwbuilder", although it lacks the ability
to define subroutines so you could compress several checks into one call
and thus make the overall ruleset smaller and cleaner.