docs-xml/Samba-Developers-Guide/modules.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="modules">
   4 <chapterinfo>
   5         <author>
   6                 <firstname>Jelmer</firstname><surname>Vernooij</surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address><email>jelmer@samba.org</email></address>
  10                 </affiliation>
  11         </author>
  12         <pubdate> 19 March 2003 </pubdate>
  13 </chapterinfo>
  14
  15 <title>Modules</title>
  16
  17 <sect1>
  18 <title>Advantages</title>
  19
  20 <para>
  21 The new modules system has the following advantages:
  22 </para>
  23
  24 <simplelist>
  25 <member>Transparent loading of static and shared modules (no need
  26 for a subsystem to know about modules)</member>
  27 <member>Simple selection between shared and static modules at configure time</member>
  28 <member>"preload modules" option for increasing performance for stable modules</member>
  29 <member>No nasty #define stuff anymore</member>
  30 <member>All backends are available as plugin now (including pdb_ldap and pdb_tdb)</member>
  31 </simplelist>
  32 </sect1>
  33
  34 <sect1>
  35 <title>Loading modules</title>
  36
  37 <para>
  38 Some subsystems in samba use different backends. These backends can be
  39 either statically linked in to samba or available as a plugin. A subsystem
  40 should have a function that allows a module to register itself. For example,
  41 the passdb subsystem has:
  42 </para>
  43
  44 <para><programlisting>
  45 NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function init);
  46 </programlisting></para>
  47
  48 <para>
  49 This function will be called by the initialisation function of the module to
  50 register itself.
  51 </para>
  52
  53 <sect2>
  54 <title>Static modules</title>
  55
  56 <para>
  57 The modules system compiles a list of initialisation functions for the
  58 static modules of each subsystem. This is a define. For example,
  59 it is here currently (from <filename>include/config.h</filename>):
  60 </para>
  61
  62 <para><programlisting>
  63 /* Static init functions */
  64 #define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();}
  65 </programlisting></para>
  66
  67 <para>
  68 These functions should be called before the subsystem is used. That
  69 should be done when the subsystem is initialised or first used.
  70 </para>
  71
  72 </sect2>
  73
  74 <sect2>
  75 <title>Shared modules</title>
  76
  77 <para>
  78 If a subsystem needs a certain backend, it should check if it has
  79 already been registered. If the backend hasn't been registered already,
  80 the subsystem should call smb_probe_module(char *subsystem, char *backend).
  81 This function tries to load the correct module from a certain path
  82 ($LIBDIR/subsystem/backend.so). If the first character in 'backend'
  83 is a slash, smb_probe_module() tries to load the module from the
  84 absolute path specified in 'backend'.
  85 </para>
  86
  87 <para>After smb_probe_module() has been executed, the subsystem
  88 should check again if the module has been registered.
  89 </para>
  90
  91 </sect2>
  92 </sect1>
  93
  94 <sect1>
  95 <title>Writing modules</title>
  96
  97 <para>
  98 Each module has an initialisation function. For modules that are
  99 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 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()).
 100 The prototype for these functions is:
 101 </para>
 102
 103 <para><programlisting>
 104 NTSTATUS init_module(TALLOC_CTX *);
 105 </programlisting></para>
 106
 107 <para>This function should call one or more
 108 registration functions. The function should return NT_STATUS_OK on success and
 109 NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</para>
 110
 111 <para>For example, pdb_ldap_init() contains: </para>
 112
 113 <para><programlisting>
 114 NTSTATUS pdb_ldap_init(TALLOC_CTX *)
 115 {
 116 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam);
 117 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua);
 118         return NT_STATUS_OK;
 119 }
 120 </programlisting></para>
 121
 122 <para>
 123 The TALLOC_CTX pointer passed as a parameter must be a long-lived context,
 124 that will stay around for as long as the program that loads the module
 125 exists. It allows the caller to taloc_free any long lived data the
 126 module choses to place on this context on program exit (giving a cleaner
 127 valgrind trace). It should be used by modules in place of talloc_autofree_context(),
 128 use of which makes programs thread-unsafe. Modules that don't care about
 129 free on exist should use the NULL talloc context.
 130 </para>
 131
 132 <sect2>
 133 <title>Static/Shared selection in configure.in</title>
 134
 135 <para>
 136 Some macros in configure.in generate the various defines and substs that
 137 are necessary for the system to work correct. All modules that should
 138 be built by default have to be added to the variable 'default_modules'.
 139 For example, if ldap is found, pdb_ldap is added to this variable.
 140 </para>
 141
 142 <para>
 143 On the bottom of configure.in, SMB_MODULE() should be called
 144 for each module and SMB_SUBSYSTEM() for each subsystem.
 145 </para>
 146
 147 <para>Syntax:</para>
 148
 149 <para><programlisting>
 150 SMB_MODULE(<replaceable>subsystem</replaceable>_<replaceable>backend</replaceable>, <replaceable>object files</replaceable>, <replaceable>plugin name</replaceable>, <replaceable>subsystem name</replaceable>, <replaceable>static_action</replaceable>, <replaceable>shared_action</replaceable>)
 151 SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>,<replaceable>depfile</replaceable>)
 152 </programlisting></para>
 153
 154 <para>The depfile for a certain subsystem is the file that calls the
 155 initialisation functions for the statically built in modules.</para>
 156
 157 <para>
 158 <replaceable>@SUBSYSTEM_MODULES@</replaceable> in Makefile.in will
 159 be replaced with the names of the plugins to build.
 160 </para>
 161
 162 <para>You must make sure all .c files that contain defines that can
 163 be changed by ./configure are rebuilt in the 'modules_clean' make target.
 164 Practically, this means all c files that contain <command>static_init_subsystem;</command> calls need to be rebuilt.
 165 </para>
 166
 167 <note>
 168 <para>
 169 There currently also is a configure.in command called SMB_MODULE_PROVIVES().
 170 This is used for modules that register multiple things. It should not
 171 be used as probing will most likely disappear in the future.</para>
 172 </note>
 173
 174 </sect2>
 175 </sect1>
 176 </chapter>