docs/docbook/devdoc/modules.xml

   1 <chapter id="modules">
   2 <chapterinfo>
   3         <author>
   4                 <firstname>Jelmer</firstname><surname>Vernooij</surname>
   5                 <affiliation>
   6                         <orgname>Samba Team</orgname>
   7                         <address><email>jelmer@samba.org</email></address>
   8                 </affiliation>
   9         </author>
  10         <pubdate> 19 March 2003 </pubdate>
  11 </chapterinfo>
  12
  13 <title>Modules</title>
  14
  15 <sect1>
  16 <title>Advantages</title>
  17
  18 <para>
  19 The new modules system has the following advantages:
  20 </para>
  21
  22 <simplelist>
  23 <member>Transparent loading of static and shared modules (no need
  24 for a subsystem to know about modules)</member>
  25 <member>Simple selection between shared and static modules at configure time</member>
  26 <member>"preload modules" option for increasing performance for stable modules</member>
  27 <member>No nasty #define stuff anymore</member>
  28 <member>All backends are available as plugin now (including pdb_ldap and pdb_tdb)</member>
  29 </simplelist>
  30 </sect1>
  31
  32 <sect1>
  33 <title>Loading modules</title>
  34
  35 <para>
  36 Some subsystems in samba use different backends. These backends can be
  37 either statically linked in to samba or available as a plugin. A subsystem
  38 should have a function that allows a module to register itself. For example,
  39 the passdb subsystem has:
  40 </para>
  41
  42 <para><programlisting>
  43 NTSTATUS smb_register_passdb(int version, const char *name, pdb_init_function init);
  44 </programlisting></para>
  45
  46 <para>
  47 This function will be called by the initialisation function of the module to
  48 register itself.
  49 </para>
  50
  51 <sect2>
  52 <title>Static modules</title>
  53
  54 <para>
  55 The modules system compiles a list of initialisation functions for the
  56 static modules of each subsystem. This is a define. For example,
  57 it is here currently (from <filename>include/config.h</filename>):
  58 </para>
  59
  60 <para><programlisting>
  61 /* Static init functions */
  62 #define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();}
  63 </programlisting></para>
  64
  65 <para>
  66 These functions should be called before the subsystem is used. That
  67 should be done when the subsystem is initialised or first used.
  68 </para>
  69
  70 </sect2>
  71
  72 <sect2>
  73 <title>Shared modules</title>
  74
  75 <para>
  76 If a subsystem needs a certain backend, it should check if it has
  77 already been registered. If the backend hasn't been registered already,
  78 the subsystem should call smb_probe_module(char *subsystem, char *backend).
  79 This function tries to load the correct module from a certain path
  80 ($LIBDIR/subsystem/backend.so). If the first character in 'backend'
  81 is a slash, smb_probe_module() tries to load the module from the
  82 absolute path specified in 'backend'.
  83 </para>
  84
  85 <para>After smb_probe_module() has been executed, the subsystem
  86 should check again if the module has been registered.
  87 </para>
  88
  89 </sect2>
  90 </sect1>
  91
  92 <sect1>
  93 <title>Writing modules</title>
  94
  95 <para>
  96 Each module has an initialisation function. For modules that are
  97 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()).
  98 The prototype for these functions is:
  99 </para>
 100
 101 <para><programlisting>
 102 NTSTATUS init_module(void);
 103 </programlisting></para>
 104
 105 <para>This function should call one or more
 106 registration functions. The function should return NT_STATUS_OK on success and
 107 NT_STATUS_UNSUCCESSFUL or a more useful nt error code on failure.</para>
 108
 109 <para>For example, pdb_ldap_init() contains: </para>
 110
 111 <para><programlisting>
 112 NTSTATUS pdb_ldap_init(void)
 113 {
 114 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam", pdb_init_ldapsam);
 115 smb_register_passdb(PASSDB_INTERFACE_VERSION, "ldapsam_nua", pdb_init_ldapsam_nua);
 116         return NT_STATUS_OK;
 117 }
 118 </programlisting></para>
 119
 120 <sect2>
 121 <title>Static/Shared selection in configure.in</title>
 122
 123 <para>
 124 Some macros in configure.in generate the various defines and substs that
 125 are necessary for the system to work correct. All modules that should
 126 be built by default have to be added to the variable 'default_modules'.
 127 For example, if ldap is found, pdb_ldap is added to this variable.
 128 </para>
 129
 130 <para>
 131 On the bottom of configure.in, SMB_MODULE() should be called
 132 for each module and SMB_SUBSYSTEM() for each subsystem.
 133 </para>
 134
 135 <para>Syntax:</para>
 136
 137 <para><programlisting>
 138 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>)
 139 SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>)
 140 </programlisting></para>
 141
 142 <para>Also, make sure to add the correct directives to
 143 <filename>Makefile.in</filename>. <replaceable>@SUBSYSTEM_STATIC@</replaceable>
 144 will be replaced with a list of objects files of the modules that need to
 145 be linked in statically. <replaceable>@SUBSYSTEM_MODULES@</replaceable> will
 146 be replaced with the names of the plugins to build.
 147 </para>
 148
 149 <para>You must make sure all .c files that contain defines that can
 150 be changed by ./configure are rebuilded in the 'modules_clean' make target.
 151 Practically, this means all c files that contain <command>static_init_subsystem;</command> calls need to be rebuilded.
 152 </para>
 153
 154 </sect2>
 155 </sect1>
 156 </chapter>