diff options
| -rw-r--r-- | docs/docbook/devdoc/dev-doc.sgml | 2 | ||||
| -rw-r--r-- | docs/docbook/devdoc/modules.sgml | 147 | ||||
| -rw-r--r-- | docs/docbook/devdoc/rpc_plugin.sgml | 13 |
3 files changed, 159 insertions, 3 deletions
diff --git a/docs/docbook/devdoc/dev-doc.sgml b/docs/docbook/devdoc/dev-doc.sgml index b5c934b1c8..f10fe72414 100644 --- a/docs/docbook/devdoc/dev-doc.sgml +++ b/docs/docbook/devdoc/dev-doc.sgml @@ -13,6 +13,7 @@ <!ENTITY sam SYSTEM "sam.sgml"> <!ENTITY encryption SYSTEM "encryption.sgml"> <!ENTITY rpc-plugin SYSTEM "rpc_plugin.sgml"> +<!ENTITY modules SYSTEM "modules.sgml"> ]> <book id="Samba-Developers-Guide"> @@ -67,6 +68,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u &wins; &sam; &encryption; +&modules; &rpc-plugin; </book> diff --git a/docs/docbook/devdoc/modules.sgml b/docs/docbook/devdoc/modules.sgml new file mode 100644 index 0000000000..098044ddfe --- /dev/null +++ b/docs/docbook/devdoc/modules.sgml @@ -0,0 +1,147 @@ +<chapter id="modules"> +<chapterinfo> + <author> + <firstname>Jelmer</firstname><surname>Vernooij</surname> + <affiliation> + <orgname>Samba Team</orgname> + <address><email>jelmer@samba.org</email></address> + </affiliation> + </author> + <pubdate> 19 March 2003 </pubdate> +</chapterinfo> + +<title>Modules</title> + +<sect1> +<title>Advantages</title> + +<para> +The new modules system has the following advantages: +</para> + +<simplelist> +<member>Transparent loading of static and shared modules (no need +for a subsystem to know about modules)</member> +<member>Simple selection between shared and static modules at configure time</member> +<member>"preload modules" option for increasing performance for stable modules</member> +<member>No nasty #define stuff anymore</member> +<member>All backends are available as plugin now (including pdb_ldap and pdb_tdb)</member> +</simplelist> +</sect1> + +<sect1> +<title>Loading modules</title> + +<para> +Some subsystems in samba use different backends. These backends can be +either statically linked in to samba or available as a plugin. A subsystem +should have a function that allows a module to register itself. For example, +the passdb subsystem has: +</para> + +<para><programlisting> +BOOL smb_register_passdb(const char *name, pdb_init_function init, int version); +</programlisting></para> + +<para> +This function will be called by the initialisation function of the module to +register itself. +</para> + +<sect2> +<title>Static modules</title> + +<para> +The modules system compiles a list of initialisation functions for the +static modules of each subsystem. This is a define. For example, +it is here currently (from <filename>include/config.h</filename>): +</para> + +<para><programlisting> +/* Static init functions */ +#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();} +</programlisting></para> + +<para> +These functions should be called before the subsystem is used. That can be +done either from the executable that will be using the subsystem ( +static_init_rpc is called from the main() function of smbd), or +from the subsystem itself when it's first used (like passdb's +lazy_initialise_passdb does). +</para> + +</sect2> + +<sect2> +<title>Shared modules</title> + +<para> +If a subsystem needs a certain backend, it should check if it has +already been registered. If the backend hasn't been registered already, +the subsystem should call smb_probe_module(char *subsystem, char *backend). +This function tries to load the correct module from a certain path +($LIBDIR/subsystem/backend.so). If the first character in 'backend' +is a slash, smb_probe_module() tries to load the module from the +absolute path specified in 'backend'. +</para> + +<para>After smb_probe_module() has been executed, the subsystem +should check again if the module has been registered. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Writing modules</title> + +<para> +Each module has an initialisation function. For modules that are +included with samba this name is '<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>_init'. For external modules (that will never be built-in, but only available as a module) this name is always 'module_init'. +The prototype for this function is: +</para> + +<para><programlisting> +int module_init(void); +</programlisting></para> + +<para>This function should call one or more +registration The function should return non-zero on success and zero on +failure.</para> + +<para>For example, pdb_ldap_init() contains: </para> + +<para><programlisting> +int pdb_ldap_init(void) +{ + smb_register_passdb("ldapsam", pdb_init_ldapsam, PASSDB_INTERFACE_VERSION); + smb_register_passdb("ldapsam_nua", pdb_init_ldapsam_nua, PASSDB_INTERFACE_VERSION); + return TRUE; +} +</programlisting></para> + +<sect2> +<title>Static/Shared selection in configure.in</title> + +<para> +Some macros in configure.in generate the various defines and substs that +are necessary for the system to work correct. All modules that should +be built by default have to be added to the variable 'default_modules'. +For example, if ldap is found, pdb_ldap is added to this variable. +</para> + +<para> +On the bottom of configure.in, SMB_MODULE() should be called +for each module and SMB_SUBSYSTEM() for each subsystem. +</para> + +<para>Syntax:</para> + +<para><programlisting> +SMB_MODULE($MODULE_<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>, <replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>, <replaceable>object files</replaceable>, <replaceable>plugin name</replaceable>, <replaceable>subsystem name</replaceable>) +SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>) +</programlisting></para> + +</sect2> +</sect1> +</chapter> diff --git a/docs/docbook/devdoc/rpc_plugin.sgml b/docs/docbook/devdoc/rpc_plugin.sgml index 21582a011d..c83742a247 100644 --- a/docs/docbook/devdoc/rpc_plugin.sgml +++ b/docs/docbook/devdoc/rpc_plugin.sgml @@ -7,6 +7,13 @@ <address><email>aliguor@us.ibm.com</email></address> </affiliation> </author> + <author> + <firstname>Jelmer</firstname><surname>Vernooij</surname> + <affiliation> + <orgname>Samba Team</orgname> + <address><email>jelmer@samba.org</email></address> + </affiliation> + </author> <pubdate>January 2003</pubdate> </chapterinfo> @@ -33,12 +40,12 @@ When an RPC call is sent to smbd, smbd tries to load a shared library by the name <filename>librpc_<pipename>.so</filename> to handle the call if it doesn't know how to handle the call internally. For instance, LSA calls are handled by <filename>librpc_lsass.so</filename>.. -These shared libraries should be located in the <filename><sambaroot>/lib/rpc</filename>. smbd then attempts to call the rpc_pipe_init function within -the shared library. +These shared libraries should be located in the <filename><sambaroot>/lib/rpc</filename>. smbd then attempts to call the init_module function within +the shared library. Check the chapter on modules for more information. </para> <para> -In the rpc_pipe_init function, the library should call +In the init_module function, the library should call rpc_pipe_register_commands(). This function takes the following arguments: </para> |