If you caught my last post, you learned about compiling libnagios and using the Nagios library in your own code. This time we’re going to use that same Nagios library along with some borrowed NDOUtils code and build something super neat: a message passing system utilizing key-value vectors and buffers attached to the kernel messaging (IPC) utilities from NDO.
Just like last time, I’m going to assume you have a sane build environment set up (where tools like make and ./configure are working) before we go any further. If you are following along, now would be the time to get these in order.
Before we get started writing our own code, we need to borrow some files from NDOUtils. We only need two files: src/queue.c and include/queue.h. You can find the source for each at https://github.com/NagiosEnterprises/ndoutils/blob/master/src/queue.c and https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h, respectively. Once you have them downloaded, we’ll be ready to move on.
First, open up queue.c in your favorite editor and delete the line that includes “../include/config.h” (we’ll manually include the headers we need in a bit). You’ll want to change the path to your queue.h file to reflect wherever you downloaded it. For the purposes of this post and the examples that follow, all of my source and header files will be in the root directory of the Nagios Core source code that we downloaded while following along with the last post.
So, the top of your queue.c should have looked like this when you downloaded it:
|
1 2 3 4 |
#include "../include/config.h" #include "../include/queue.h" #include <sys/ipc.h> #include <sys/msg.h> |
After you’ve made the changes I mentioned, it should look like this:
|
1 2 3 |
#include "queue.h" #include <sys/ipc.h> #include <sys/msg.h> |
Save that file and open up queue.h. We’re going to add all of the necessary header files that would have been included with config.h in here. Find the line that defines NDOUTILS_INCLUDE_QUEUE_H, and directly after it add the following include directives:
|
1 2 3 4 5 6 7 |
#include <syslog.h> #include <string.h> #include <errno.h> #include <stdio.h> #include <signal.h> #include <stdlib.h> #include <unistd.h> |
By now, the top of your queue.h file should look like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 |
#ifndef NDOUTILS_INCLUDE_QUEUE_H #define NDOUTILS_INCLUDE_QUEUE_H #include <syslog.h> #include <string.h> #include <errno.h> #include <stdio.h> #include <signal.h> #include <stdlib.h> #include <unistd.h> #define NDO_QUEUE_PATH "." |
Perfect! Now we’re going to set up our main application. Last time I walked through the file as we were creating it, but this time it’s a tad more advanced so we’re going to look at it in its entirety and then step through the explanation. Create a file named test2.c, and fill it with the following content:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 |
#include "lib/libnagios.h" #include "queue.h" /* function for walking a kvv and performing this function on each key/value */ static int walker(struct key_value *kv, void *discard) { /* all we care about is printing the values to the screen */ printf("walking kvv, key: %s, value: %s\n", kv->key, kv->value); return 0; } int main(void) { /* these will be used for distinguishing key/value pairs and sets */ char KEYVAL_SEP = '='; char PAIR_SEP = ';'; int OVERALLOC = 2; /* some keys and values */ const char *keyval[] = { "key1=value1", "foo=bar", "nagios=rules" }; int keyval_len = 3; /* setup some key value vectors and initialize 1, save the other 2 for later */ struct kvvec *kvv, *kvv_from_msg_queue; struct kvvec_buf *kvv_buf; kvv = kvvec_create(keyval_len); /* add our keys and values to the vector */ int i; for (i = 0; i < keyval_len; i++) { char *arg = strdup(keyval[i]); char *eq = strchr(arg, '='); if (eq) *eq++ = 0; kvvec_addkv(kvv, strdup(arg), strdup(eq)); free(arg); /* eq is destroyed here as well */ } /* lets print the keys and values */ printf("\nprinting keys and values of kvv\n"); kvvec_foreach(kvv, NULL, walker); /* now lets sort it and print it one more time */ printf("\nsorting then printing keys and values of kvv\n"); kvvec_sort(kvv); kvvec_foreach(kvv, NULL, walker); /* now lets add kvv to kvv_buf so that we can put it in the kernel msg queue */ kvv_buf = kvvec2buf(kvv, KEYVAL_SEP, PAIR_SEP, OVERALLOC); /* set up a queue using our borrowed ndo2db queue code */ ndo2db_queue_init(getpid()); /* initialize a message with our kvv_buf data and send it to the queue */ struct ndo2db_queue_msg msg; strcpy(msg.text, kvv_buf->buf); ndo2db_queue_send(&msg, kvv_buf->buflen); /* get our message out of the queue and turn it back into a key value vector */ char *queue_msg = pop_from_queue(); kvv_from_msg_queue = buf2kvvec(queue_msg, strlen(queue_msg), KEYVAL_SEP, PAIR_SEP, KVVEC_COPY); /* print out the keys and values of our kvvec we just got from the message queue */ printf("\nprinting keys and values of kvv_from_msg_queue\n"); kvvec_foreach(kvv_from_msg_queue, NULL, walker); /* we MUST remember to free the message queue! */ ndo2db_queue_free(); /* house-keeping */ free(kvv_buf->buf); free(kvv_buf); kvvec_destroy(kvv, KVVEC_FREE_ALL); kvvec_destroy(kvv_from_msg_queue, KVVEC_FREE_ALL); return 0; } |
Here we’re just including our necessary header files:
|
1 2 |
#include "lib/libnagios.h" #include "queue.h" |
This is a function that we use to “walk” through the key-value vector and perform some meaningful operation against each pair we find. *kv will be the key-value pair, and *arg is an additional argument you can pass to the kvvec_foreach function (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L136-L146).
|
1 2 3 4 5 6 7 8 |
/* function for walking a kvv and performing this function on each key/value */ static int walker(struct key_value *kv, void *arg) { /* all we care about is printing the values to the screen */ printf("walking kvv, key: %s, value: %s\n", kv->key, kv->value); return 0; } |
Now we’re going to start our application and define a few parameters to be used later. KEYVAL_SEP will be the separating character used to determine key from values. PAIR_SEP will be the separating character to keep key-value pairs separate from each other. OVERALLOC will be used to determine how much extra space is allocated when we create our vector. Then we go ahead and set up a basic char * buffer with our key-value data and set keyval_len equal to how many [key-values] we have there.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
int main(void) { /* these will be used for distinguishing key/value pairs and sets */ char KEYVAL_SEP = '='; char PAIR_SEP = ';'; int OVERALLOC = 2; /* some keys and values */ const char *keyval[] = { "key1=value1", "foo=bar", "nagios=rules" }; int keyval_len = 3; |
Now we’re getting to the nitty gritty. It’s time to declare some vectors and a buffer. We’ll initialize one for use immediately, but save the others for later. We’re using kvvec and kvvec_buf structures to store vectors and buffers (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L25-L46) and initializing an empty kvvec with kvvec_create (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L70-L76).
|
1 2 3 4 |
/* setup some key value vectors and initialize 1, save the other 2 for later */ struct kvvec *kvv, *kvv_from_msg_queue; struct kvvec_buf *kvv_buf; kvv = kvvec_create(keyval_len); |
Let’s cycle through our *keyval array and inject our pairs into our freshly initialized kvvec using kvvec_addkv (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L115-L134).
|
1 2 3 4 5 6 7 8 9 10 11 |
/* add our keys and values to the vector */ int i; for (i = 0; i < keyval_len; i++) { char *arg = strdup(keyval[i]); char *eq = strchr(arg, '='); if (eq) *eq++ = 0; kvvec_addkv(kvv, strdup(arg), strdup(eq)); free(arg); /* eq is destroyed here as well */ } |
Remember the function we defined that was going to “walk” through the key-value vector and perform a meaningful operation against each key-value pair? We’re going to call it now, and as it walks through each key-value, it will print both elements.
|
1 2 3 |
/* lets print the keys and values */ printf("\nprinting keys and values of kvv\n"); kvvec_foreach(kvv, NULL, walker); |
Now we’re going to sort the vector using kvvec_sort (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L108-L113), which will sort the pairs alphabetically by key. Once we’ve done that, we’re going to call the walker function again which will print the key-value pairs in their new order.
|
1 2 3 4 |
/* now lets sort it and print it one more time */ printf("\nsorting then printing keys and values of kvv\n"); kvvec_sort(kvv); kvvec_foreach(kvv, NULL, walker); |
The magic and beauty of libnagios’s kvvec function really shines through with the buffer/vector conversion functions. We’re going to use kvvec2buf (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L163-L178) to convert our vector into a single buffer using the parameters we set up when we began our application.
|
1 2 |
/* now lets add kvv to kvv_buf so that we can put it in the kernel msg queue */ kvv_buf = kvvec2buf(kvv, KEYVAL_SEP, PAIR_SEP, OVERALLOC); |
Now, we finally get to the borrowed NDOUtils code. This next block is responsible for initializing a message queue utilizing ndo2db_queue_init (https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h#L35-L36). It takes only one argument: an integer ID to be used as identification for the message queue. We’re passing our process id.
Next we’re creating a struct ndo2db_queue_msg (https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h#L30-L33) variable and copying our key-value buffer.
Finally, we’ll send our message to the queue using ndo2db_queue_send (https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h#L41-L42). This function takes two arguments: an ndo2db_queue_msg and a size_t the size of the message to send.
|
1 2 3 4 5 6 7 |
/* set up a queue using our borrowed ndo2db queue code */ ndo2db_queue_init(getpid()); /* initialize a message with our kvv_buf data and send it to the queue */ struct ndo2db_queue_msg msg; strcpy(msg.text, kvv_buf->buf); ndo2db_queue_send(&msg, kvv_buf->buflen); |
Our example here is very basic. Ideally, it is at this point in the application that something would happen to this buffer. It would be picked up by some child process or thread or a different process entirely and processed there. In order to maintain some brevity, we’ll simply be pulling it right back out of the queue! In order to do that, we’re using pop_from_queue (https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h#L44-L45). This simply returns a char pointer containing your message text (which happens to be the buffer text). Once we’ve done that, we’re going to use buf2kvvec (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L180-L191) to convert our message passed buffer back into a key-value vector.
After that conversion takes place, we’ll issue a call to the walker function yet again just so we can make sure that our keys and values are right where we expect them to be.
|
1 2 3 4 5 6 7 |
/* get our message out of the queue and turn it back into a key value vector */ char *queue_msg = pop_from_queue(); kvv_from_msg_queue = buf2kvvec(queue_msg, strlen(queue_msg), KEYVAL_SEP, PAIR_SEP, KVVEC_COPY); /* print out the keys and values of our kvvec we just got from the message queue */ printf("\nprinting keys and values of kvv_from_msg_queue\n"); kvvec_foreach(kvv_from_msg_queue, NULL, walker); |
Whew. How exciting! All that’s left now is to clean up the mess we made. In order to do that, we need to call ndo2db_queue_free (https://github.com/NagiosEnterprises/ndoutils/blob/master/include/queue.h#L38-L39) so that we release the queue’s system resources. After that, we’re freeing some buffers and then destroying the key-value vectors using kvvec_destroy (https://github.com/NagiosEnterprises/nagioscore/blob/master/lib/kvvec.h#L148-L154). We’re passing the KVVEC_FREE_ALL flag here, but you could decide to only KVVEC_FREE_KEYS or KVVEC_FREE_VALUES.
|
1 2 3 4 5 6 7 8 9 10 11 |
/* we MUST remember to free the message queue! */ ndo2db_queue_free(); /* house-keeping */ free(kvv_buf->buf); free(kvv_buf); kvvec_destroy(kvv, KVVEC_FREE_ALL); kvvec_destroy(kvv_from_msg_queue, KVVEC_FREE_ALL); return 0; } |
Just in case you missed it last time, we’ll need to have libnagios compiled and installed if we want any of this to work. If you haven’t already, you can do this with the following commands:
|
1 2 3 4 |
cd /path/to/nagioscore-master ./configure make lib/libnagios.a make install-lib |
|
1 |
gcc -L/usr/local/nagios/lib test2.c queue.c -lnagios -o test2 |
Now lets run our application and see the output!
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
./test2 printing keys and values of kvv walking kvv, key: key1, value: value1 walking kvv, key: foo, value: bar walking kvv, key: nagios, value: rules sorting then printing keys and values of kvv walking kvv, key: foo, value: bar walking kvv, key: key1, value: value1 walking kvv, key: nagios, value: rules printing keys and values of kvv_from_msg_queue walking kvv, key: foo, value: bar walking kvv, key: key1, value: value1 walking kvv, key: nagios, value: rules |
Neat! Just as a side note, when you’ve pushed your messages onto the kernel message queue, you can actually watch the queue with the command ipcs -q.
I hope you’ve learned a little more about using the Nagios library to extend your own code.
