This commit was manufactured by cvs2svn to create tag
[Samba.git] / source / architecture.doc
blob58a46895941bb8ed492960c1a2eaf47ee26e9f5c
1 Samba Architecture
2 ------------------
4 First preliminary version Dan Shearer Nov 97
5 Quickly scrabbled together from odd bits of mail and memory. Please update.
7 This document gives a general overview of how Samba works
8 internally. The Samba Team has tried to come up with a model which is
9 the best possible compromise between elegance, portability, security
10 and the constraints imposed by the very message SMB and CIFS
11 protocol. 
13 It also tries to answer some of the frequently asked questions such as:
15         *       Is Samba secure when running on Unix? The xyz platform?
16                 What about the root priveliges issue?
18         *       Pros and cons of multithreading in various parts of Samba
20         *       Why not have a separate process for name resolution, WINS,
21                 and browsing?
24 Multithreading and Samba
25 ------------------------
27 People sometimes tout threads as a uniformly good thing. They are very
28 nice in their place but are quite inappropriate for smbd. nmbd is
29 another matter, and multi-threading it would be very nice. 
31 The short version is that smbd is not multithreaded, and alternative
32 servers that take this approach under Unix (such as Syntax, at the
33 time of writing) suffer tremendous performance penalties and are less
34 robust. nmbd is not threaded either, but this is because it is not
35 possible to do it while keeping code consistent and portable across 35
36 or more platforms. (This drawback also applies to threading smbd.)
38 The longer versions is that there are very good reasons for not making
39 smbd multi-threaded.  Multi-threading would actually make Samba much
40 slower, less scalable, less portable and much less robust. The fact
41 that we use a separate process for each connection is one of Samba's
42 biggest advantages.
44 Threading smbd
45 --------------
47 A few problems that would arise from a threaded smbd are:
49 0)  It's not only to create threads instead of processes, but you
50     must care about all variables if they have to be thread specific
51     (currently they would be global).
53 1) if one thread dies (eg. a seg fault) then all threads die. We can
54 immediately throw robustness out the window.
56 2) many of the system calls we make are blocking. Non-blocking
57 equivalents of many calls are either not available or are awkward (and
58 slow) to use. So while we block in one thread all clients are
59 waiting. Imagine if one share is a slow NFS filesystem and the others
60 are fast, we will end up slowing all clients to the speed of NFS.
62 3) you can't run as a different uid in different threads. This means
63 we would have to switch uid/gid on _every_ SMB packet. It would be
64 horrendously slow.
66 4) the per process file descriptor limit would mean that we could only
67 support a limited number of clients.
69 5) we couldn't use the system locking calls as the locking context of
70 fcntl() is a process, not a thread.
72 Threading nmbd
73 --------------
75 This would be ideal, but gets sunk by portability requirements.
77 Andrew tried to write a test threads library for nmbd that used only
78 ansi-C constructs (using setjmp and longjmp). Unfortunately some OSes
79 defeat this by restricting longjmp to calling addresses that are
80 shallower than the current address on the stack (apparently AIX does
81 this). This makes a truly portable threads library impossible. So to
82 support all our current platforms we would have to code nmbd both with
83 and without threads, and as the real aim of threads is to make the
84 code clearer we would not have gained anything. (it is a myth that
85 threads make things faster. threading is like recursion, it can make
86 things clear but the same thing can always be done faster by some
87 other method)
89 Chris tried to spec out a general design that would abstract threading
90 vs separate processes (vs other methods?) and make them accessible
91 through some general API. This doesn't work because of the data
92 sharing requirements of the protocol (packets in the future depending
93 on packets now, etc.) At least, the code would work but would be very
94 clumsy, and besides the fork() type model would never work on Unix. (Is there an OS that it would work on, for nmbd?)
96 A fork() is cheap, but not nearly cheap enough to do on every UDP
97 packet that arrives. Having a pool of processes is possible but is
98 nasty to program cleanly due to the enormous amount of shared data (in
99 complex structures) between the processes. We can't rely on each
100 platform having a shared memory system.
102 nbmd Design
103 -----------
105 Originally Andrew used recursion to simulate a multi-threaded
106 environment, which use the stack enormously and made for really
107 confusing debugging sessions. Luke Leighton rewrote it to use a
108 queuing system that keeps state information on each packet.  The
109 first version used a single structure which was used by all the
110 pending states.  As the initialisation of this structure was
111 done by adding arguments, as the functionality developed, it got
112 pretty messy.  So, it was replaced with a higher-order function
113 and a pointer to a user-defined memory block.  This suddenly
114 made things much simpler: large numbers of functions could be
115 made static, and modularised.  This is the same principle as used
116 in NT's kernel, and achieves the same effect as threads, but in
117 a single process.
119 Then Jeremy rewrote nmbd. The packet data in nmbd isn't what's on the
120 wire. It's a nice format that is very amenable to processing but still
121 keeps the idea of a distinct packet. See "struct packet_struct" in
122 nameserv.h.  It has all the detail but none of the on-the-wire
123 mess. This makes it ideal for using in disk or memory-based databases
124 for browsing and WINS support. 
126 nmbd now consists of a series of modules. It...
129 Samba Design and Security
130 -------------------------
132 Why Isn't nmbd Multiple Daemons?
133 --------------------------------
135 DCE/RPC
136 -------
138 NT administration is basically DCE/RPC function calls.  The entire
139 NT architecture is based on DCE/RPC over SMB.