Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, 2006-17-11 at 18:53 -0500, Paul Moore wrote:
jamal wrote:
I think we are best off punting on the userspace as there a multiple ways to
do
it: use good ole fashioned socket calls, the libnl library, or some other way
that hasn't been written yet. Besides, Thomas already has some pretty good
userspace documentation written for libnl; no sense in duplicating that
effort.
That has been my thinking as well. Looking at just the comments in the
code for the attribute stuff I think Thomas has done an excellent job in
documenting.
I havent looked at libnl in many moons (and dont have time at the
moment) - but it would be the right thing for a newbie/usability
approach.
In my tutorial I am not going to use it mostly because of lack of time
to figure out things (have to get out about 100 slides done by monday).
I already know how to use libnetlink and i have already added patches to
iproute2 for genetlink - so i am going to use those.
I will send you the tutorial so you can see what i mean.
That said, there is a kernel space example and a field breakdown; did that
look
okay?
It did. Just the little nitpicks i mentioned (like error checks etc). I
will stare at it some more later.
If the content is good but the layout is off we can always move it up
closer to the top of the document. If the content needs work lets deal with
that first ...
I think moving it up first may make it more usable. If i find this doc,
cutnpaste, change variable names, load it, refine it further to do what
i want ... that would be ideal.
Well, if we are talking about *needs* then nobody really needs more than the
source code.
I am not entirely sure i buy that anymore these days.
[The shock i had at some point is that the majority of linux users are
not subscribers to the code is the message philosophy. This was a
shock to me because the crowd i typically associate with always delivers
that message Look at the source and you shall be healed].
IMHO the main reason for documentation is to help speed along the
understanding of the code so it becomes more accessibile. I can see their
being
value for including both section I and section II material in the document.
sure, sure.
And in the complex case, source is useless if you dont know what is
being coded.
I know this is a big change, so it will depend on how much time you
have. I also think people may be happy with it in its current form. It
would be nice to get feedback from someone who has used it.
Well, it's Friday night and I've got a big football game to watch tommorrow so
I'm probably not going to devote much time to this until Monday.
Take it easy, no rush.
Let's see what
other people have to say in the meantime. We can always just submit/post it
and play with it as time permits.
indeed.
One of the main reasons I wanted to post my changes is because I found your
original document helpful when writing NetLabel but I didn't know about when I
started because it wasn't located in the usual places (I had to pick it out of
the mailing list archives). I think having a Generic Netlink document in
Documentation/ and/or on the OSDL network wiki is a good thing - even if it
isn't perfect.
I tend to be conservative when pushing to the kernel(you should see the
patches i am sitting on;-). But if you are brave, go ahead and submit
it. Perhaps you can put the doc somewhere, and send a url patch to the
kernel and then keep updating the web version.
Don't take it personally, it's just step one in my master plan to remove all
references too googah from the english language. Muwahahaha!
hehe. That would be hard unless you get rid of certain cartoon
characters ;-
I tend to like the actual references closer to the referring text (I dislike
scrolling) but I'm not too hung up on this, I can move it.
Your mileage may vary. Your call - The formal way is you have them at
the end.
Yeah, I stuggled with that the entire time I was writing that draft. I'm
still
not entirely happy with it either but I decided that I was tired of worrying
about it so I just sent it out.
I don't remember a section on terminology in your original doc, but I'll go
back
and check.
If it is not there, I suggest just adding it in II.
Hey, anybody who sends me text that doesn't include the phrase Justin
Timberlake Rocks gets to be a {co}author.
[Is Justin Timberlake the fella who got the FCC involved in Janet
Jacksons mammary glands? If, yes, he rocks!]
I'm just trying to keep the document
alive.
A noble effort. And i dont want to stress you with more work - As it is
it is not bad, it could just be better ;- (famous last words?)
[1] http://en.wikipedia.org/wiki/Foobar
My favorite wikipedia page - http://en.wikipedia.org/wiki/Mad_Scientist
Hey, how did my picture get there? ;-
cheers,
jamal
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Mon, 2006-13-11 at 15:06 -0500, Paul Moore wrote: jamal wrote: On Mon, 2006-13-11 at 09:08 -0500, Paul Moore wrote: I want to give Jamal a little bit longer to reply. Sorry, family emergency - still ongoing today, so havent looked at anything (including presentation that was supposed to be done) ;- Give me a day or two (I know i at least have to do the presentation or iam fscked ;-). No problem, life has a tendency to surprise us once in a while, hopefully it is nothing to terrible. Sorry, this was certainly more than 2 days; however, I am back (kinda). [Chasing something that is driving me nuts for the last hour or so for an iproute2 with ipsec with hope to introduce aevents.] i will review the doc as soon as i am done with that. cheers, jamal - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, 2006-17-11 at 08:05 -0500, jamal wrote: i will review the doc as soon as i am done with that. I glanced at the doc over lunch. I will give you high level views first and later on today or tomorrow i will give you a lot more pointed opinions. #1. I think the content layout has improved over the previous doc. So good stuff. Something still bothers me though; whether there is too much theory or verbosity (not that this long email has any of those characteristics;-). I am wondering if that affects usability. As a litmus test, what would be the answer to the question: If i didnt know anything about generic netlink, how long do i need to spend and immediately start programming? I dont think it is 5 minutes. Can we make it a 5 minute effort? I think this is partially my fault because thats how i laid out the original doc (and always is my style) - but you added more;- Heres a thought: ** lay it out is to have two sections: I. A LinuxWay section (others call it genetic programming!) a) heres an example for the kernel and heres the controller from user space b) heres what all different fields mean II. Here are all the nitty gritty details your mother never told you. What this means is someone can immediately jump to Ia) do it the LinuxWay(tm). When in doubt will read Ib) and when in further doubt will read II. [Actually Andrew Morton contented that nobody needs more than section I when i first posted the doc]. I know this is a big change, so it will depend on how much time you have. I also think people may be happy with it in its current form. It would be nice to get feedback from someone who has used it. 2) Hey - you got rid of foobar[1] and googah ;- I love those terms. No big deal - you own the doc now, so you can get away with things like that ;- 3) Why not create a references section at the end and move all the references you have scattered every there instead? 4) Terminology is still confusing even to me. We most definetely need such a section. For example, I dont like the term family to descrive those boxes that sit in the kernel. But i dont know what else to call them. Also looking closely at Thomas' introduction of the thing called nla_policy - it really oughta have been called attribute property. To add to this chaos - you introduced something you call a channel. A little confusing although sounds right ;- I think the previous doc had attempted something like a section on terms introduced by Balbir. But you may have gotten rid of it. 5) For registration of commands and families, you dont show the user handling return codes which could be errors. If this doc becomes scripture it could mean trouble. Just a cutnpaste from the original doc should suffice. 6) There is still a lot of content for theory mostly that is missing. I noticed you dont have async events, discovery etc. And there are still a few ideas i would like to discuss with Thomas and send patches for later. So keep me as a coauthor - it will keep me on the hook for now; i will bail out the moment i think it is complete. hope this helps. cheers, jamal [1] http://en.wikipedia.org/wiki/Foobar - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
jamal wrote: #1. I think the content layout has improved over the previous doc. So good stuff. Something still bothers me though; whether there is too much theory or verbosity (not that this long email has any of those characteristics;-). I am wondering if that affects usability. As a litmus test, what would be the answer to the question: If i didnt know anything about generic netlink, how long do i need to spend and immediately start programming? I dont think it is 5 minutes. Can we make it a 5 minute effort? I think this is partially my fault because thats how i laid out the original doc (and always is my style) - but you added more;- Heres a thought: ** lay it out is to have two sections: I. A LinuxWay section (others call it genetic programming!) a) heres an example for the kernel and heres the controller from user space b) heres what all different fields mean I think we are best off punting on the userspace as there a multiple ways to do it: use good ole fashioned socket calls, the libnl library, or some other way that hasn't been written yet. Besides, Thomas already has some pretty good userspace documentation written for libnl; no sense in duplicating that effort. That said, there is a kernel space example and a field breakdown; did that look okay? If the content is good but the layout is off we can always move it up closer to the top of the document. If the content needs work lets deal with that first ... II. Here are all the nitty gritty details your mother never told you. What this means is someone can immediately jump to Ia) do it the LinuxWay(tm). When in doubt will read Ib) and when in further doubt will read II. [Actually Andrew Morton contented that nobody needs more than section I when i first posted the doc]. Well, if we are talking about *needs* then nobody really needs more than the source code. IMHO the main reason for documentation is to help speed along the understanding of the code so it becomes more accessibile. I can see their being value for including both section I and section II material in the document. I know this is a big change, so it will depend on how much time you have. I also think people may be happy with it in its current form. It would be nice to get feedback from someone who has used it. Well, it's Friday night and I've got a big football game to watch tommorrow so I'm probably not going to devote much time to this until Monday. Let's see what other people have to say in the meantime. We can always just submit/post it and play with it as time permits. One of the main reasons I wanted to post my changes is because I found your original document helpful when writing NetLabel but I didn't know about when I started because it wasn't located in the usual places (I had to pick it out of the mailing list archives). I think having a Generic Netlink document in Documentation/ and/or on the OSDL network wiki is a good thing - even if it isn't perfect. 2) Hey - you got rid of foobar[1] and googah ;- I love those terms. No big deal - you own the doc now, so you can get away with things like that ;- Don't take it personally, it's just step one in my master plan to remove all references too googah from the english language. Muwahahaha! 3) Why not create a references section at the end and move all the references you have scattered every there instead? I tend to like the actual references closer to the referring text (I dislike scrolling) but I'm not too hung up on this, I can move it. 4) Terminology is still confusing even to me. We most definetely need such a section. For example, I dont like the term family to descrive those boxes that sit in the kernel. But i dont know what else to call them. Also looking closely at Thomas' introduction of the thing called nla_policy - it really oughta have been called attribute property. To add to this chaos - you introduced something you call a channel. A little confusing although sounds right ;- I think the previous doc had attempted something like a section on terms introduced by Balbir. But you may have gotten rid of it. Yeah, I stuggled with that the entire time I was writing that draft. I'm still not entirely happy with it either but I decided that I was tired of worrying about it so I just sent it out. I don't remember a section on terminology in your original doc, but I'll go back and check. 5) For registration of commands and families, you dont show the user handling return codes which could be errors. If this doc becomes scripture it could mean trouble. Just a cutnpaste from the original doc should suffice. Good point, I included it in the other examples but not that one - I'll fix it. 6) There is still a lot of content for theory mostly that is missing. I noticed you dont have async events, discovery etc. And there are still a few ideas i would like to discuss with Thomas and send patches for later. Yep, I was trying to get it fairly small so
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Monday 13 November 2006 2:23 am, Jarek Poplawski wrote: Sorry! Typo in @@ -436,20 part. Forget the earlier message. No problem, my first draft was full of typos too ;) So there is more... Jarek P. PS: It is added to my first patch because I don't know what is the current version. Thanks. I'm going to mail out the latest version (my first draft with everybody's patches) later today - I want to give Jamal a little bit longer to reply. -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Mon, 2006-13-11 at 09:08 -0500, Paul Moore wrote: I want to give Jamal a little bit longer to reply. Sorry, family emergency - still ongoing today, so havent looked at anything (including presentation that was supposed to be done) ;- Give me a day or two (I know i at least have to do the presentation or iam fscked ;-). cheers, jamal - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Jarek Poplawski wrote: @@ -586,7 +586,7 @@ goto failure; } /* add a DOC_EXMPL_A_MSG attribute */ - rc = nla_put_string(skb, DOC_EXMPL_A_MSG, Generic Netlink Rocks); + rc = nla_put_string(skb, DOC_EXMPL_A_MSG, Justin Timberlake rocks); if (rc != 0) goto failure; /* finalize the message */ So here I am applying this patch by hand because the diffs are a bit off and I come across this ... I think I might have to nix this change on the basis of rudimentary quality standards :) Besides, *I* brought sexy back. -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
jamal wrote: On Mon, 2006-13-11 at 09:08 -0500, Paul Moore wrote: I want to give Jamal a little bit longer to reply. Sorry, family emergency - still ongoing today, so havent looked at anything (including presentation that was supposed to be done) ;- Give me a day or two (I know i at least have to do the presentation or iam fscked ;-). No problem, life has a tendency to surprise us once in a while, hopefully it is nothing to terrible. For those of you who have been sending feedback, here is an updated copy to look over. I've taken pretty much everything but if there is still something awry feel free to send patches ... An Introduction To Using Generic Netlink === Last Updated: November 13, 2006 Table of Contents 1. Introduction 1.1. Document Overview 1.2. Netlink And Generic Netlink 2. Architectural Overview 3. Generic Netlink Families 3.1. Family Overview 3.1.1. The genl_family Structure 3.1.2. The genl_ops Structure 3.2. Registering A Family 4. Generic Netlink Communications 4.1. Generic Netlink Message Format 4.2. Kernel Communication 4.2.1. Sending Messages 4.2.2. Receiving Messages 4.3. Userspace Communication 5. Recommendations 5.1. Attributes And Message Payloads 5.2. Operation Granularity 5.3. Acknowledgment And Error Reporting 1. Introduction -- 1.1. Document Overview -- This document gives a brief introduction to Generic Netlink, some simple examples on how to use it, and some recommendations on how to make the most of the Generic Netlink communications interface. While this document does not require that the reader have a detailed understanding of what Netlink is and how it works, some basic Netlink knowledge is assumed. As usual, the kernel source code is your best friend here. While this document talks briefly about Generic Netlink from a userspace point of view, its primary focus is on the kernel's Generic Netlink API. It is recommended that application developers who are interested in using Generic Netlink make use of the libnl library[1]. [1] http://people.suug.ch/~tgr/libnl 1.2. Netlink And Generic Netlink -- Netlink is a flexible, robust wire-format communications channel typically used for kernel to user communication although it can also be used for user to user and kernel to kernel communications. Netlink communication channels are associated with families or busses, where each bus deals with a specific service; for example, different Netlink busses exist for routing, XFRM, netfilter, and several other kernel subsystems. More information about Netlink can be found in RFC 3549[2]. Over the years, Netlink has become very popular which has brought about a very real concern that the number of Netlink family numbers may be exhausted in the near future. In response to this the Generic Netlink family was created which acts as a Netlink multiplexer, allowing multiple services to use a single Netlink bus. [2] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt 2. Architectural Overview -- Figure #1 illustrates the basic Generic Netlink architecture which is composed of five different types of components: 1) The Netlink subsystem which serves as the underlying transport layer for all of the Generic Netlink communications. 2) The Generic Netlink bus which is implemented inside the kernel, but which is available to userspace through the socket API and inside the kernel via the normal Netlink and Generic Netlink APIs. 3) The Generic Netlink users who communicate with each other over the Generic Netlink bus; users can exist both in kernel and user space. 4) The Generic Netlink controller which is part of the kernel and is responsible for dynamically allocating Generic Netlink communication channels and other management tasks. The Generic Netlink controller is implemented as a standard Generic Netlink user, however, it listens on a special, pre-allocated Generic Netlink channel. 5) The kernel socket API. Generic Netlink sockets are created with the PF_NETLINK domain and the NETLINK_GENERIC protocol values. +-+ +-+ | (3) application A | | (3) application B | +--+--+ +--+--+ || \/ \ / || +---++---+ |:
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Mon, Nov 13, 2006 at 02:58:17PM -0500, Paul Moore wrote: Jarek Poplawski wrote: @@ -586,7 +586,7 @@ goto failure; } /* add a DOC_EXMPL_A_MSG attribute */ - rc = nla_put_string(skb, DOC_EXMPL_A_MSG, Generic Netlink Rocks); + rc = nla_put_string(skb, DOC_EXMPL_A_MSG, Justin Timberlake rocks); if (rc != 0) goto failure; /* finalize the message */ So here I am applying this patch by hand because the diffs are a bit off and I come across this ... I think I might have to nix this change on the basis of rudimentary quality standards :) Besides, *I* brought sexy back. It's too late! My Love (clip) nixed all possible standards so you'll have to update it soon anyway... Jarek P. - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, Nov 10, 2006 at 06:36:42PM +0100, Thomas Graf wrote:
* Jarek Poplawski [EMAIL PROTECTED] 2006-11-10 14:24
@@ -449,7 +449,7 @@
The second step is to define the operations for the family, which we do by
creating at least one instance of the genl_ops structure which we
explained in
-section 3.1.2.. In this example we are only going to define one operation
but
+section 3.1.2. In this example we are only going to define one operation
but
you can define up to 255 unique operations for each family.
/* handler */
@@ -465,7 +465,7 @@
DOC_EXMPL_C_ECHO,
__DOC_EXMPL_C_ECHO,
Careful, the typo is here, not below.
};
- #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_MAX - 1)
+ #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_ECHO - 1)
/* operation definition */
struct genl_ops doc_exmpl_gnl_ops_echo = {
But there is more...
Jarek P.
PS: It is added to my first patch because I don't know
what is the current version.
---
--- netlink.txt-2006-11-10 10:53:50.0 +0100
+++ netlink.txt 2006-11-13 07:53:41.0 +0100
@@ -32,7 +32,7 @@
1.1. Document Overview
--
-This document gives is a brief introduction to Generic Netlink, some simple
+This document gives a brief introduction to Generic Netlink, some simple
examples on how to use it, and some recommendations on how to make the most of
the Generic Netlink communications interface. While this document does not
require that the reader have a detailed understanding of what Netlink is
@@ -55,21 +55,21 @@
channels are associated with families or busses, where each bus deals with a
specific service; for example, different Netlink busses exist for routing,
XFRM, netfilter, and several other kernel subsystems. More information about
-Netlink can be found in RFC 3549[1].
+Netlink can be found in RFC 3549[2].
Over the years, Netlink has become very popular which has brought about a very
real concern that the number of Netlink family numbers may be exhausted in the
near future. In response to this the Generic Netlink family was created which
-acts as a Netlink multiplexer, allowing multiple service to use a single
+acts as a Netlink multiplexer, allowing multiple services to use a single
Netlink bus.
-[1] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
+[2] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
2. Architectural Overview
--
-Figure #1 illustrates how the basic Generic Netlink architecture which is
-composed of five different types of components.
+Figure #1 illustrates the basic Generic Netlink architecture which is
+composed of five different types of components:
1) The Netlink subsystem which serves as the underlying transport layer for
all of the Generic Netlink communications.
@@ -99,7 +99,7 @@
||
+---++---+
|: : | user-space
- =+: (5) Kernel socket API : +
+ =+: (5) kernel socket API : +
|: : | kernel-space
++---+---+
| |
@@ -112,7 +112,7 @@
+--+--+---++
| | |
+---+-+| |
- | (4) Controller | / \
+ | (4) controller | / \
+-+ / \
| |
+--+--+ +--+--+
@@ -141,15 +141,15 @@
--
The Generic Netlink mechanism is based on a client-server model. The Generic
-Netlink servers register families, which are a collection of well defined
-services, with the controller and the clients communicate with the server
+Netlink servers register with the controller families, which are a collection
+of well defined services, and the clients communicate with the servers
through these service registrations. This section explains how Generic Netlink
families are defined, created and registered.
3.1. Family Overview
--
-Generic Netlink family service registrations are defined by two structures,
+Generic Netlink family service registrations are defined by two structures:
genl_family and genl_ops. The genl_family structure defines the family and
it's associated communication channel. The genl_ops structure defines
an individual service or operation
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, Nov 10, 2006 at 06:36:42PM +0100, Thomas Graf wrote:
* Jarek Poplawski [EMAIL PROTECTED] 2006-11-10 14:24
@@ -449,7 +449,7 @@
The second step is to define the operations for the family, which we do by
creating at least one instance of the genl_ops structure which we
explained in
-section 3.1.2.. In this example we are only going to define one operation
but
+section 3.1.2. In this example we are only going to define one operation
but
you can define up to 255 unique operations for each family.
/* handler */
@@ -465,7 +465,7 @@
DOC_EXMPL_C_ECHO,
__DOC_EXMPL_C_ECHO,
Careful, the typo is here, not below.
};
- #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_MAX - 1)
+ #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_ECHO - 1)
/* operation definition */
struct genl_ops doc_exmpl_gnl_ops_echo = {
Sorry! Typo in @@ -436,20 part. Forget the earlier message.
So there is more...
Jarek P.
PS: It is added to my first patch because I don't know
what is the current version.
---
--- netlink.txt-2006-11-10 10:53:50.0 +0100
+++ netlink.txt 2006-11-13 07:53:41.0 +0100
@@ -32,7 +32,7 @@
1.1. Document Overview
--
-This document gives is a brief introduction to Generic Netlink, some simple
+This document gives a brief introduction to Generic Netlink, some simple
examples on how to use it, and some recommendations on how to make the most of
the Generic Netlink communications interface. While this document does not
require that the reader have a detailed understanding of what Netlink is
@@ -55,21 +55,21 @@
channels are associated with families or busses, where each bus deals with a
specific service; for example, different Netlink busses exist for routing,
XFRM, netfilter, and several other kernel subsystems. More information about
-Netlink can be found in RFC 3549[1].
+Netlink can be found in RFC 3549[2].
Over the years, Netlink has become very popular which has brought about a very
real concern that the number of Netlink family numbers may be exhausted in the
near future. In response to this the Generic Netlink family was created which
-acts as a Netlink multiplexer, allowing multiple service to use a single
+acts as a Netlink multiplexer, allowing multiple services to use a single
Netlink bus.
-[1] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
+[2] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
2. Architectural Overview
--
-Figure #1 illustrates how the basic Generic Netlink architecture which is
-composed of five different types of components.
+Figure #1 illustrates the basic Generic Netlink architecture which is
+composed of five different types of components:
1) The Netlink subsystem which serves as the underlying transport layer for
all of the Generic Netlink communications.
@@ -99,7 +99,7 @@
||
+---++---+
|: : | user-space
- =+: (5) Kernel socket API : +
+ =+: (5) kernel socket API : +
|: : | kernel-space
++---+---+
| |
@@ -112,7 +112,7 @@
+--+--+---++
| | |
+---+-+| |
- | (4) Controller | / \
+ | (4) controller | / \
+-+ / \
| |
+--+--+ +--+--+
@@ -141,15 +141,15 @@
--
The Generic Netlink mechanism is based on a client-server model. The Generic
-Netlink servers register families, which are a collection of well defined
-services, with the controller and the clients communicate with the server
+Netlink servers register with the controller families, which are a collection
+of well defined services, and the clients communicate with the servers
through these service registrations. This section explains how Generic Netlink
families are defined, created and registered.
3.1. Family Overview
--
-Generic Netlink family service registrations are defined by two structures,
+Generic Netlink family service registrations are defined by two structures:
genl_family and genl_ops. The genl_family structure defines the family and
it's associated communication channel. The
Re: Generic Netlink HOW-TO based on Jamal's original doc
* Paul Moore [EMAIL PROTECTED] 2006-11-10 01:08 Excellent! - u32 snd_pid This is the PID of the client which issued the request. In order to avoid confusion it might be better to call it netlink PID as it is not equal to the process ID. - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On 10-11-2006 07:08, Paul Moore wrote:
...
An Introduction To Using Generic Netlink
===
...
Here is a proposal of small adjustments.
Maybe some of them will be useful.
Best regards,
Jarek P.
---
--- netlink.txt-2006-11-10 10:53:50.0 +0100
+++ netlink.txt 2006-11-10 14:08:25.0 +0100
@@ -32,7 +32,7 @@
1.1. Document Overview
--
-This document gives is a brief introduction to Generic Netlink, some simple
+This document gives a brief introduction to Generic Netlink, some simple
examples on how to use it, and some recommendations on how to make the most of
the Generic Netlink communications interface. While this document does not
require that the reader have a detailed understanding of what Netlink is
@@ -55,21 +55,21 @@
channels are associated with families or busses, where each bus deals with a
specific service; for example, different Netlink busses exist for routing,
XFRM, netfilter, and several other kernel subsystems. More information about
-Netlink can be found in RFC 3549[1].
+Netlink can be found in RFC 3549[2].
Over the years, Netlink has become very popular which has brought about a very
real concern that the number of Netlink family numbers may be exhausted in the
near future. In response to this the Generic Netlink family was created which
-acts as a Netlink multiplexer, allowing multiple service to use a single
+acts as a Netlink multiplexer, allowing multiple services to use a single
Netlink bus.
-[1] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
+[2] ftp://ftp.rfc-editor.org/in-notes/rfc3549.txt
2. Architectural Overview
--
-Figure #1 illustrates how the basic Generic Netlink architecture which is
-composed of five different types of components.
+Figure #1 illustrates the basic Generic Netlink architecture which is
+composed of five different types of components:
1) The Netlink subsystem which serves as the underlying transport layer for
all of the Generic Netlink communications.
@@ -99,7 +99,7 @@
||
+---++---+
|: : | user-space
- =+: (5) Kernel socket API : +
+ =+: (5) kernel socket API : +
|: : | kernel-space
++---+---+
| |
@@ -112,7 +112,7 @@
+--+--+---++
| | |
+---+-+| |
- | (4) Controller | / \
+ | (4) controller | / \
+-+ / \
| |
+--+--+ +--+--+
@@ -149,7 +149,7 @@
3.1. Family Overview
--
-Generic Netlink family service registrations are defined by two structures,
+Generic Netlink family service registrations are defined by two structures:
genl_family and genl_ops. The genl_family structure defines the family and
it's associated communication channel. The genl_ops structure defines
an individual service or operation which the family provides to other Generic
@@ -161,7 +161,7 @@
[1] http://people.suug.ch/~tgr/libnl
-3.1.2. The genl_family Structure
+3.1.1. The genl_family Structure
Generic Netlink services are defined by the genl_family structure, which is
shown below:
@@ -241,7 +241,7 @@
* unsigned int flags
This field is used to specify any special attributes of the operation. The
- following flags may be used, multiple flags can be OR'd together:
+ following flags may be used (multiple flags can be OR'd together):
- GENL_ADMIN_PERM
@@ -251,11 +251,12 @@
This field defines the Netlink attribute policy for the operation request
message. If specified, the Generic Netlink mechanism uses this policy to
- verify all of the attributes in a operation request message before calling
+ verify all of the attributes in an operation request message before calling
the operation handler.
The attribute policy is defined as an array of nla_policy structures indexed
- by the attribute number. The nla_policy structure is defined in figure #4.
+ by the attribute number. The nla_policy structure is defined as shown in
+ figure #4.
struct nla_policy
{
@@ -269,7 +270,7 @@
- u16 type
- This specifies the type of the attribute, presently the following
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, 2006-10-11 at 01:45 -0500, Paul Moore wrote: James Morris wrote: An Introduction To Using Generic Netlink === Wow, this is great! Thanks. I consider it an act of penance for all of the evil things I did with Netlink on my first few iterations of NetLabel ;) Hey, theres more than one way to pay for your sins ;- For example: Do you wanna take over maintainance of the doc? ;- i.e it would make a lot of sense to finally submit it for inclusion. Thanks for the effort. I havent read it - dont have the time till this weekend. I would like to have input as well from the other folks who have opined in the past (on CC list - they seemed to have strong opinions of what should be in the doc). This is also timely because this weekend i was going to work on a presentation on this stuff for a conference ;- So i will actually have to read what you put together. I will have more comments later when i am done reading. cheers, jamal - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Paul Moore wrote: A couple of months ago I promised Jamal and Thomas I would post some comments to Jamal's original genetlink how-to. However, as I started to work on the document the diff from the original started to get a little ridiculous so instead of posting a patch against Jamal's original how-to I'm just posting the revised document in it's entirety. In the document below I tried to summarize all of the things I learned while developing NetLabel. Some of it came from Jamal's document, some the kernel code, and some from discussions with Thomas. Hopefully this document will make it much easier for others to use genetlink in the future. If this text below is acceptable to everyone, should this be added to the Documentation directory? Mind if we put a wikified version on http://linux-net.osdl.org? - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Thomas Graf wrote: * Paul Moore [EMAIL PROTECTED] 2006-11-10 01:08 Excellent! Thanks. - u32 snd_pid This is the PID of the client which issued the request. In order to avoid confusion it might be better to call it netlink PID as it is not equal to the process ID. Good point, I just made the change. I'll push out another rev of the document once the rest of the group has had a chance to review the doc. -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Jarek Poplawski wrote: On 10-11-2006 07:08, Paul Moore wrote: ... An Introduction To Using Generic Netlink === ... Here is a proposal of small adjustments. Maybe some of them will be useful. They all look very useful to me, thank you very much. I'm going to merge your patch and I'll put out an updated rev of the document once Jamal and some others have had a chance to review the document. -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
jamal wrote: On Fri, 2006-10-11 at 01:45 -0500, Paul Moore wrote: James Morris wrote: An Introduction To Using Generic Netlink === Wow, this is great! Thanks. I consider it an act of penance for all of the evil things I did with Netlink on my first few iterations of NetLabel ;) Hey, theres more than one way to pay for your sins ;- For example: Do you wanna take over maintainance of the doc? ;- There is a sucker born every minute. right? :) I'll make you a deal: I'll take over maintainance of the document as long as you promise to send me your feedback by Monday. i.e it would make a lot of sense to finally submit it for inclusion. Thanks for the effort. I think so too, I'm glad I was able to help out. I havent read it - dont have the time till this weekend. I would like to have input as well from the other folks who have opined in the past (on CC list - they seemed to have strong opinions of what should be in the doc). This is also timely because this weekend i was going to work on a presentation on this stuff for a conference ;- So i will actually have to read what you put together. I will have more comments later when i am done reading. Okay, I've already made some changes based on other comments in this thread but I'll refrain from pushing out an updated version until early next week. I'll also make the next version of the document a patch against net-2.6.20. Thanks. -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Stephen Hemminger wrote: Paul Moore wrote: A couple of months ago I promised Jamal and Thomas I would post some comments to Jamal's original genetlink how-to. However, as I started to work on the document the diff from the original started to get a little ridiculous so instead of posting a patch against Jamal's original how-to I'm just posting the revised document in it's entirety. In the document below I tried to summarize all of the things I learned while developing NetLabel. Some of it came from Jamal's document, some the kernel code, and some from discussions with Thomas. Hopefully this document will make it much easier for others to use genetlink in the future. If this text below is acceptable to everyone, should this be added to the Documentation directory? Mind if we put a wikified version on http://linux-net.osdl.org? That sounds fine to me, although can we hold off for a little bit so I can collect some more comments? Is the wiki open to anyone, i.e. can I add the document directly, or am I better off just letting you do it? -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, 10 Nov 2006 11:17:11 -0500 Paul Moore wrote: jamal wrote: On Fri, 2006-10-11 at 01:45 -0500, Paul Moore wrote: James Morris wrote: An Introduction To Using Generic Netlink === Wow, this is great! Thanks. I consider it an act of penance for all of the evil things I did with Netlink on my first few iterations of NetLabel ;) Hey, theres more than one way to pay for your sins ;- For example: Do you wanna take over maintainance of the doc? ;- There is a sucker born every minute. right? :) I'll make you a deal: I'll take over maintainance of the document as long as you promise to send me your feedback by Monday. Jamal, Were my patches ever merged into your document? i.e it would make a lot of sense to finally submit it for inclusion. Thanks for the effort. I think so too, I'm glad I was able to help out. I havent read it - dont have the time till this weekend. I would like to have input as well from the other folks who have opined in the past (on CC list - they seemed to have strong opinions of what should be in the doc). This is also timely because this weekend i was going to work on a presentation on this stuff for a conference ;- So i will actually have to read what you put together. I will have more comments later when i am done reading. Okay, I've already made some changes based on other comments in this thread but I'll refrain from pushing out an updated version until early next week. I'll also make the next version of the document a patch against net-2.6.20. --- ~Randy - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
* Jarek Poplawski [EMAIL PROTECTED] 2006-11-10 14:24
@@ -449,7 +449,7 @@
The second step is to define the operations for the family, which we do by
creating at least one instance of the genl_ops structure which we explained
in
-section 3.1.2.. In this example we are only going to define one operation
but
+section 3.1.2. In this example we are only going to define one operation but
you can define up to 255 unique operations for each family.
/* handler */
@@ -465,7 +465,7 @@
DOC_EXMPL_C_ECHO,
__DOC_EXMPL_C_ECHO,
Careful, the typo is here, not below.
};
- #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_MAX - 1)
+ #define DOC_EXMPL_C_MAX (__DOC_EXMPL_C_ECHO - 1)
/* operation definition */
struct genl_ops doc_exmpl_gnl_ops_echo = {
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
On Fri, 10 Nov 2006 01:08:23 -0500 Paul Moore wrote:
An Introduction To Using Generic Netlink
===
3.1.2. The genl_family Structure
Generic Netlink services are defined by the genl_family structure, which is
shown below:
struct genl_family
{
unsigned intid;
unsigned inthdrsize;
charname[GENL_NAMSIZ];
unsigned intversion;
unsigned intmaxattr;
struct nlattr **attrbuf;
struct list_headops_list;
struct list_headfamily_list;
};
Any alignment/packing concerns here? or that is already
handled, just not presented here?
and same questions for other structs below (deleted).
Typo patch attached.
---
~Randy
--- generic-netlink-howto.txt.~1~ 2006-11-10 09:35:03.0 -0800
+++ generic-netlink-howto.txt 2006-11-10 10:21:10.0 -0800
@@ -40,7 +40,7 @@
kernel source code is your best friend here.
While this document talks briefly about Generic Netlink from a userspace point
-of view it's primary focus is on the kernel's Generic Netlink API. It is
+of view, its primary focus is on the kernel's Generic Netlink API. It is
recommended that application developers who are interested in using Generic
Netlink make use of the libnl library[1].
@@ -141,17 +141,17 @@
--
The Generic Netlink mechanism is based on a client-server model. The Generic
-Netlink servers register families, which are a collection of well defined
+Netlink servers register families, which are a collection of well-defined
services, with the controller and the clients communicate with the server
through these service registrations. This section explains how Generic Netlink
-families are defined, created and registered.
+families are defined, created, and registered.
3.1. Family Overview
--
Generic Netlink family service registrations are defined by two structures,
genl_family and genl_ops. The genl_family structure defines the family and
-it's associated communication channel. The genl_ops structure defines
+its associated communication channel. The genl_ops structure defines
an individual service or operation which the family provides to other Generic
Netlink users.
@@ -191,7 +191,7 @@
* unsigned int hdrsize
- If the family makes use of a family specific header, it's size is stored
+ If the family makes use of a family specific header, its size is stored
here. If there is no family specific header this value should be zero.
* char name[GENL_NAMSIZ]
@@ -278,19 +278,19 @@
o NLA_U8
- A 8 bit unsigned integer
+ A 8-bit unsigned integer
o NLA_U16
- A 16 bit unsigned integer
+ A 16-bit unsigned integer
o NLA_U32
- A 32 bit unsigned integer
+ A 32-bit unsigned integer
o NLA_U64
- A 64 bit unsigned integer
+ A 64-bit unsigned integer
o NLA_FLAG
@@ -298,7 +298,7 @@
o NLA_MSECS
- A 64 bit time value in msecs
+ A 64-bit time value in msecs
o NLA_STRING
@@ -319,7 +319,7 @@
NULL byte. If the attribute type is unknown or NLA_UNSPEC then this field
should be set to the exact length of the attribute's payload.
- Unless the attribute type is one of the fixed length types above, a value
+ Unless the attribute type is one of the fixed-length types above, a value
of zero indicates that no validation of the attribute should be performed.
* int (*doit)(struct skbuff *skb, struct genl_info *info)
@@ -331,7 +331,7 @@
which triggered the handler and the second is a Generic Netlink genl_info
structure which is defined in figure #5.
- struct genl_ops
+ struct genl_info
{
u32 snd_seq;
u32 snd_pid;
@@ -449,7 +449,7 @@
The second step is to define the operations for the family, which we do by
creating at least one instance of the genl_ops structure which we explained in
-section 3.1.2.. In this example we are only going to define one operation but
+section 3.1.2. In this example we are only going to define one operation but
you can define up to 255 unique operations for each family.
/* handler */
@@ -659,19 +659,19 @@
* scalar values
- Most scalar values already have well defined attribute types, see section 3
- for details
+ Most scalar values already have well-defined attribute types; see section 3
+ for details.
* structures
Structures can be represented using a nested attribute with the structure
- fields represented as attributes in the payload of the container attribute
+ fields represented as attributes in the payload of the container
Re: Generic Netlink HOW-TO based on Jamal's original doc
Randy Dunlap wrote:
On Fri, 10 Nov 2006 01:08:23 -0500 Paul Moore wrote:
An Introduction To Using Generic Netlink
===
3.1.2. The genl_family Structure
Generic Netlink services are defined by the genl_family structure, which is
shown below:
struct genl_family
{
unsigned intid;
unsigned inthdrsize;
charname[GENL_NAMSIZ];
unsigned intversion;
unsigned intmaxattr;
struct nlattr **attrbuf;
struct list_headops_list;
struct list_headfamily_list;
};
Any alignment/packing concerns here? or that is already
handled, just not presented here?
and same questions for other structs below (deleted).
These structure contents/layout were taken straight from the code.
Typo patch attached.
Applied, thanks.
--
paul moore
linux security @ hp
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
* Randy Dunlap [EMAIL PROTECTED] 2006-11-10 10:23
On Fri, 10 Nov 2006 01:08:23 -0500 Paul Moore wrote:
An Introduction To Using Generic Netlink
===
3.1.2. The genl_family Structure
Generic Netlink services are defined by the genl_family structure, which is
shown below:
struct genl_family
{
unsigned intid;
unsigned inthdrsize;
charname[GENL_NAMSIZ];
unsigned intversion;
unsigned intmaxattr;
struct nlattr **attrbuf;
struct list_headops_list;
struct list_headfamily_list;
};
Any alignment/packing concerns here? or that is already
handled, just not presented here?
I thought I chose GENL_NAMESIZ wisely but to be sure I checked
with Mr. Alignment himself, Arnaldo:
struct genl_family {
unsigned int id; /* 0(0) 4 */
unsigned int hdrsize; /* 4(0) 4 */
char name[16]; /* 8(0)16 */
unsigned int version; /* 24(0) 4 */
unsigned int maxattr; /* 28(0) 4 */
/* -- cacheline 1 boundary -- */
struct nlattr * * attrbuf; /* 32(0) 4 */
struct list_head ops_list; /* 36(0) 8 */
struct list_head family_list; /* 44(0) 8 */
}; /* size: 52 */
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Thomas Graf wrote:
* Randy Dunlap [EMAIL PROTECTED] 2006-11-10 10:23
On Fri, 10 Nov 2006 01:08:23 -0500 Paul Moore wrote:
An Introduction To Using Generic Netlink
===
3.1.2. The genl_family Structure
Generic Netlink services are defined by the genl_family structure, which is
shown below:
struct genl_family
{
unsigned intid;
unsigned inthdrsize;
charname[GENL_NAMSIZ];
unsigned intversion;
unsigned intmaxattr;
struct nlattr **attrbuf;
struct list_headops_list;
struct list_headfamily_list;
};
Any alignment/packing concerns here? or that is already
handled, just not presented here?
I thought I chose GENL_NAMESIZ wisely but to be sure I checked
with Mr. Alignment himself, Arnaldo:
Hm, looks OK to me. Am I missing something?
struct genl_family {
unsigned int id; /* 0(0) 4 */
unsigned int hdrsize; /* 4(0) 4 */
char name[16]; /* 8(0)16 */
unsigned int version; /* 24(0) 4 */
unsigned int maxattr; /* 28(0) 4 */
/* -- cacheline 1 boundary -- */
struct nlattr * * attrbuf; /* 32(0) 4 */
struct list_head ops_list; /* 36(0) 8 */
struct list_head family_list; /* 44(0) 8 */
}; /* size: 52 */
How about field size issues? Usually for int's etc. that are in
userspace interfaces, we use __u32 etc.
--
~Randy
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
* Randy Dunlap [EMAIL PROTECTED] 2006-11-10 14:49
I thought I chose GENL_NAMESIZ wisely but to be sure I checked
with Mr. Alignment himself, Arnaldo:
Hm, looks OK to me. Am I missing something?
It is OK, I was merely trying to prove it :-)
struct genl_family {
unsigned int id; /* 0(0) 4 */
unsigned int hdrsize; /* 4(0) 4 */
char name[16]; /* 8(0)16 */
unsigned int version; /* 24(0) 4 */
unsigned int maxattr; /* 28(0) 4 */
/* -- cacheline 1 boundary -- */
struct nlattr * * attrbuf; /* 32(0) 4 */
struct list_head ops_list; /* 36(0) 8 */
struct list_head family_list; /* 44(0) 8 */
}; /* size: 52 */
How about field size issues? Usually for int's etc. that are in
userspace interfaces, we use __u32 etc.
This is kernel side only, struct genl_family lives in net/genetlink.h
and is not exported to userspace.
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
Thomas Graf wrote:
* Randy Dunlap [EMAIL PROTECTED] 2006-11-10 14:49
I thought I chose GENL_NAMESIZ wisely but to be sure I checked
with Mr. Alignment himself, Arnaldo:
Hm, looks OK to me. Am I missing something?
It is OK, I was merely trying to prove it :-)
struct genl_family {
unsigned int id; /* 0(0) 4 */
unsigned int hdrsize; /* 4(0) 4 */
char name[16]; /* 8(0)16 */
unsigned int version; /* 24(0) 4 */
unsigned int maxattr; /* 28(0) 4 */
/* -- cacheline 1 boundary -- */
struct nlattr * * attrbuf; /* 32(0) 4 */
struct list_head ops_list; /* 36(0) 8 */
struct list_head family_list; /* 44(0) 8 */
}; /* size: 52 */
How about field size issues? Usually for int's etc. that are in
userspace interfaces, we use __u32 etc.
This is kernel side only, struct genl_family lives in net/genetlink.h
and is not exported to userspace.
OK, thanks for the clarifications.
--
~Randy
-
To unsubscribe from this list: send the line unsubscribe netdev in
the body of a message to [EMAIL PROTECTED]
More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
An Introduction To Using Generic Netlink === Wow, this is great! -- James Morris [EMAIL PROTECTED] - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: Generic Netlink HOW-TO based on Jamal's original doc
James Morris wrote: An Introduction To Using Generic Netlink === Wow, this is great! Thanks. I consider it an act of penance for all of the evil things I did with Netlink on my first few iterations of NetLabel ;) -- paul moore linux security @ hp - To unsubscribe from this list: send the line unsubscribe netdev in the body of a message to [EMAIL PROTECTED] More majordomo info at http://vger.kernel.org/majordomo-info.html
