4bf8671e6008737a26c70f0d58ddc7b21b13e2ac
[samba.git] / prog_guide.txt
1 THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
2 FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.
3
4
5 Samba4 Programming Guide
6 ------------------------
7
8 The internals of Samba4 are quite different from previous versions of
9 Samba, so even if you are an experienced Samba developer please take
10 the time to read through this document.
11
12 This document will explain both the broad structure of Samba4, and
13 some of the common coding elements such as memory management and
14 dealing with macros.
15
16
17 Coding Style
18 ------------
19
20 In past versions of Samba we have basically let each programmer choose
21 their own programming style. Unfortunately the result has often been
22 that code that other members of the team find difficult to read. For
23 Samba version 4 I would like to standardise on a common coding style
24 to make the whole tree more readable. For those of you who are
25 horrified at the idea of having to learn a new style, I can assure you
26 that it isn't as painful as you might think. I was forced to adopt a
27 new style when I started working on the Linux kernel, and after some
28 initial pain found it quite easy.
29
30 That said, I don't want to invent a new style, instead I would like to
31 adopt the style used by the Linux kernel. It is a widely used style
32 with plenty of support tools available. See Documentation/CodingStyle
33 in the Linux source tree. This is the style that I have used to write
34 all of the core infrastructure for Samba4 and I think that we should
35 continue with that style.
36
37 I also think that we should most definately *not* adopt an automatic
38 reformatting system in cvs (or whatever other source code system we
39 end up using in the future). Such automatic formatters are, in my
40 experience, incredibly error prone and don't understand the necessary
41 exceptions. I don't mind if people use automated tools to reformat
42 their own code before they commit it, but please do not run such
43 automated tools on large slabs of existing code without being willing
44 to spend a *lot* of time hand checking the results.
45
46 Finally, I think that for code that is parsing or formatting protocol
47 packets the code layout should strongly reflect the packet
48 format. That means ordring the code so that it parses in the same
49 order as the packet is stored on the wire (where possible) and using
50 white space to align packet offsets so that a reader can immediately
51 map any line of the code to the corresponding place in the packet.
52
53
54 Static and Global Data
55 ----------------------
56
57 The basic rule is "avoid static and global data like the plague". What
58 do I mean by static data? The way to tell if you have static data in a
59 file is to use the "size" utility in Linux. For example if we run:
60
61   size libcli/raw/*.o
62
63 in Samba4 then you get the following:
64
65    text    data     bss     dec     hex filename
66    2015       0       0    2015     7df libcli/raw/clikrb5.o
67     202       0       0     202      ca libcli/raw/clioplock.o
68      35       0       0      35      23 libcli/raw/clirewrite.o
69    3891       0       0    3891     f33 libcli/raw/clisession.o
70     869       0       0     869     365 libcli/raw/clisocket.o
71    4962       0       0    4962    1362 libcli/raw/clispnego.o
72    1223       0       0    1223     4c7 libcli/raw/clitransport.o
73    2294       0       0    2294     8f6 libcli/raw/clitree.o
74    1081       0       0    1081     439 libcli/raw/raweas.o
75    6765       0       0    6765    1a6d libcli/raw/rawfile.o
76    6824       0       0    6824    1aa8 libcli/raw/rawfileinfo.o
77    2944       0       0    2944     b80 libcli/raw/rawfsinfo.o
78     541       0       0     541     21d libcli/raw/rawioctl.o
79    1728       0       0    1728     6c0 libcli/raw/rawnegotiate.o
80     723       0       0     723     2d3 libcli/raw/rawnotify.o
81    3779       0       0    3779     ec3 libcli/raw/rawreadwrite.o
82    6597       0       0    6597    19c5 libcli/raw/rawrequest.o
83    5580       0       0    5580    15cc libcli/raw/rawsearch.o
84    3034       0       0    3034     bda libcli/raw/rawsetfileinfo.o
85    5187       0       0    5187    1443 libcli/raw/rawtrans.o
86    2033       0       0    2033     7f1 libcli/raw/smb_signing.o
87
88 notice that the "data" and "bss" columns are all zero? That is
89 good. If there are any non-zero values in data or bss then that
90 indicates static data and is bad (as a rule of thumb).
91
92 Lets compare that result to the equivalent in Samba3:
93
94    text    data     bss     dec     hex filename
95    3978       0       0    3978     f8a libsmb/asn1.o
96   18963       0     288   19251    4b33 libsmb/cliconnect.o
97    2815       0    1024    3839     eff libsmb/clidgram.o
98    4038       0       0    4038     fc6 libsmb/clientgen.o
99    3337     664     256    4257    10a1 libsmb/clierror.o
100   10043       0       0   10043    273b libsmb/clifile.o
101     332       0       0     332     14c libsmb/clifsinfo.o
102     166       0       0     166      a6 libsmb/clikrb5.o
103    5212       0       0    5212    145c libsmb/clilist.o
104    1367       0       0    1367     557 libsmb/climessage.o
105     259       0       0     259     103 libsmb/clioplock.o
106    1584       0       0    1584     630 libsmb/cliprint.o
107    7565       0     256    7821    1e8d libsmb/cliquota.o
108    7694       0       0    7694    1e0e libsmb/clirap.o
109   27440       0       0   27440    6b30 libsmb/clirap2.o
110    2905       0       0    2905     b59 libsmb/clireadwrite.o
111    1698       0       0    1698     6a2 libsmb/clisecdesc.o
112    5517       0       0    5517    158d libsmb/clispnego.o
113     485       0       0     485     1e5 libsmb/clistr.o
114    8449       0       0    8449    2101 libsmb/clitrans.o
115    2053       0       4    2057     809 libsmb/conncache.o
116    3041       0     256    3297     ce1 libsmb/credentials.o
117    1261       0    1024    2285     8ed libsmb/doserr.o
118   14560       0       0   14560    38e0 libsmb/errormap.o
119    3645       0       0    3645     e3d libsmb/namecache.o
120   16815       0       8   16823    41b7 libsmb/namequery.o
121    1626       0       0    1626     65a libsmb/namequery_dc.o
122   14301       0    1076   15377    3c11 libsmb/nmblib.o
123   24516       0    2048   26564    67c4 libsmb/nterr.o
124    8661       0       8    8669    21dd libsmb/ntlmssp.o
125    3188       0       0    3188     c74 libsmb/ntlmssp_parse.o
126    4945       0       0    4945    1351 libsmb/ntlmssp_sign.o
127    1303       0       0    1303     517 libsmb/passchange.o
128    1221       0       0    1221     4c5 libsmb/pwd_cache.o
129    2475       0       4    2479     9af libsmb/samlogon_cache.o
130   10768      32       0   10800    2a30 libsmb/smb_signing.o
131    4524       0      16    4540    11bc libsmb/smbdes.o
132    5708       0       0    5708    164c libsmb/smbencrypt.o
133    7049       0    3072   10121    2789 libsmb/smberr.o
134    2995       0       0    2995     bb3 libsmb/spnego.o
135    3186       0       0    3186     c72 libsmb/trustdom_cache.o
136    1742       0       0    1742     6ce libsmb/trusts_util.o
137     918       0      28     946     3b2 libsmb/unexpected.o
138
139 notice all of the non-zero data and bss elements? Every bit of that
140 data is a bug waiting to happen.
141
142 Static data is evil as it has the following consequences:
143  - it makes code much less likely to be thread-safe
144  - it makes code much less likely to be recursion-safe
145  - it leads to subtle side effects when the same code is called from
146    multiple places
147
148 Static data is particularly evil in library code (such as our internal
149 smb and rpc libraries). If you can get rid of all static data in
150 libraries then you can make some fairly strong guarantees about the
151 behaviour of functions in that library, which really helps.
152
153 Of course, it is possible to write code that uses static data and is
154 safe, it's just much harder to do that than just avoid static data in
155 the first place. We have been tripped up countless times by subtle
156 bugs in Samba due to the use of static data, so I think it is time to
157 start avoiding it in new code. Much of the core infrastructure of
158 Samba4 was specifically written to avoid static data, so I'm going to
159 be really annoyed if everyone starts adding lots of static data back
160 in.
161
162 So, how do we avoid static data? The basic method is to use context
163 pointers. When reading the Samba4 code you will notice that just about
164 every function takes a pointer to a context structure as its first
165 argument. Any data that the function needs that isn't an explicit
166 argument to the function can be found by traversing that context. 
167
168 Note that this includes all of the little caches that we have lying
169 all over the code in Samba3. I'm referring to the ones that generally
170 have a "static int initialised" and then some static string or integer
171 that remembers the last return value of the function. Get rid of them!
172 If you are *REALLY* absolutely completely certain that your personal
173 favourite mini-cache is needed then you should do it properly by
174 putting it into the appropriate context rather than doing it the lazy
175 way by putting it inside the target function. I would suggest however
176 that the vast majority of those little caches are useless - don't
177 stick it in unless you have really firm benchmarking results that show
178 that it is needed and helps by a significant amount.
179
180 Note that Samba4 is not yet completely clean of static data like
181 this. I've gotten the smbd/ directory down to 24 bytes of static data,
182 and libcli/raw/ down to zero. I've also gotten the ntvfs layer and all
183 backends down to just 8 bytes in ntvfs_base.c. The rest still needs
184 some more work.
185
186 Also note that truly constant data is OK, and will not in fact show up
187 in the data and bss columns in "size" anyway (it will be included in
188 "text"). So you can have constant tables of protocol data.
189
190
191 How to use talloc
192 -----------------
193
194 If you are used to talloc from Samba3 then please read this carefully,
195 as talloc has changed rather a lot.
196
197 The new talloc is a hierarchical, reference counted memory pool system
198 with destructors. Quite a mounthful really, but not too bad once you
199 get used to it.
200
201 Perhaps the biggest change from Samba3 is that there is no distinction
202 between a "talloc context" and a "talloc pointer". Any pointer
203 returned from talloc() is itself a valid talloc context. This means
204 you can do this:
205
206   struct foo *a = talloc(mem_ctx, sizeof(*s));
207   a->name = talloc(a, strlen("foo")+1);
208
209 and the pointer a->name would be a "child" of the talloc context "a"
210 which is itself a child of mem_ctx. So if you do talloc_free(mem_ctx)
211 then it is all destroyed, whereas if you do talloc_free(a) then just a
212 and a->name are destroyed.
213
214 If you think about this, then what this effectively gives you is an
215 n-ary tree, where you can free any part of the tree with
216 talloc_free().
217
218 The next big change with the new talloc is reference counts. A talloc
219 pointer starts with a reference count of 1. You can call
220 talloc_increase_ref_count() on any talloc pointer and that increases
221 the reference count by 1. If you then call talloc_free() on a pointer
222 that has a reference count greater than 1, then the reference count is
223 decreased, but the memory is not released.
224
225 Finally, talloc now has destructors. You can set a destructor on any
226 talloc pointer using talloc_set_destructor(). Your destructor will
227 then be called before the memory is released. An interesting feature
228 of these destructors is that they can return a error. If the
229 destructor returns -1 then that is interpreted as a refusal to release
230 the memory, and the talloc_free() will return. It will also prevent
231 the release of all memory "below" that memory in the tree.
232
233 You should also go and look at a new talloc function in Samba4 called
234 talloc_steal(). By using talloc_steal() you can move a lump of memory
235 from one memory context to another without copying the data. This
236 should be used when a backend function (such as a packet parser)
237 produces a result as a lump of talloc memory and you need to keep it
238 around for a longer lifetime than the talloc context it is in. You
239 just "steal" the memory from the short-lived context, putting it into
240 your long lived context.
241
242
243 Interface Structures
244 --------------------
245
246 One of the biggest changes in Samba4 is the universal use of interface
247 structures. Go take a look through include/smb_interfaces.h now to get
248 an idea of what I am talking about.
249
250 In Samba3 many of the core wire structures in the SMB protocol were
251 never explicitly defined in Samba. Instead, our parse and generation
252 functions just worked directly with wire buffers. The biggest problem
253 with this is that is tied our parse code with out "business logic"
254 much too closely, which meant the code got extremely confusing to
255 read.
256
257 In Samba4 we have explicitly defined interface structures for
258 everything in the protocol. When we receive a buffer we always parse
259 it completely into one of these structures, then we pass a pointer to
260 that structure to a backend handler. What we must *not* do is make any
261 decisions about the data inside the parse functions. That is critical
262 as different backends will need different portions of the data. This
263 leads to a golden rule for Samba4:
264
265   "don't design interfaces that lose information"
266
267 In Samba3 our backends often received "condensed" versions of the
268 information sent from clients, but this inevitably meant that some
269 backends could not get at the data they needed to do what they wanted,
270 so from now on we should expose the backends to all of the available
271 information and let them choose which bits they want.
272
273 Ok, so now some of you will be thinking "this sounds just like our
274 msrpc code from Samba3", and while to some extent this is true there
275 are extremely important differences in the approach that are worth
276 pointing out.
277
278 In the Samba3 msrpc code we used explicit parse strucrures for all
279 msrpc functions. The problem is that we didn't just put all of the
280 real variables in these structures, we also put in all the artifacts
281 as well. A good example is the security descriptor strucrure that
282 looks like this in Samba3:
283
284 typedef struct security_descriptor_info
285 {
286         uint16 revision; 
287         uint16 type;    
288
289         uint32 off_owner_sid;
290         uint32 off_grp_sid;
291         uint32 off_sacl;
292         uint32 off_dacl;
293
294         SEC_ACL *dacl;
295         SEC_ACL *sacl;
296         DOM_SID *owner_sid; 
297         DOM_SID *grp_sid;
298 } SEC_DESC;
299
300 The problem with this structure is all the off_* variables. Those are
301 not part of the interface, and do not appear in any real descriptions
302 of Microsoft security descriptors. They are parsing artifacts
303 generated by the IDL compiler that Microsoft use. That doesn't mean
304 they aren't needed on the wire - indeed they are as they tell the
305 parser where to find the following four variables, but they should
306 *NOT* be in the interface structure.
307
308 In Samba3 there were unwritten rules about which variables in a
309 strucrure a high level caller has to fill in and which ones are filled
310 in by the marshalling code. In Samba4 those rules are gone, because
311 the redundent artifact variables are gone. The high level caller just
312 sets up the real variables and the marshalling code worries about
313 generating the right offsets.
314
315 The same rule applies to strings. In many places in the SMB and MSRPC
316 protocols complex strings are used on the wire, with complex rules
317 about padding, format, alighment, termination etc. None of that
318 information is useful to a high level calling routine or to a backend
319 - its all just so much wire fluff. So, in Samba4 these strings are
320 just "char *" and are always in our internal multi-byte format (which
321 is usually UTF8). It is up to the parse functions to worry about
322 translating the format and getting the padding right.
323
324 The one exception to this is the use of the WIRE_STRING type, but that
325 has a very good justification in terms of regression testing. Go and
326 read the comment in smb_interfaces.h about that now.
327
328 So, here is another rule to code by. When writing an interface
329 structure think carefully about what variables in the structure can be
330 left out as they are redundent. If some length is effectively defined
331 twice on the wire then only put it once in the packet. If a length can
332 be inferred from a null termination then do that and leave the length
333 out of the structure completely. Don't put redundent stuff in
334 structures!
335
336
337 Async Design
338 ------------
339
340 Samba4 has an asynchronous design. That affects *lots* of the code,
341 and the implications of the asynchronous design needs to be considered
342 just about everywhere.
343
344 The first aspect of the async design to look at is the SMB client
345 library. Lets take a look at the following three functions in
346 libcli/raw/rawfile.c:
347
348 struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms);
349 NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms);
350 NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms);
351
352 Go and read them now then come back.
353
354 Ok, first notice there there are 3 separate functions, whereas the
355 equivalent code in Samba3 had just one. Also note that the 3rd
356 function is extremely simple - its just a wrapper around calling the
357 first two in order.
358
359 The three separate functions are needed because we need to be able to
360 generate SMB calls asynchronously. The first call, which for smb calls
361 is always called smb_raw_XXXX_send(), constructs and sends a SMB
362 request and returns a "struct cli_request" which acts as a handle for
363 the request. The caller is then free to do lots of other calls if it
364 wants to, then when it is ready it can call the smb_raw_XXX_recv()
365 function to receive the reply. 
366
367 If all you want is a synchronous call then call the 3rd interface, the
368 one called smb_raw_XXXX(). That just calls the first two in order, and
369 blocks waiting for the reply. 
370
371 But what if you want to be called when the reply comes in? Yes, thats
372 possible. You can do things like this:
373
374     struct cli_request *req;
375
376     req = smb_raw_XXX_send(tree, params);
377
378     req->async.fn = my_callback;
379     req->async.private = my_private_data;
380
381 then in your callback function you can call the smb_raw_XXXX_recv()
382 function to receive the reply. Your callback will receive the "req"
383 pointer, which you can use to retrieve your private data from
384 req->async.private.
385
386 Then all you need to do is ensure that the main loop in the client
387 library gets called. You can either do that by polling the connection
388 using cli_transport_pending() and cli_request_receive_next() or you
389 can use transport->idle.func to setup an idle function handler to call
390 back to your main code. Either way, you can build a fully async
391 application.
392
393 In order to support all of this we have to make sure that when we
394 write a piece of library code (SMB, MSRPC etc) that we build the
395 separate _send() and _recv() functions. It really is worth the effort.
396
397 Now about async in smbd, a much more complex topic.
398
399 The SMB protocol is inherently async. Some functions (such as change
400 notify) often don't return for hours, while hundreds of other
401 functions pass through the socket. Take a look at the RAW-MUX test in
402 the Samba4 smbtorture to see some really extreme examples of the sort
403 of async operations that Windows supports. I particularly like the
404 open/open/close sequence where the 2nd open (which conflicts with the
405 first) succeeds because the subsequent close is answered out of order.
406
407 In Samba3 we handled this stuff very badly. We had awful "pending
408 request" queues that allocated full 128k packet buffers, and even with
409 all that crap we got the semantics wrong. In Samba4 I intend to make
410 sure we get this stuff right.
411
412 So, how do we do this? We now have an async interface between smbd and
413 the NTVFS backends. Whenever smbd calls into a backend the backend has
414 an option of answer the request in a synchronous fashion if it wants
415 to just like in Samba3, but it also has the option of answering the
416 request asynchronously. The only backend that currently does this is
417 the CIFS backend, but I hope the other backends will soon do this to.
418
419 To make this work you need to do things like this in the backend:
420
421   req->control_flags |= REQ_CONTROL_ASYNC;
422
423 that tells smbd that the backend has elected to reply later rather
424 than replying immediately. The backend must *only* do this if
425 req->async.send_fn is not NULL. If send_fn is NULL then it means that
426 the smbd front end cannot handle this function being replied to in an
427 async fashion.
428
429 If the backend does this then it is up to the backend to call
430 req->async.send_fn() when it is ready to reply. It the meantime smbd
431 puts the call on hold and goes back to answering other requests on the
432 socket.
433
434 Inside smbd you will find that there is code to support this. The most
435 obvious change is that smbd splits each SMB reply function into two
436 parts - just like the client library has a _send() and _recv()
437 function, so smbd has a _send() function and the parse function for
438 each SMB.
439
440 As an example go and have a look at reply_getatr_send() and
441 reply_getatr() in smbd/reply.c. Read them? Good.
442
443 Notice that reply_getatr() sets up the req->async structure to contain
444 the send function. Thats how the backend gets to do an async reply, it
445 calls this function when it is ready. Also notice that reply_getatr()
446 only does the parsing of the request, and does not do the reply
447 generation. That is done by the _send() function. 
448
449 The only missing piece in the Samba4 right now that prevents it being
450 fully async is that it currently does the low level socket calls (read
451 and write on sockets) in a blocking fashion. It does use select() to
452 make it somewhat async, but if a client were to send a partial packet
453 then delay before sending the rest then smbd would be stuck waiting
454 for the second half of the packet. 
455
456 To fix this I plan on making the socket calls async as well, which
457 luckily will not involve any API changes in the core of smbd or the
458 library. It just involves a little bit of extra code in clitransport.c
459 and smbd/request.c. As a side effect I hope that this will also reduce
460 the average number of system calls required to answer a request, so we
461 may see a performance improvement.
462
463
464 NTVFS
465 -----
466
467 One of the most noticeable changes in Samba4 is the introduction of
468 the NTVFS layer. This provided the initial motivation for the design
469 of Samba4 and in many ways lies at the heart of the design.
470
471 In Samba3 the main file serving process (smbd) combined the handling
472 of the SMB protocol with the mapping to POSIX semantics in the same
473 code. If you look in smbd/reply.c in Samba3 you see numerous places
474 where POSIX assumptions are mixed tightly with SMB parsing code. We
475 did have a VFS layer in Samba3, but it was a POSIX-like VFS layer, so
476 no matter how you wrote a plugin you could not bypass the POSIX
477 mapping decisions that had already been made before the VFS layer was
478 called.
479
480 In Samba4 things are quite different. All SMB parsing is performed in
481 the smbd front end, then fully parsed requests are passed to the NTVFS
482 backend. That backend makes any semantic mapping decisions and fills
483 in the 'out' portion of the request. The front end is then responsible
484 for putting those results into wire format and sending them to the
485 client.
486
487 Lets have a look at one of those request structures. Go and read the
488 definition of "union smb_write" and "enum write_level" in
489 include/smb_interfaces.h. (no, don't just skip reading it, really go
490 and read it. Yes, that means you!).
491
492 Notice the union? That's how Samba4 allows a single NTVFS backend
493 interface to handle the several different ways of doing a write
494 operation in the SMB protocol. Now lets look at one section of that
495 union:
496
497         /* SMBwriteX interface */
498         struct {
499                 enum write_level level;
500
501                 struct {
502                         uint16 fnum;
503                         SMB_BIG_UINT offset;
504                         uint16 wmode;
505                         uint16 remaining;
506                         uint32 count;
507                         const char *data;
508                 } in;
509                 struct {
510                         uint32 nwritten;
511                         uint16 remaining;
512                 } out;
513         } writex;
514
515 see the "in" and "out" sections? The "in" section is for parameters
516 that the SMB client sends on the wire as part of the request. The smbd
517 front end parse code parses the wire request and fills in all those
518 parameters. It then calls the NTVFS interface which looks like this:
519
520   NTSTATUS (*write)(struct request_context *req, union smb_write *io);
521
522 and the NTVFS backend does the write request. The backend then fills
523 in the "out" section of the writex structure and gives the union back
524 to the front end (either by returning, or if done in an async fashion
525 then by calling the async send function. See the async discussion
526 elsewhere in this document).
527
528 The NTVFS backend knows which particular function is being requested
529 by looking at io->generic.level. Notice that this enum is also
530 repeated inside each of the sub-structures in the union, so the
531 backend could just as easily look at io->writex.level and would get
532 the same variable.
533
534 Notice also that some levels (such as splwrite) don't have an "out"
535 section. This happens because there is no return value apart from a
536 status code from those SMB calls. 
537
538 So what about status codes? The status code is returned directly by
539 the backend NTVFS interface when the call is performed
540 synchronously. When performed asynchronously then the status code is
541 put into req->async.status before the req->async.send_fn() callback is
542 called.
543
544 Currently the most complete NTVFS backend is the CIFS backend. I don't
545 expect this backend will be used much in production, but it does
546 provide the ideal test case for our NTVFS design. As it offers the
547 full capabilities that are possible with a CIFS server we can be sure
548 that we don't have any gaping holes in our APIs, and that the front
549 end code is flexible enough to handle any advances in the NT style
550 feature sets of Unix filesystems that make come along.
551
552
553 Process Models
554 --------------
555
556 In Samba3 we supported just one process model. It just so happens that
557 the process model that Samba3 supported is the "right" one for most
558 users, but there are situations where this model wasn't ideal.
559
560 In Samba4 you can choose the smbd process model on the smbd command
561 line. 
562
563
564 DCERPC binding strings
565 ----------------------
566
567 When connecting to a dcerpc service you need to specify a binding
568 string. 
569
570 The format is:
571
572   TRANSPORT:host:[flags]
573
574 where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP
575
576 "host" is an IP or hostname or netbios name
577
578 "flags" can include a SMB pipe name if using the ncacn_np transport or
579 a TCP port number if using the ncacn_ip_tcp transport, otherwise they
580 will be auto-determined.
581
582 other recognised flags are:
583
584   sign : enable ntlmssp signing
585   seal : enable ntlmssp sealing
586   validate: enable the NDR validator
587   print: enable debugging of the packets
588   bigendian: use bigendian RPC
589
590
591 For example, these all connect to the samr pipe:
592
593    ncacn_np:myserver
594    ncacn_np:myserver:samr
595    ncacn_np:myserver:samr,seal
596    ncacn_np:myserver:\pipe\samr
597    ncacn_np:myserver:/pipe/samr
598    ncacn_np:myserver[samr]
599    ncacn_np:myserver[\pipe\samr]
600    ncacn_np:myserver[/pipe/samr]
601    ncacn_np:myserver:[samr,sign,print]
602    ncacn_np:myserver:[\pipe\samr,sign,seal,bigendian]
603    ncacn_np:myserver:[/pipe/samr,seal,validate]
604
605    ncacn_ip_tcp:myserver
606    ncacn_ip_tcp:myserver:1024
607    ncacn_ip_tcp:myserver[1024]
608    ncacn_ip_tcp:myserver:[1024,sign,seal]
609
610
611 IDEA: Maybe extend UNC names like this?
612
613  smbclient //server/share
614  smbclient //server/share:[sign,seal,spnego]
615
616 DCERPC Handles
617 --------------
618 The various handles that are used in the RPC servers should be created and 
619 fetch using the dcesrv_handle_* functions.
620
621 Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain 
622 a new handle of the specified type. Handle types are unique within each 
623 pipe.
624
625 The handle can later be fetched again using
626 struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type)
627 and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *).
628
629 User data should be stored in the 'data' member of the dcesrv_handle struct.
630
631
632 MSRPC
633 -----
634
635
636
637  - ntvfs
638  - testing
639  - command line handling
640  - libcli structure
641  - posix reliance
642  - uid/gid handling
643  - process models
644  - static data
645  - msrpc
646
647
648 - use _p talloc varients
649
650 don't zero structures! avoid ZERO_STRUCT() and talloc_zero()
651
652
653 GMT vs TZ in printout of QFILEINFO timezones
654
655 put in full UNC path in tconx
656
657 test timezone handling by using a server in different zone from client
658
659 don't just use any old TALLOC_CTX, use the right one!
660
661 do {} while (0) system
662
663 NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
664
665 need to implement secondary parts of trans2 and nttrans in server and
666 client
667
668 add talloc_steal() to move a talloc ptr from one pool to another
669
670 document access_mask in openx reply
671
672 check all capabilities and flag1, flag2 fields (eg. EAs)
673
674 large files -> pass thru levels
675
676 setpathinfo is very fussy about null termination of the file name
677
678 the overwrite flag doesn't seem to work on setpathinfo RENAME_INFORMATION
679
680 END_OF_FILE_INFORMATION and ALLOCATION_INFORMATION don't seem to work
681 via setpathinfo
682
683 on w2k3 setpathinfo DISPOSITION_INFORMATION fails, but does have an
684 effect. It leaves the file with SHARING_VIOLATION.
685
686 on w2k3 trans2 setpathinfo with any invalid low numbered level causes
687 the file to get into a state where DELETE_PENDING is reported, and the
688 file cannot be deleted until you reboot
689
690 trans2 qpathinfo doesn't see the delete_pending flag correctly, but
691 qfileinfo does!
692
693 get rid of pstring, fstring, strtok
694
695 add programming documentation note about lp_set_cmdline()
696
697 need to add a wct checking function in all client parsing code,
698 similar to REQ_CHECK_WCT()
699
700 need to make sure that NTTIME is a round number of seconds when
701 converted from time_t
702
703 not using a zero next offset in SMB_FILE_STREAM_INFORMATION for last
704 entry causes explorer exception under win2000
705
706
707 if the server sets the session key the same for a second SMB socket as
708 an initial socket then the client will not re-authenticate, it will go
709 straight to a tconx, skipping session setup and will use all the
710 existing parameters! This allows two sockets with the same keys!?
711
712
713 removed blocking lock code, we now queue the whole request the same as
714 we queue any other pending request. This allows for things like a
715 close() while a pending blocking lock is being processed to operate
716 sanely.
717
718 disabled change notify code
719
720 disabled oplock code
721
722
723
724 MILESTONES
725 ==========
726
727
728 client library and test code
729 ----------------------------
730
731   convert client library to new structure
732   get smbtorture working
733   get smbclient working
734   expand client library for all requests
735   write per-request test suite
736   gentest randomised test suite
737   separate client code as a library for non-Samba use
738
739 server code
740 -----------
741   add remaining core SMB requests
742   add IPC layer
743   add nttrans layer
744   add rpc layer
745   fix auth models (share, server, rpc)
746   get net command working
747   connect CIFS backend to server level auth
748   get nmbd working
749   get winbindd working
750   reconnect printing code
751   restore removed smbd options
752   add smb.conf macro substitution code
753   add async backend notification 
754   add generic timer event mechanism
755
756 clustering code
757 ---------------
758
759   write CIFS backend
760   new server models (break 1-1)
761   test clustered models
762   add fulcrum statistics gathering
763
764 docs
765 ----
766
767   conference paper
768   developer docs
769
770 svn instructions
771
772 Ideas
773 -----
774
775  - store all config in config.ldb
776
777  - load from smb.conf if modtime changes
778
779  - dump full system config with ldbsearch
780
781  - will need the ability to form a ldif difference file
782
783  - advanced web admin via a web ldb editor
784
785  - normal web admin via web forms -> ldif
786
787  - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc
788
789  - subsystems in smbd will load config parameters for a share
790    using ldbsearch at tconx time
791
792  - need a loadparm equivalent module that provides parameter defaults
793
794  - start smbd like this:  "smbd -C tdb://etc/samba/config.ldb" or
795    "smbd -C ldapi://var/run/ldapi"
796
797  - write a tool that generates a template ldap schema from an existing
798    ldb+tdb file
799
800  - no need to HUP smbd to reload config
801
802  - how to handle configuration comments? same problem as SWAT
803
804
805 BUGS:
806   non-signed non-sealed RPC (level == 2 == "connect")
807   add a test case for last_entry_offset in trans2 find interfaces
808   conn refused
809   connect -> errno
810   no 137 resolution not possible
811   should not fallback to anon when pass supplied
812   should check pass-thu cap bit, and skip lots of tests
813   possibly allow the test suite to say "allow oversized replies" for
814      trans2 and other calls
815   handle servers that don't have the setattre call in torture
816   add max file coponent length test and max path len test
817
818