11. Functions to query libiptcThis section explains which functions allow you to query libiptc. We will use the header file of libiptc, file usr/local/include/libiptc/libiptc.h, containing prototypes of each function as a reference to develop our explanation. I have also included a brief description (when available) taken from Linux netfilter Hacking HOWTO within each function explanation. 11.1. iptc_initName: iptc_init Usage: Takes a snapshot of the rules. Prototype: iptc_handle_t iptc_init(const char *tablename) Description: This function must be called as initiator before any other function can be called. Parameters: tablename is the name of the table we need to query and/or modify; this could be filter, mangle, nat, etc. Returns: Pointer to a structure of type iptc_handle_t that must be used as main parameter for the rest of functions we will call from libiptc. iptc_init returns the pointer to the structure or NULL if it fails. If this happens you can invoke iptc_strerror to get information about the error. See below. Have a look at this section of code in file iptables-save.c for how to invoke this function:
11.2. iptc_strerrorName: iptc_strerror Usage: Translates error numbers into more human-readable form. Prototype: const char *iptc_strerror(int err) Description: This function returns a more meaningful explanation of a failure code in the iptc library. If a function fails, it will always set errno. This value can be passed to iptc_strerror() to yield an error message. Parameters: err is an integer indicating the error number. Returns: Char pointer containing the error description. 11.3. iptc_first_chainName: iptc_first_chain Usage: Iterator functions to run through the chains. Prototype: const char *iptc_first_chain(iptc_handle_t *handle) Description: This function returns the first chain name in the table. Parameters: Pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Char pointer to the name of the chain. 11.4. iptc_next_chainName: iptc_next_chain Usage: Iterator functions to run through the chains. Prototype: const char *iptc_next_chain(iptc_handle_t *handle) Description: This function returns the next chain name in the table; NULL means no more chains. Parameters: Pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Char pointer to the name of the chain. These two previous functions allow to us to iterate through the chains of the table getting the name of each of the chains; iptc_first_chain returns the name of the first chain of the table; iptc_next_chain returns the name of next chains and NULL when the function reaches the end. We can create Program #1 to exercise our understanding of these previous four functions:
Write this program and save it as p1.c in /usr/local/src. Now write this "bash" script to simplify the compiling process:
Save it as ipt-cc and do not forget to chmod 0700 ipt-cc. Now compile your p1 program:
And run it:
You will get:
These are the three built-in iptables chains. Now create some new chains using iptables and run your program again:
You will get:
Try to generate an error initializing tablename to myfilter instead of filter. When you compile and execute your program again, you will get:
iptables informs you that myfilter does not exist as a table. 11.5. iptc_is_chainName: iptc_is_chain Usage: Check if a chain exists. Prototype: int iptc_is_chain(const char *chain, const iptc_handle_t handle) Description: This function checks to see if the chain described in the parameter chain exists in the table. Parameters: chain is a char pointer containing the name of the chain we want to check to. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: integer value 1 (true) if the chain exists; integer value 0 (false) if the chain does not exist. 11.6. iptc_builtinName: iptc_builtin Usage: Is this a built-in chain? Prototype: int iptc_builtin(const char *chain, const iptc_handle_t handle) Description: This function is used to check if a given chain name is a built-in chain or not. Parameters: chain is a char pointer containing the name of the chain we want to check to. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Returns integer value 1 (true) if the given chain name is the name of a builtin chain; returns integer value 0 (false) is not. 11.7. iptc_first_ruleName: iptc_first_rule Usage: Get first rule in the given chain. Prototype: const struct ipt_entry *iptc_first_rule(const char *chain, iptc_handle_t *handle) Description: This function returns a pointer to the first rule in the given chain name; NULL for an empty chain. Parameters: chain is a char pointer containing the name of the chain we want to get the rules to. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Returns a pointer to an ipt_entry structure containing information about the first rule of the chain. See below for an explanation of this structure. 11.8. iptc_next_ruleName: iptc_next_rule Usage: Get the next rule in the given chain. Prototype: const struct ipt_entry *iptc_next_rule(const struct ipt_entry *prev, iptc_handle_t *handle) Description: This function returns a pointer to the next rule in the given chain name; NULL means the end of the chain. Parameters: prev is a pointer to a structure of type ipt_entry that must be obtained first by a previous call to the function iptc_first_rule. In order to get the second and subsequent rules you have to pass a pointer to the structure containing the information about the previous rule of the chain. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Returns a pointer to an ipt_entry structure containing information about the next rule of the chain. See below for an explanation of this structure. 11.9. iptc_get_targetName: iptc_get_target Usage: Get a pointer to the target name of this entry. Prototype: const char *iptc_get_target(const struct ipt_entry *e, iptc_handle_t *handle) Description: This function gets the target of the given rule. If it is an extended target, the name of that target is returned. If it is a jump to another chain, the name of that chain is returned. If it is a verdict (eg. DROP), that name is returned. If it has no target (an accounting-style rule), then the empty string is returned. Note that this function should be used instead of using the value of the verdict field of the ipt_entry structure directly, as it offers the above further interpretations of the standard verdict. Parameters: e is a pointer to a structure of type ipt_entry that must be obtained first by a previous call to the function iptc_first_rule or the function iptc_next_rule. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Returns a char pointer to the target name. See Description above for more information. Now it is time to explain the ipt_entry structure; these pieces of code are taken from iptables package sources:
An ipt_entry structure contains:
A simple way to work with all this information is to borrow some functions from iptables-save.c by Paul Russell and Harald Welte. Here is another sample program Program #2 written with a lot of help from Russell-Welte:
The function print_rule borrowed from iptables-save.c prints the information about a rule into a readable form using:
In main we iterate through each chain and for each one we iterate through each rule printing it. The arguments of print_rule are:
OK, compile and run program p2:
You will get:
Now modify the environment using iptables to add some rules:
Now if you run again p2 you will get:
We have now rules printed for INPUT and chain_1 chains. The numbers in the brackets at left are packet and byte counters respectively. 11.10. iptc_get_policyName: iptc_get_policy Usage: Get the policy of a given built-in chain. Prototype: const char *iptc_get_policy(const char *chain, struct ipt_counters *counter, iptc_handle_t *handle) Description: This function gets the policy of a built-in chain, and fills in the counters argument with the hit statistics on that policy. Parameters: You have to pass as arguments the name of the built-in chain you want to get the policy to, a pointer to an ipt_counters structure to be filled by the function and the iptc_handle_t structure identifying the table we are working to. The ipt_counters structure was explained in previous section; do not forget that iptc_handle_t must be obtained by a previous call to the function iptc_init. Returns: Returns a char pointer to the policy name. Using pieces of programs 1 and 2 we can write program #3:
OK, compile and run program p3:
You will get something like this:
11.11. iptc_read_counterName: iptc_read_counter Usage: Read counters of a rule in a chain. Prototype: struct ipt_counters *iptc_read_counter(const ipt_chainlabel chain, unsigned int rulenum, iptc_handle_t *handle); Description: This function read and returns packet and byte counters of the entry rule in chain chain positioned at rulenum. Counters are returned in a pointer to a type structure ipt_counters. Rule numbers start at 1 for the first rule. Parameters: chain is a char pointer to the name of the chain to be readed; rulenum is an integer value defined the position in the chain of rules of the rule which counters will be read. handle is a pointer to a structure of type iptc_handle_t that was obtained by a previous call to iptc_init. Returns: Returns a pointer to an ipt_counters structure containing the byte and packet counters readed. Linux HOWTO full list |
|
This document, LDP HOWTO-INDEX, is copyrighted (c) 1995 - 2002 by Tim Bynum, Guylhem Aznar, Joshua Drake and Greg Ferguson. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at http://www.gnu.org/copyleft/fdl.html. If you have questions, please contact the LDP.
Web Design Copyright © 1999-2003. Chrisranjana Software Solutions Pvt Ltd. syndicate rss feed |