From 4474f67fa3f915f7e09fddc3df42cd97403752f9 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Wed, 26 Mar 2003 11:09:12 +0000 Subject: - Patch from John to update PDC-HOWTO, add ServerType and CUPS (not finished yet) - Regenerate docs - Update docs-status (This used to be commit adbb714ade8ab6f4e9b5d80f0f85041746c0edf1) --- docs/htmldocs/Samba-Developers-Guide.html | 367 +++++++++++++++++++++++++++++- 1 file changed, 355 insertions(+), 12 deletions(-) (limited to 'docs/htmldocs/Samba-Developers-Guide.html') diff --git a/docs/htmldocs/Samba-Developers-Guide.html b/docs/htmldocs/Samba-Developers-Guide.html index 22cbcec3ee..142d9dc537 100644 --- a/docs/htmldocs/Samba-Developers-Guide.html +++ b/docs/htmldocs/Samba-Developers-Guide.html @@ -816,23 +816,89 @@ NAME="SMBPASSWDFILEFORMAT" >
14. RPC Pluggable ModulesModules
14.1. AboutAdvantages
14.2. Loading modules
14.2.1. Static modules
14.2.2. Shared modules
14.3. Writing modules
14.3.1. Static/Shared selection in configure.in
15. RPC Pluggable Modules
15.1. About
15.2. General Overview
16. Notes to packagers
16.1. Versioning
16.2. Modules

Chapter 14. RPC Pluggable Modules

Chapter 14. Modules

14.1. About14.1. Advantages

The new modules system has the following advantages:

Transparent loading of static and shared modules (no need +for a subsystem to know about modules)
Simple selection between shared and static modules at configure time
"preload modules" option for increasing performance for stable modules
No nasty #define stuff anymore
All backends are available as plugin now (including pdb_ldap and pdb_tdb)

14.2. Loading modules

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: 

BOOL smb_register_passdb(const char *name, pdb_init_function init, int version);

This function will be called by the initialisation function of the module to +register itself.

14.2.1. Static modules

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 include/config.h): 

/* Static init functions */
+#define static_init_pdb { pdb_mysql_init(); pdb_ldap_init(); pdb_smbpasswd_init(); pdb_tdbsam_init(); pdb_guest_init();}

These functions should be called before the subsystem is used. That +should be done when the subsystem is initialised or first used.

14.2.2. Shared modules

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'.

After smb_probe_module() has been executed, the subsystem +should check again if the module has been registered.

14.3. Writing modules

Each module has an initialisation function. For modules that are +included with samba this name is 'subsystem_backend_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:

int init_module(void);

This function should call one or more +registration functions. The function should return non-zero on success and zero on +failure.

For example, pdb_ldap_init() contains: 

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;
+}

14.3.1. Static/Shared selection in configure.in

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.

On the bottom of configure.in, SMB_MODULE() should be called +for each module and SMB_SUBSYSTEM() for each subsystem.

Syntax:

SMB_MODULE(subsystem_backend, object files, plugin name, subsystem name, static_action, shared_action)
+SMB_SUBSYSTEM(subsystem)

Also, make sure to add the correct directives to +Makefile.in. @SUBSYSTEM_STATIC@ +will be replaced with a list of objects files of the modules that need to +be linked in statically. @SUBSYSTEM_MODULES@ will +be replaced with the names of the plugins to build.

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 static_init_subsystem; calls need to be rebuilded.

Chapter 15. RPC Pluggable Modules

15.1. About

This document describes how to make use the new RPC Pluggable Modules features @@ -9346,8 +9639,8 @@ CLASS="SECT1" >

14.2. General Overview15.2. General Overview

When an RPC call is sent to smbd, smbd tries to load a shared library by the @@ -9363,10 +9656,10 @@ CLASS="FILENAME" These shared libraries should be located in the <sambaroot>/lib/rpc. smbd then attempts to call the rpc_pipe_init function within -the shared library.

. smbd then attempts to call the init_module function within +the shared library. Check the chapter on modules for more information.

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:

Chapter 16. Notes to packagers
16.1. Versioning
Please, please update the version number in 
+source/include/version.h to include the versioning of your package. This makes it easier to distinguish standard samba builds
+from custom-build samba builds (distributions often patch packages). For 
+example, a good version would be: 
Version 2.999+3.0.alpha21-5 for Debian
16.2. Modules
Samba now has support for building parts of samba as plugins. This 
+makes it possible to, for example, put ldap or mysql support in a seperate 
+package, thus making it possible to have a normal samba package not 
+depending on ldap or mysql. To build as much parts of samba 
+as a plugin, run: 
./configure --with-shared-modules=rpc,vfs,auth,pdb,charset