X-Git-Url: http://git.samba.org/?p=samba.git;a=blobdiff_plain;f=prog_guide.txt;h=05d1bc614033b65c29d779e9584e91c18740cdea;hp=9539e1e5c1922261ae87cc24cf132d7d1db9d3e8;hb=12d8b02f441eb4d8e70b2164ea4636796777becb;hpb=c58c7ea1799ba58af67f8507566f932b68bde545 diff --git a/prog_guide.txt b/prog_guide.txt index 9539e1e5c19..05d1bc61403 100644 --- a/prog_guide.txt +++ b/prog_guide.txt @@ -1,3 +1,5 @@ + + THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET. @@ -188,44 +190,11 @@ in the data and bss columns in "size" anyway (it will be included in "text"). So you can have constant tables of protocol data. -Memory Contexts ---------------- - -We introduced the talloc() system for memory contexts during the 2.2 -development cycle and it has been a great success. It has greatly -simplified a lot of our code, particularly with regard to error -handling. - -In Samba4 we use talloc even more extensively to give us much finer -grained memory management. The really important thing to remember -about talloc in Samba4 is: - - "don't just use the first talloc context that comes to hand - use - the RIGHT talloc context" - -Just using the first talloc context that comes to hand is probably the -most common systematic bug I have seen so far from programmers that -have worked on the Samba4 code base. The reason this is vital is that -different talloc contexts have vastly different lifetimes, so if you -use a talloc context that has a long lifetime (such as one associated -with a tree connection) for data that is very short lived (such as -parsing an individual packet) then you have just introduced a huge -memory leak. - -In fact, it is quite common that the correct thing to do is to create -a new talloc context for some little function and then destroy it when -you are done. That will give you a memory context that has exactly the -right lifetime. - -You should also go and look at a new talloc function in Samba4 called -talloc_steal(). By using talloc_steal() you can move a lump of memory -from one memory context to another without copying the data. This -should be used when a backend function (such as a packet parser) -produces a result as a lump of talloc memory and you need to keep it -around for a longer lifetime than the talloc context it is in. You -just "steal" the memory from the short-lived context, putting it into -your long lived context. +How to use talloc +----------------- +Please see the separate document, talloc_guide.txt in this +directory. You _must_ read this if you want to program in Samba4. Interface Structures -------------------- @@ -556,11 +525,13 @@ string. The format is: - TRANSPORT:host:[flags] + TRANSPORT:host[flags] where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP -"host" is an IP or hostname or netbios name +"host" is an IP or hostname or netbios name. If the binding string +identifies the server side of an endpoint, "host" may be an empty +string. "flags" can include a SMB pipe name if using the ncacn_np transport or a TCP port number if using the ncacn_ip_tcp transport, otherwise they @@ -570,37 +541,49 @@ other recognised flags are: sign : enable ntlmssp signing seal : enable ntlmssp sealing + connect : enable rpc connect level auth (auth, but no sign or seal) validate: enable the NDR validator print: enable debugging of the packets bigendian: use bigendian RPC + padcheck: check reply data for non-zero pad bytes For example, these all connect to the samr pipe: ncacn_np:myserver - ncacn_np:myserver:samr - ncacn_np:myserver:samr,seal - ncacn_np:myserver:\pipe\samr - ncacn_np:myserver:/pipe/samr ncacn_np:myserver[samr] ncacn_np:myserver[\pipe\samr] ncacn_np:myserver[/pipe/samr] - ncacn_np:myserver:[samr,sign,print] - ncacn_np:myserver:[\pipe\samr,sign,seal,bigendian] - ncacn_np:myserver:[/pipe/samr,seal,validate] + ncacn_np:myserver[samr,sign,print] + ncacn_np:myserver[\pipe\samr,sign,seal,bigendian] + ncacn_np:myserver[/pipe/samr,seal,validate] + ncacn_np: + ncacn_np:[/pipe/samr] ncacn_ip_tcp:myserver - ncacn_ip_tcp:myserver:1024 ncacn_ip_tcp:myserver[1024] - ncacn_ip_tcp:myserver:[1024,sign,seal] + ncacn_ip_tcp:myserver[1024,sign,seal] IDEA: Maybe extend UNC names like this? smbclient //server/share - smbclient //server/share:[sign,seal,spnego] + smbclient //server/share[sign,seal,spnego] +DCERPC Handles +-------------- +The various handles that are used in the RPC servers should be created and +fetch using the dcesrv_handle_* functions. + +Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain +a new handle of the specified type. Handle types are unique within each +pipe. +The handle can later be fetched again using +struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type) +and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *). + +User data should be stored in the 'data' member of the dcesrv_handle struct. MSRPC @@ -619,8 +602,6 @@ MSRPC - msrpc -- use _p talloc varients - don't zero structures! avoid ZERO_STRUCT() and talloc_zero() @@ -630,8 +611,6 @@ put in full UNC path in tconx test timezone handling by using a server in different zone from client -don't just use any old TALLOC_CTX, use the right one! - do {} while (0) system NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR() @@ -639,8 +618,6 @@ NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR() need to implement secondary parts of trans2 and nttrans in server and client -add talloc_steal() to move a talloc ptr from one pool to another - document access_mask in openx reply check all capabilities and flag1, flag2 fields (eg. EAs) @@ -742,4 +719,63 @@ docs developer docs svn instructions -test commit + +Ideas +----- + + - store all config in config.ldb + + - load from smb.conf if modtime changes + + - dump full system config with ldbsearch + + - will need the ability to form a ldif difference file + + - advanced web admin via a web ldb editor + + - normal web admin via web forms -> ldif + + - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc + + - subsystems in smbd will load config parameters for a share + using ldbsearch at tconx time + + - need a loadparm equivalent module that provides parameter defaults + + - start smbd like this: "smbd -C tdb://etc/samba/config.ldb" or + "smbd -C ldapi://var/run/ldapi" + + - write a tool that generates a template ldap schema from an existing + ldb+tdb file + + - no need to HUP smbd to reload config + + - how to handle configuration comments? same problem as SWAT + + +BUGS: + add a test case for last_entry_offset in trans2 find interfaces + conn refused + connect -> errno + no 137 resolution not possible + should not fallback to anon when pass supplied + should check pass-thu cap bit, and skip lots of tests + possibly allow the test suite to say "allow oversized replies" for + trans2 and other calls + handle servers that don't have the setattre call in torture + add max file coponent length test and max path len test + +case-insenstive idea: + all filenames on disk lowercase + real case in extended attribute + keep cache of what dirs are all lowercase + when searching for name, don't search if dir is definately all lowercase + when creating file, use dnotify to tell if someone else creates at + same time + +solve del *.* idea: + make mangle cache dynamic size + fill during a dir scan + setup a timer + destroy cache after 30 sec + destroy if a 2nd dir scan happens on same dir