summaryrefslogtreecommitdiff
path: root/docs/docbook
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2003-03-19 20:08:30 +0000
committerJelmer Vernooij <jelmer@samba.org>2003-03-19 20:08:30 +0000
commitf23c19359fa9702fead4a5aecb0dc0eaaf9d0e5f (patch)
treec5ebc501f1215d645a19f3bbd0c307c4aeff54a8 /docs/docbook
parent84627f7995af6260e56f734a6d39ea1a85274c34 (diff)
downloadsamba-f23c19359fa9702fead4a5aecb0dc0eaaf9d0e5f.tar.gz
samba-f23c19359fa9702fead4a5aecb0dc0eaaf9d0e5f.tar.bz2
samba-f23c19359fa9702fead4a5aecb0dc0eaaf9d0e5f.zip
Add documentation on new modules system
(This used to be commit f0f454129a5a57e50391397f45d7cf4d58648d45)
Diffstat (limited to 'docs/docbook')
-rw-r--r--docs/docbook/devdoc/dev-doc.sgml2
-rw-r--r--docs/docbook/devdoc/modules.sgml147
-rw-r--r--docs/docbook/devdoc/rpc_plugin.sgml13
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_&lt;pipename&gt;.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>&lt;sambaroot&gt;/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>&lt;sambaroot&gt;/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>