Date: Thu, 31 Aug 2006 18:02:46 GMT From: Paolo Pisati <piso@FreeBSD.org> To: Perforce Change Reviews <perforce@freebsd.org> Subject: PERFORCE change 105410 for review Message-ID: <200608311802.k7VI2keP074642@repoman.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://perforce.freebsd.org/chv.cgi?CH=105410 Change 105410 by piso@piso_newluxor on 2006/08/31 18:02:14 First round of mdoc cleanup. Affected files ... .. //depot/projects/soc2005/libalias/sys/netinet/libalias/libalias.3#4 edit Differences ... ==== //depot/projects/soc2005/libalias/sys/netinet/libalias/libalias.3#4 (text+ko) ==== @@ -894,8 +894,8 @@ .An Ruslan Ermilov Aq ru@FreeBSD.org added support for PPTP and LSNAT as well as general hacking. .An Paolo Pisati Aq piso@FreeBSD.org -made the library modular, moving support for all -the protocols (except for IP, TCP and UDP) to external modules. +made the library modular, moving support for all +protocols (except for IP, TCP and UDP) to external modules. .Sh ACKNOWLEDGMENTS Listed below, in approximate chronological order, are individuals who have provided valuable comments and/or debugging assistance. @@ -1014,105 +1014,148 @@ a unique aliasing link can be established. 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 ipfw support) -One of the latest improvement of libalias was to make its support +.Sh MODULAR ARCHITECTURE (AND Xr ipfw 4 Sh SUPPORT) +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 runtime support for new protocols. -To achieve this feature, all the code for protocols handling was moved +the ability to load/unload at run-time support for new protocols. +To achieve this feature, all the code for protocol handling was moved to a series of modules outside of the main library. -These modules are compiled from the same source base but works in a -different ways, according if they are compiled to work inside a kernel -or as part of a user land library. -.Ss Libalias modules in kernel land -When compiled to be part of a kernel, libalias modules are plain -simple kld, installed as default with all the other kernel modules: +These modules are compiled from the same sources but works in a +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, +.Nm libalias +modules are plain simple KLDs: .Pp -.Bd -ragged -offset indent -.An -split -.An /boot/kernel/alias_cuseeme.ko -.An /boot/kernel/alias_dummy.ko -.An /boot/kernel/alias_ftp.ko -.An /boot/kernel/alias_irc.ko -.An /boot/kernel/alias_nbt.ko -.An /boot/kernel/alias_pptp.ko -.An /boot/kernel/alias_skinny.ko -.An /boot/kernel/alias_smedia.ko -.Ed +.Bl -item -compact +.It +.Pa /boot/kernel/alias_cuseeme.ko +.It +.Pa /boot/kernel/alias_dummy.ko +.It +.Pa /boot/kernel/alias_ftp.ko +.It +.Pa /boot/kernel/alias_irc.ko +.It +.Pa /boot/kernel/alias_nbt.ko +.It +.Pa /boot/kernel/alias_pptp.ko +.It +.Pa /boot/kernel/alias_skinny.ko +.It +.Pa /boot/kernel/alias_smedia.ko +.El .Pp -To load a new protocol just kldload it: +To add support for new protocol just kldload its module, for example: .Pp -kldload alias_ftp # add support for ftp protocol to kernel libalias +.Dl "kldload alias_ftp .Pp and when you don't need it anymore, you can unload it: .Pp -kldunload alias_ftp -.Pp -.Ss Libalias modules in user land -Due to the differences between kernel and user land (no kld mechanism, +.Dl "kldunload alias_ftp +.Ss LIBALIAS MODULES IN USERLAND +Due to the differences between kernel and userland (no kld mechanism, many different address spaces, etc etc), we had to change a bit how to -handle modules loading/tracking/unloading in user land. +handle modules loading/tracking/unloading in userland. .Pp -While compiled for a user land libalias, all the modules are installed -in /usr/lib: +While compiled for a userland +.Nm libalias +all the modules are plain libraries: .Pp -.Bd -ragged -offset indent -.An -split -.An /usr/lib/libalias_cuseeme.a -.An /usr/lib/libalias_cuseeme.so -> /lib/libalias_cuseeme.so.4 -.An /usr/lib/libalias_cuseeme_p.a -.An /usr/lib/libalias_dummy.a -.An /usr/lib/libalias_dummy.so -> /lib/libalias_dummy.so.4 -.An /usr/lib/libalias_dummy_p.a -.An /usr/lib/libalias_ftp.a -.An /usr/lib/libalias_ftp.so -> /lib/libalias_ftp.so.4 -.An /usr/lib/libalias_ftp_p.a -.An /usr/lib/libalias_irc.a -.An /usr/lib/libalias_irc.so -> /lib/libalias_irc.so.4 -.An /usr/lib/libalias_irc_p.a -.An /usr/lib/libalias_nbt.a -.An /usr/lib/libalias_nbt.so -> /lib/libalias_nbt.so.4 -.An /usr/lib/libalias_nbt_p.a -.An /usr/lib/libalias_pptp.a -.An /usr/lib/libalias_pptp.so -> /lib/libalias_pptp.so.4 -.An /usr/lib/libalias_pptp_p.a -.An /usr/lib/libalias_skinny.a -.An /usr/lib/libalias_skinny.so -> /lib/libalias_skinny.so.4 -.An /usr/lib/libalias_skinny_p.a -.An /usr/lib/libalias_smedia.a -.An /usr/lib/libalias_smedia.so -> /lib/libalias_smedia.so.4 -.An /usr/lib/libalias_smedia_p.a -.Ed +.Bl -item -compact +.It +.Pa /usr/lib/libalias_cuseeme.a +.It +.Pa /usr/lib/libalias_cuseeme.so -> /lib/libalias_cuseeme.so.4 +.It +.Pa /usr/lib/libalias_cuseeme_p.a +.It +.Pa /usr/lib/libalias_dummy.a +.It +.Pa /usr/lib/libalias_dummy.so -> /lib/libalias_dummy.so.4 +.It +.Pa /usr/lib/libalias_dummy_p.a +.It +.Pa /usr/lib/libalias_ftp.a +.It +.Pa /usr/lib/libalias_ftp.so -> /lib/libalias_ftp.so.4 +.It +.Pa /usr/lib/libalias_ftp_p.a +.It +.Pa /usr/lib/libalias_irc.a +.It +.Pa /usr/lib/libalias_irc.so -> /lib/libalias_irc.so.4 +.It +.Pa /usr/lib/libalias_irc_p.a +.It +.Pa /usr/lib/libalias_nbt.a +.It +.Pa /usr/lib/libalias_nbt.so -> /lib/libalias_nbt.so.4 +.It +.Pa /usr/lib/libalias_nbt_p.a +.It +.Pa /usr/lib/libalias_pptp.a +.It +.Pa /usr/lib/libalias_pptp.so -> /lib/libalias_pptp.so.4 +.It +.Pa /usr/lib/libalias_pptp_p.a +.It +.Pa /usr/lib/libalias_skinny.a +.It +.Pa /usr/lib/libalias_skinny.so -> /lib/libalias_skinny.so.4 +.It +.Pa /usr/lib/libalias_skinny_p.a +.It +.Pa /usr/lib/libalias_smedia.a +.It +.Pa /usr/lib/libalias_smedia.so -> /lib/libalias_smedia.so.4 +.It +.Pa /usr/lib/libalias_smedia_p.a +.El .Pp To take advantage of modules, an application must be patched to handle SIGHUP signal and call LibAliasRefreshModules() whenever it receives that signal (see below for details). .Pp -If you have correctly installed libalias, in /etc you should +If you have correctly installed +.Nm libalias +in /etc you should find a file called libalias.conf with the following contents (or similar): .Pp -.Bd -ragged -offset indent -.An -split -.An /usr/lib/libalias_cuseeme.so -.An /usr/lib/libalias_ftp.so -.An /usr/lib/libalias_irc.so -.An /usr/lib/libalias_nbt.so -.An /usr/lib/libalias_pptp.so -.An /usr/lib/libalias_skinny.so -.An /usr/lib/libalias_smedia.so -.Ed +.Bl -item -compact +.It +.Pa /usr/lib/libalias_cuseeme.so +.It +.Pa /usr/lib/libalias_ftp.so +.It +.Pa /usr/lib/libalias_irc.so +.It +.Pa /usr/lib/libalias_nbt.so +.It +.Pa /usr/lib/libalias_pptp.so +.It +.Pa /usr/lib/libalias_skinny.so +.It +.Pa /usr/lib/libalias_smedia.so +.El .Pp -this file contains the paths to the modules that libalias will load. +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 -kill -HUP <process pid> -.Pp -.Sh Modular architecture: how it works -The modular architecture of libalias work (almost) the same when it's -running inside kernel or in user land. From alias_mod.c: +.Dl "kill -HUP <process pid> +.Ss MODULAR ARCHITECURE: HOW IT WORKS +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 -/* protocol and user land module handlers chains */ +/* protocol and userland module handlers chains */ struct chain handler_chain, dll_chain; handler_chain keep tracks of all the protocol handlers loaded, while @@ -1155,10 +1198,14 @@ module can handle. .Pp The protocol handler function is the function that actually manipulates -the packet to make libalias correctly nat it. +the packet to make +.Nm libalias +correctly nat it. .Pp -When a packet enters libalias, if it meets a module hook, -libalias scan handler_chain to see if there's an handler that match +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 this type of packet (it checks protocol and direction of packet), then if more then one handler is found, it starts with the module with a lower priority number: it calls fingerprints and read the result. @@ -1167,7 +1214,9 @@ 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 libalias, the module hook looks like this: +Inside +.Nm libalias +the module hook looks like this: .Bd -literal struct alias_data ad = { lnk, @@ -1204,15 +1253,20 @@ in this case, find_handler will search only for modules registered for supporting INcoming UDP packets. .Pp -As i said earlier, libalias in userland is a bit different, cause we +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 user land libalias modules loaded. +dll_chain contains a list of all userland +.Nm libalias +modules loaded. .Pp -When an application calls LibAliasRefreshModules(), libalias first unload -all the loaded modules, then reload all the modules listed in +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 is added. .Pp @@ -1235,12 +1289,13 @@ .Pp handle is a pointer to the module obtained through dlopen() .Pp -Whenever a module is loaded in user land, an entry is added to +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 libalias that can be -used as a skeleton for future work, here we analyse some parts of that +.Ss HOW TO WRITE A MODULE FOR LIBALIAS +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. From alias_dummy.c: .Bd -literal @@ -1308,9 +1363,11 @@ } .Ed and they must accept exactly these input parameters. -.Ss Patching an application for user land libalias modules -If you have any application that uses libalias and you want to add it -support for libalias modules, then follow this simple 5 steps +.Ss PATCHING AN APPLICATION FOR USERLAND LIBALIAS MODULES +If you have any application that uses +.Nm libalias +and you want to add it +support for modules, then follow this simple 5 steps procedure. .Bd -ragged -offset indent .An -split @@ -1349,10 +1406,11 @@ .Pp .An recompile and you are done. .Ed +.Ss LOGGING SUPPORT IN KERNEL LAND .Pp -.Ss Logging support in kernel land -.Pp -While working as kld, libalias now have log support that +While working as kld, +.Nm libalias +now have log support that happens on a buffer allocated inside struct libalias(from alias_local.h): .Bd -literal struct libalias { @@ -1376,7 +1434,9 @@ ... } .Ed -so all the applications using libalias, will be able to handle their +so all the applications using +.Nm libalias +, will be able to handle their own logs, if they want, accessing logDesc. Moreover, every change to log buffer is automatically added to syslog with facilities security and info.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200608311802.k7VI2keP074642>