From owner-p4-projects@FreeBSD.ORG Fri Sep 1 12:16:54 2006 Return-Path: X-Original-To: p4-projects@freebsd.org Delivered-To: p4-projects@freebsd.org Received: by hub.freebsd.org (Postfix, from userid 32767) id 04B1D16A4E1; Fri, 1 Sep 2006 12:16:54 +0000 (UTC) X-Original-To: perforce@freebsd.org Delivered-To: perforce@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id AA2F716A4DF for ; Fri, 1 Sep 2006 12:16:53 +0000 (UTC) (envelope-from piso@freebsd.org) Received: from repoman.freebsd.org (repoman.freebsd.org [216.136.204.115]) by mx1.FreeBSD.org (Postfix) with ESMTP id 56C4643D45 for ; Fri, 1 Sep 2006 12:16:53 +0000 (GMT) (envelope-from piso@freebsd.org) Received: from repoman.freebsd.org (localhost [127.0.0.1]) by repoman.freebsd.org (8.13.6/8.13.6) with ESMTP id k81CGraY044953 for ; Fri, 1 Sep 2006 12:16:53 GMT (envelope-from piso@freebsd.org) Received: (from perforce@localhost) by repoman.freebsd.org (8.13.6/8.13.4/Submit) id k81CGrdr044950 for perforce@freebsd.org; Fri, 1 Sep 2006 12:16:53 GMT (envelope-from piso@freebsd.org) Date: Fri, 1 Sep 2006 12:16:53 GMT Message-Id: <200609011216.k81CGrdr044950@repoman.freebsd.org> X-Authentication-Warning: repoman.freebsd.org: perforce set sender to piso@freebsd.org using -f From: Paolo Pisati To: Perforce Change Reviews Cc: Subject: PERFORCE change 105456 for review X-BeenThere: p4-projects@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: p4 projects tree changes List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 01 Sep 2006 12:16:54 -0000 http://perforce.freebsd.org/chv.cgi?CH=105456 Change 105456 by piso@piso_newluxor on 2006/09/01 12:16:12 Cosmetic. Affected files ... .. //depot/projects/soc2005/libalias/sys/netinet/libalias/libalias.3#5 edit Differences ... ==== //depot/projects/soc2005/libalias/sys/netinet/libalias/libalias.3#5 (text+ko) ==== @@ -1015,7 +1015,7 @@ In an alternate operating mode, the first choice of an aliasing port is also random and unrelated to the local port number. .Sh MODULAR ARCHITECTURE (AND Xr ipfw 4 Sh SUPPORT) -One of the latest improvements to +One of the latest improvements to .Nm libalias was to make its support for new protocols independent from the rest of the library, giving it the ability to load/unload at run-time support for new protocols. @@ -1025,7 +1025,7 @@ different ways, depending on whether they are compiled to work inside a kernel or as part of the userland library. .Ss LIBALIAS MODULES IN KERNEL LAND -When compiled to be parts of a kernel, +When compiled to be parts of a kernel, .Nm libalias modules are plain simple KLDs: .Pp @@ -1060,7 +1060,7 @@ many different address spaces, etc etc), we had to change a bit how to handle modules loading/tracking/unloading in userland. .Pp -While compiled for a userland +While compiled for a userland .Nm libalias all the modules are plain libraries: .Pp @@ -1119,7 +1119,7 @@ patched to handle SIGHUP signal and call LibAliasRefreshModules() whenever it receives that signal (see below for details). .Pp -If you have correctly installed +If you have correctly installed .Nm libalias in /etc you should find a file called libalias.conf with the following contents (or @@ -1142,16 +1142,16 @@ .Pa /usr/lib/libalias_smedia.so .El .Pp -this file contains the paths to the modules that -.Nm libalias +this file contains the paths to the modules that +.Nm libalias will load. To load/unload a new module just add its path to libalias.conf and send a SIGHUP signal to the application that needs the new module: .Pp .Dl "kill -HUP .Ss MODULAR ARCHITECURE: HOW IT WORKS -The modular architecture of -.Nm libalias +The modular architecture of +.Nm libalias work (almost) the same when it's running inside kernel or in userland. From alias_mod.c: .Bd -literal @@ -1166,17 +1166,17 @@ struct proto_handler { /* handler priority */ - int pri; + int pri; /* flow direction */ - int16_t dir; - /* working protocol */ - int16_t proto; + int16_t dir; + /* working protocol */ + int16_t proto; /* fingerprint * function */ - int (*fingerprint)(struct libalias *la, + int (*fingerprint)(struct libalias *la, struct ip *pip, struct alias_data *ah); /* aliasing * function */ - int (*protohandler)(struct libalias *la, - struct ip *pip, struct alias_data *ah); + int (*protohandler)(struct libalias *la, + struct ip *pip, struct alias_data *ah); struct proto_handler *next; }; .Ed @@ -1188,7 +1188,7 @@ .Pp dir is the direction of packets: ingoing or outgoing. .Pp -proto says at which protocol this packet belongs: IP, TCP or UDP +proto says at which protocol this packet belongs: IP, TCP or UDP .Pp fingerprint points to the fingerprint function while protohandler points to the protocol handler function. @@ -1198,11 +1198,11 @@ module can handle. .Pp The protocol handler function is the function that actually manipulates -the packet to make -.Nm libalias +the packet to make +.Nm libalias correctly nat it. .Pp -When a packet enters +When a packet enters .Nm libalias , if it meets a module hook, handler_chain is searched to see if there's an handler that match @@ -1214,13 +1214,13 @@ of this handler and return, else it skip to the fingerprint function of the next eligible module, till the end of handler_chain .Pp -Inside -.Nm libalias +Inside +.Nm libalias the module hook looks like this: .Bd -literal struct alias_data ad = { - lnk, - &original_address, + lnk, + &original_address, &alias_address, &alias_port, &ud->uh_sport, /* original source port */ @@ -1230,10 +1230,8 @@ ... - /* walk out chain */ + /* walk out chain */ err = find_handler(IN, UDP, la, pip, &ad); - if (err == EHDNOF) - ; .Ed all data useful to a module are gathered together in a alias_data structure, then find_handler is called. @@ -1246,25 +1244,25 @@ .Pp la: pointer to this instance of libalias .Pp -pip: pointer to a struct ip +pip: pointer to a struct ip .Pp ad: pointer to struct alias_data (see above) .Pp in this case, find_handler will search only for modules registered for supporting INcoming UDP packets. .Pp -As i said earlier, +As i said earlier, .Nm libalias in userland is a bit different, cause we have to take care of module handling too (avoiding duplicate load of module, avoiding module with same name, etc etc) so dll_chain was introduced. .Pp -dll_chain contains a list of all userland +dll_chain contains a list of all userland .Nm libalias modules loaded. .Pp -When an application calls LibAliasRefreshModules(), +When an application calls LibAliasRefreshModules(), .Nm libalias first unload all the loaded modules, then reload all the modules listed in /etc/libalias.conf: for every module loaded, a new entry to dll_chain @@ -1272,28 +1270,28 @@ .Pp dll_chain is composed of struct dll entries: .Bd -literal -struct dll { +struct dll { /* name of module */ - char name[DLL_LEN]; - /* + char name[DLL_LEN]; + /* * ptr to shared obj obtained through * dlopen() - use this ptr to get access - * to any symbols from a loaded module - * via dlsym() + * to any symbols from a loaded module + * via dlsym() */ - void *handle; + void *handle; struct dll *next; -}; +}; .Ed name is the name of the module -.Pp +.Pp handle is a pointer to the module obtained through dlopen() .Pp Whenever a module is loaded in userland, an entry is added to dll_chain, than every protocol handler present in that module is resolved and registered in handler_chain. .Ss HOW TO WRITE A MODULE FOR LIBALIAS -There's a module (called alias_dummy.[ch]) in +There's a module (called alias_dummy.[ch]) in .Nm libalias that can be used as a skeleton for future work, here we analyse some parts of that module. @@ -1322,7 +1320,7 @@ { int error; - switch (type) { + switch (type) { case MOD_LOAD: error = 0; attach_handlers(handlers); @@ -1346,7 +1344,7 @@ #ifdef _KERNEL static #endif -int +int fingerprint(struct libalias *la, struct ip *pip, struct alias_data *ah) { ... @@ -1355,8 +1353,8 @@ #ifdef _KERNEL static #endif -int -protohandler(struct libalias *la, struct ip *pip, +int +protohandler(struct libalias *la, struct ip *pip, struct alias_data *ah) { ... @@ -1364,7 +1362,7 @@ .Ed and they must accept exactly these input parameters. .Ss PATCHING AN APPLICATION FOR USERLAND LIBALIAS MODULES -If you have any application that uses +If you have any application that uses .Nm libalias and you want to add it support for modules, then follow this simple 5 steps @@ -1373,7 +1371,6 @@ .An -split .An 1) first, figure out which file is the main file of your program .An (let's call it main.c) - .An 2) add this to the header section of main,c, if not already .An present: .Pp @@ -1390,7 +1387,7 @@ .Pp .An 5) and place this function somewhere in main.c: .Pp -.An static void +.An static void .An signal_handler(int sig) { .Pp .An LibAliasRefreshModules(); @@ -1408,7 +1405,7 @@ .Ed .Ss LOGGING SUPPORT IN KERNEL LAND .Pp -While working as kld, +While working as kld, .Nm libalias now have log support that happens on a buffer allocated inside struct libalias(from alias_local.h): @@ -1416,15 +1413,15 @@ struct libalias { ... - /* log descriptor */ + /* log descriptor */ #ifdef KERNEL_LOG - char *logDesc; /* - * ptr to an auto-malloced + char *logDesc; /* + * ptr to an auto-malloced * memory buffer when libalias * works as kld */ -#else - FILE *logDesc; /* +#else + FILE *logDesc; /* * ptr to /var/log/alias.log * when libalias runs as a * userland lib @@ -1434,7 +1431,7 @@ ... } .Ed -so all the applications using +so all the applications using .Nm libalias , will be able to handle their own logs, if they want, accessing logDesc.