4 ms·

Learning how to read the help output is often enough I find the 'ip --help' is virtually incomprehensible, and the man page no better. There's no explanation a

Learning how to read the help output is often enough I find the 'ip --help' is virtually incomprehensible, and the man page no better. There's no explanation about what the tool can do, only some machine-readable formatting of the syntax expected. This kind of documentation is useless IMO, it's actively hostile to new users.

mercora 8y ago
the help gets more specific the more complete your command gets. Try "ip link add type vlan help" for example. While i agree it does nothing to explain what the various switches do, if you know what you are trying to achieve this is most of the time enough. However i do not agree about the man pages the switches are explained there in enough detail in my opinion...
- joosters 8y ago
  The switches are useless until you have an idea about what the command can do. And yet the 'IP - COMMAND SYNTAX' section has text like 'link - network device'. What the hell does that mean? So 'ip link' does what exactly? Could the developers have typed more than just two words to try to explain this command (action?) Good luck to anyone who decides to RTFM.
  - sdfgdfhjdgj 8y ago
    SEE ALSO: ip-link(8) You have to read the manual too ;)
rmu09 8y ago
The tool allows one to manipulate kernel objects more or less 1:1, so documentation and help of 'ip' and 'tc' is adequate enough if you know what those kernel objects are and how they behave, but it won't help if you don't know anything about linux networking or traffic shaping in the first place.
- grepthisab 8y ago
  What's the best way to learn these things?
  - pas 8y ago
    LWN ( https://lwn.net/Kernel/Index/#Networking https://lwn.net/Kernel/Index/#Networking ), LWN + kernel documentation ( https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/networking https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin... ) , more LWN + iproute2 source/news/commitlog ( https://git.kernel.org/pub/scm/network/iproute2/iproute2.git/log/ https://git.kernel.org/pub/scm/network/iproute2/iproute2.git... and https://git.kernel.org/pub/scm/network/iproute2/iproute2.git/log/ip https://git.kernel.org/pub/scm/network/iproute2/iproute2.git... << basically the names will give you what to search for on LWN ), and a bit more reading ( https://www.netdevconf.org/ https://www.netdevconf.org/ ) ... and trying them (the features) out. In VMs and in other network simulators. ( http://mininet.org/overview/ http://mininet.org/overview/ comes to mind, but simply using Vagrant / Virtualbox is okay ) Also, networking is very standardized (duh :)), so if you follow network related stuff ( https://www.reddit.com/r/networking/ https://www.reddit.com/r/networking/ ), you can sort of get a feel for what might come to the Linux kernel. LWN is still the best in this regard, because it deals with new developments, so reading the archives will tell you what might be in the kernel. Furthermore, since nowadays everything is kube-cloud-virtual-container-open-netes-stack, looking at network developments for these technologies will get you in the know. (Seemingly bonkers stuff, like BGP for containers is now bog standard with things like Calico. Running a full switch in kernel with an awesome distributed overlay network for "cloud" without OpenFlow? OVN by OVS got your back. Doing all this fast? DPDK is uber fast, but XDP is just so conveniently clever.) Plus there's the datacenter networking stuff, like TRILL/SPB ( https://networkingnerd.net/2016/05/11/the-death-of-trill/ https://networkingnerd.net/2016/05/11/the-death-of-trill/ ), but those haven't got integrated into the kernel, because the aforementioned Calico, OVN and other overlay stuff. Oh, and the best way is to keep asking questions!
    - felixgallo 8y ago
      I'm sure you mean well, but this comment epitomizes the problem. Formerly, Unix was fairly modular, open to comprehension, and had excellent documentation guiding the user. Now, everyone who isn't a paying Red Hat support customer is not just on their own but thrown to the wolves.

mercora 8y ago

the help gets more specific the more complete your command gets. Try "ip link add type vlan help" for example. While i agree it does nothing to explain what the various switches do, if you know what you are trying to achieve this is most of the time enough. However i do not agree about the man pages the switches are explained there in enough detail in my opinion...

joosters 8y ago
The switches are useless until you have an idea about what the command can do. And yet the 'IP - COMMAND SYNTAX' section has text like 'link - network device'. What the hell does that mean? So 'ip link' does what exactly? Could the developers have typed more than just two words to try to explain this command (action?) Good luck to anyone who decides to RTFM.
- sdfgdfhjdgj 8y ago
  SEE ALSO: ip-link(8) You have to read the manual too ;)

rmu09 8y ago

The tool allows one to manipulate kernel objects more or less 1:1, so documentation and help of 'ip' and 'tc' is adequate enough if you know what those kernel objects are and how they behave, but it won't help if you don't know anything about linux networking or traffic shaping in the first place.

grepthisab 8y ago
What's the best way to learn these things?
- pas 8y ago
  LWN ( https://lwn.net/Kernel/Index/#Networking https://lwn.net/Kernel/Index/#Networking ), LWN + kernel documentation ( https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/Documentation/networking https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/lin... ) , more LWN + iproute2 source/news/commitlog ( https://git.kernel.org/pub/scm/network/iproute2/iproute2.git/log/ https://git.kernel.org/pub/scm/network/iproute2/iproute2.git... and https://git.kernel.org/pub/scm/network/iproute2/iproute2.git/log/ip https://git.kernel.org/pub/scm/network/iproute2/iproute2.git... << basically the names will give you what to search for on LWN ), and a bit more reading ( https://www.netdevconf.org/ https://www.netdevconf.org/ ) ... and trying them (the features) out. In VMs and in other network simulators. ( http://mininet.org/overview/ http://mininet.org/overview/ comes to mind, but simply using Vagrant / Virtualbox is okay ) Also, networking is very standardized (duh :)), so if you follow network related stuff ( https://www.reddit.com/r/networking/ https://www.reddit.com/r/networking/ ), you can sort of get a feel for what might come to the Linux kernel. LWN is still the best in this regard, because it deals with new developments, so reading the archives will tell you what might be in the kernel. Furthermore, since nowadays everything is kube-cloud-virtual-container-open-netes-stack, looking at network developments for these technologies will get you in the know. (Seemingly bonkers stuff, like BGP for containers is now bog standard with things like Calico. Running a full switch in kernel with an awesome distributed overlay network for "cloud" without OpenFlow? OVN by OVS got your back. Doing all this fast? DPDK is uber fast, but XDP is just so conveniently clever.) Plus there's the datacenter networking stuff, like TRILL/SPB ( https://networkingnerd.net/2016/05/11/the-death-of-trill/ https://networkingnerd.net/2016/05/11/the-death-of-trill/ ), but those haven't got integrated into the kernel, because the aforementioned Calico, OVN and other overlay stuff. Oh, and the best way is to keep asking questions!
  - felixgallo 8y ago
    I'm sure you mean well, but this comment epitomizes the problem. Formerly, Unix was fairly modular, open to comprehension, and had excellent documentation guiding the user. Now, everyone who isn't a paying Red Hat support customer is not just on their own but thrown to the wolves.