1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
<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
should be done when the subsystem is initialised or first used.
</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 'init_module'. (In the case of modules included with samba, the configure system will add a #define subsystem_backend_init() init_module()).
The prototype for these functions is:
</para>
<para><programlisting>
int init_module(void);
</programlisting></para>
<para>This function should call one or more
registration functions. 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(<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>)
SMB_SUBSYSTEM(<replaceable>subsystem</replaceable>)
</programlisting></para>
<para>Also, make sure to add the correct directives to
<filename>Makefile.in</filename>. <replaceable>@SUBSYSTEM_STATIC@</replaceable>
will be replaced with a list of objects files of the modules that need to
be linked in statically. <replaceable>@SUBSYSTEM_MODULES@</replaceable> will
be replaced with the names of the plugins to build.
</para>
<para>You must make sure all .c files that contain defines that can
be changed by ./configure are rebuilded in the 'modules_clean' make target.
Practically, this means all c files that contain <command>static_init_subsystem;</command> calls need to be rebuilded.
</para>
</sect2>
</sect1>
</chapter>
|
