NG_GREP

Section: Devices and Network Interfaces (4)
Index Return to Main Contents

BSD mandoc
 

NAME

ng_grep - grep-like content filter netgraph node type  

SYNOPSIS

In ng_grep.h In my_pattern.h  

DESCRIPTION

The grep node type accomplishes filtration of packets travelling through a Netgraph network on the basis of payload contents (now only tcp is supported) Each node has 3 named hooks, in, meet and miss. All packets receiving on in hook are partially decoded and their payload is compared with set of patterns stored in the nodes's memory. When payload matches a pattern, searching stops and packet goes to meet hook. Otherwise ( packet is not tcp, is not ip, has no payload or payload not match any of patterns ) packet goes to miss hook.  

HOOKS

 

CONTROL MESSAGES

This node type supports the generic control messages, plus the following:

NGM_GREP_GETSTATS (getstats )
struct ng_grep_stats_out {
        u_long  in_c;
        u_long  bad_c;
        u_long  meet_c;
        u_long  miss_c;
}
Returns counts for in, bad (incoming from meet and miss hooks), out to miss and out to meet pkts.
NGM_GREP_GETCLEARSTATS (getclearstats )
Is similar to getstats, bit clears all stats after show.
NGM_GREP_CLEARSTATS (clearstats )
Simply clears stats counters.
NGM_GREP_FLUSH (flush )
Clears all pattenrs from node's memory ( a little quicker then subsequential del's ). Requares no paramemeters.
NGM_GREP_ADD (add )
Adds a given pattern to internal checklist of the node. If the same pattern already exists, do nothing, but it's no error.
NGM_GREP_DEL (del )
Deletes a given pattern from an internal checklist of the node. If such pattern not exists, an error is displayed.
NGM_GREP_CHECK (check )
Checks an existense of a given pattern in the node's memory. If the given pattern exists, the function returns err=0, and err=2 if not.
parameters for add, del, check
This three functions assepts the same parameter set.
struct ng_grep_add_in {
        u_char  flag_i_c;
        u_char  flag_rex;
        u_char  flag_sub;
        u_char   raw[NG_GREP_MAX_STR_PAR_LEN];
        u_char   url[NG_GREP_MAX_STR_PAR_LEN];
};
but only one of strings must be non-zero. More strictly, if url has non-zero length, the content of raw is ignored. The chose of raw or url determinates the method of comparision incoming data with this pattern.

If pattern was defined via raw string, it will be compared with tcp payload using strncasecmp function.

If patern was defined via url string, the process will be a little more complicated. At first, the string must contain strictly one constraction '://' All symbols from the begin of the string up to this construction cosidered as protocol name. Only http is supportd now, any other symbols combibations will produce an error (err=22). The second part of the incoming string, from '://' up to first '/' or end of string if '/' is absent, is considered as hostname and compared with 'Host:' field of travelling packet. And the third part, after '/' up to end of string, is considered as pathname and is compared with the parameter of POST/GET command in travelling packet.

The flag i_c (ignore case) means to ignore case when strcmp. The flag sum means do not consider any symbols after strlen(pattern), i. e. all strings beginning from patterm will be considered as meet condition. if sub=0, the comparison will be meet only if pattern and testing string are absolutly indentical. raw paterns are compares as sum=1 in any case. The host part of url patterm is capmpred as i_c=1 sum=0 in any case.

The answer consists of

struct ng_grep_add_out {
        u_char  rc;
        u_char  flag_i_c;
        u_char  flag_rex;
        u_char  flag_sub;
        u_long  meet_c;
        u_char  raw[NG_GREP_MAX_STR_PAR_LEN];
        u_char  url[NG_GREP_MAX_STR_PAR_LEN];
        u_char  host[NG_GREP_MAX_STR_PAR_LEN];
        u_char  path[NG_GREP_MAX_STR_PAR_LEN];
        u_char  prot[8];
};
 

SHUTDOWN

 

EXAMPLES

Assume, we want to filter requests to http://www.sample.ru/sample and all nested url's (http://www.sample.ru/sanple*)

At first we must load kernel module and create in hook to ipfw (for example)

# kldload ./ng_grep.ko
# ngctl mkpeer ipfw: grep 80 in
# ngctl name ipfw:80 grep 

Now let's create a path for traffic, that not meet out condition:

# ngctl connect ipfw: grep: 81 miss

After it we must create a rule(s) in ipfw, firecting traffic to 80 hook of ipfw:

# ipfw add 100 netgraph 80 tcp from any to any dst-port 80 via em1 out

Now all tcp packets, addressing to 80 port af any ip address, will be directed to 80 hook of ipfw:, then to in hook of grep:, and grep forwards all of them to hook miss.

# ngctl msg grep: check {i_c=1 sub=1 url=\"http://www.sample.ru/sample\"}
Rec'd response "check" (4) from "[30e0]:":
Args:   { err=2 i_c=1 sub=1 url="http://www.sample.ru/sample" }

We can see, that such pattern isn't in grep patterns set (err=2) Let's add it and check:

# ngctl msg grep: add {i_c=1 sub=1 url=\"http://www.sample.ru/sample\"}
Rec'd response "add" (2) from "[30e0]:":
Args:   { i_c=1 url="http://www.sample.ru/sample" host="www.sample.ru" path="/sample" }
# ngctl msg grep: check {i_c=1 sub=1 url=\"http://www.sample.ru/sample\"}
Rec'd response "check" (4) from "[30e0]:":
Args:   { i_c=1 sub=1 url="http://www.sample.ru/sample" host="www.sample.ru" path="/sample" }

Ok, this pattern is in set, and now all requests to http://www.sample.ru/sample will be directed to hook meet. Btw, this hook is not connected now, so such packets will be dropped. The condition is meet for 'http://www.sample.ru/sample' and any nested path, 'http://www.sample.ru/sample/sam2' for example. If you don't need nested path to satisfy condition, do not use 'sub=1' option. Ahtung -- the patterns with the same url but different sets of flags (i_c, sub) are the different patterns, independent from each other, and must be separately added/deletet/checked.  

SEE ALSO

 

HISTORY

The implementation is in progress, begins in FreeBSD 10.0

ALPHA-04 (2014/04/30 )
sub and i_c options added.

getstats, clearstats, getclearstats commands added.

ALPHA-03 (2014/04/16 )
url pattern type added
ALPHA-02 (2014/04/15 )
can filter raw data
ALPHA-01 (2014/04/10 )
Does not do any real work, only demonstrates opportunities.
 

AUTHORS

An Andy Trushin Aq andy@ahome.ru  

BUGS

I don't know yet... It's alpha ;-)


 

Index

NAME
SYNOPSIS
DESCRIPTION
HOOKS
CONTROL MESSAGES
SHUTDOWN
EXAMPLES
SEE ALSO
HISTORY
AUTHORS
BUGS

This document was created by man2html, using the manual pages.
Time: 19:59:09 GMT, May 01, 2014