From 6576e9967ca570bc0348a0fff4899ad4fc7c6d87 Mon Sep 17 00:00:00 2001 From: Jelmer Vernooij Date: Sat, 5 Jun 2004 22:31:58 +0000 Subject: Replace entities with xi:include (This used to be commit 8b5fb7614c7fec9fba2c4bf0a3ffa93c4316b28d) --- docs/Makefile.in | 6 +- docs/devel/CodingSuggestions.xml | 6 + docs/devel/NetBIOS.xml | 6 + docs/devel/Tracing.xml | 6 + docs/devel/architecture.xml | 6 + docs/devel/cifsntdomain.xml | 6 + docs/devel/contributing.xml | 6 + docs/devel/debug.xml | 6 + docs/devel/encryption.xml | 6 + docs/devel/gencache.xml | 6 + docs/devel/index.xml | 64 +++---- docs/devel/internals.xml | 6 + docs/devel/modules.xml | 6 + docs/devel/packagers.xml | 6 + docs/devel/parsing.xml | 6 + docs/devel/printing.xml | 6 + docs/devel/registry.xml | 6 + docs/devel/rpc_plugin.xml | 6 + docs/devel/sam.xml | 357 --------------------------------------- docs/devel/unix-smb.xml | 6 + docs/devel/vfs.xml | 6 + docs/devel/windows-debug.xml | 6 + docs/devel/wins.xml | 6 + 23 files changed, 143 insertions(+), 404 deletions(-) delete mode 100644 docs/devel/sam.xml (limited to 'docs') diff --git a/docs/Makefile.in b/docs/Makefile.in index c5a2b0bb52..e6955d07e4 100644 --- a/docs/Makefile.in +++ b/docs/Makefile.in @@ -146,14 +146,10 @@ Samba-Guide.xml: $(GUIDEDOC)/guide-main.xml Samba-Developers-Guide.xml: $(DEVDOCDIR)/index.xml $(DEVDOCDIR_DEPS) $(XSLTPROC) --stringparam noreference 1 --xinclude --output $@ xslt/expand-sambadoc.xsl $< -$(HOWTODIR)/attributions.xml: $(HOWTODIR)/index.xml +%/attributions.xml: %/index.xml @echo "" > $@ # Make sure we don't get recursive dependencies, etc! $(XSLTPROC) --output $@ xslt/generate-attributions.xsl $< -$(DEVDOCDIR)/attributions.xml: $(DEVDOCDIR)/index.xml - @echo > $@ # Make sure we don't get recursive dependencies, etc! - $(XSLTPROC) --output $@ xslt/generate-attributions.xsl $< - clean: rm -rf $(OUTPUTDIR)/* rm -f *.xml $(MANPAGES) $(TXTDIR)/*.txt $(PSDIR)/*.ps \ diff --git a/docs/devel/CodingSuggestions.xml b/docs/devel/CodingSuggestions.xml index bdf6d3d17d..04465a1fcd 100644 --- a/docs/devel/CodingSuggestions.xml +++ b/docs/devel/CodingSuggestions.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/NetBIOS.xml b/docs/devel/NetBIOS.xml index 6b4eb34b76..6bfe0c8647 100644 --- a/docs/devel/NetBIOS.xml +++ b/docs/devel/NetBIOS.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/Tracing.xml b/docs/devel/Tracing.xml index ccf1e1c3c8..3868eaab7b 100644 --- a/docs/devel/Tracing.xml +++ b/docs/devel/Tracing.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/architecture.xml b/docs/devel/architecture.xml index 312a63af97..fb1fe52546 100644 --- a/docs/devel/architecture.xml +++ b/docs/devel/architecture.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/cifsntdomain.xml b/docs/devel/cifsntdomain.xml index 7c3c22d106..5e57833b69 100644 --- a/docs/devel/cifsntdomain.xml +++ b/docs/devel/cifsntdomain.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/contributing.xml b/docs/devel/contributing.xml index 4137a62053..a06dfd14db 100644 --- a/docs/devel/contributing.xml +++ b/docs/devel/contributing.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> &author.jelmer; diff --git a/docs/devel/debug.xml b/docs/devel/debug.xml index 7e81cc825d..f627833557 100644 --- a/docs/devel/debug.xml +++ b/docs/devel/debug.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/encryption.xml b/docs/devel/encryption.xml index 56a1d10c9c..0a1fbbbbed 100644 --- a/docs/devel/encryption.xml +++ b/docs/devel/encryption.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/gencache.xml b/docs/devel/gencache.xml index 1ba2f77c9d..265461c5e3 100644 --- a/docs/devel/gencache.xml +++ b/docs/devel/gencache.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/index.xml b/docs/devel/index.xml index 8a9e165a79..30e18b20ba 100644 --- a/docs/devel/index.xml +++ b/docs/devel/index.xml @@ -1,29 +1,10 @@ %globalentities; - - - - - - - - - - - - - - - - - - - - ]> - + SAMBA Developers Guide @@ -61,7 +42,7 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt Attributions - &attributions-dev; + @@ -72,46 +53,45 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt The protocol - &NetBIOS; - &unix-smb; - &cifsntdomain; + + + Samba Basics -&Architecture; -&debug; -&internals; -&CodingSuggestions; -&contributing; -&modules; + + + + + + Samba Subsystems - &sam; - &rpc-plugin; - &vfs; - ®istry; - &parsing; - &wins; - &encryption; + + + + + + Debugging and tracing -&Tracing; -&windows-deb; -&printing; + + + Appendices - &packagers; + diff --git a/docs/devel/internals.xml b/docs/devel/internals.xml index 982cfd2e10..7decd9d06c 100644 --- a/docs/devel/internals.xml +++ b/docs/devel/internals.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/modules.xml b/docs/devel/modules.xml index 171ee27f90..c14fda04dd 100644 --- a/docs/devel/modules.xml +++ b/docs/devel/modules.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/packagers.xml b/docs/devel/packagers.xml index fb47c7305c..a55f4c6581 100644 --- a/docs/devel/packagers.xml +++ b/docs/devel/packagers.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/parsing.xml b/docs/devel/parsing.xml index 8d929617f5..d989c97809 100644 --- a/docs/devel/parsing.xml +++ b/docs/devel/parsing.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/printing.xml b/docs/devel/printing.xml index 363b9fb6e5..cd29b5010b 100644 --- a/docs/devel/printing.xml +++ b/docs/devel/printing.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/registry.xml b/docs/devel/registry.xml index b331ebce7f..078e926de9 100644 --- a/docs/devel/registry.xml +++ b/docs/devel/registry.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> &author.jelmer; diff --git a/docs/devel/rpc_plugin.xml b/docs/devel/rpc_plugin.xml index 287e35b0be..478847b192 100644 --- a/docs/devel/rpc_plugin.xml +++ b/docs/devel/rpc_plugin.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/sam.xml b/docs/devel/sam.xml deleted file mode 100644 index 84c17d65e2..0000000000 --- a/docs/devel/sam.xml +++ /dev/null @@ -1,357 +0,0 @@ - - - - - AndrewBartlett - - 1 October 2002 - - -The Upcoming SAM System - - -Security in the 'new SAM' - -One of the biggest problems with passdb is it's implementation of -'security'. Access control is on a 'are you root at the moment' basis, -and it has no concept of NT ACLs. Things like ldapsam had to add -'magic' 'are you root' checks. - -We took this very seriously when we started work, and the new structure -is designed with this in mind, from the ground up. Each call to the SAM -has a NT_TOKEN and (if relevant) an 'access desired'. This is either -provided as a parameter, or implicitly supplied by the object being -accessed. - - -For example, when you call - - - -NTSTATUS sam_get_account_by_name(const SAM_CONTEXT *context, const -NT_USER_TOKEN *access_token, uint32 access_desired, const char *domain, -const char *name, SAM_ACCOUNT_HANDLE **account) - - - -The context can be NULL (and is used to allow import/export by setting -up 2 contexts, and allowing calls on both simultaneously) - - - -The access token *must* be specified. Normally the user's token out of -current_user, this can also be a global 'system' context. - - - -The access desired is as per the ACL, for passing to the seaccess stuff. - - - -The domain/username are standard. Even if we only have one domain, -keeping this ensures that we don't get 'unqualified' usernames (same -problem as we had with unqualified SIDs). - - - -We return a 'handle'. This is opaque to the rest of Samba, but is -operated on by get/set routines, all of which return NTSTATUS. - - - -The access checking is done by the SAM module. The reason it is not -done 'above' the interface is to ensure a 'choke point'. I put a lot of -effort into the auth subsystem to ensure we never 'accidentally' forgot -to check for null passwords, missed a restriction etc. I intend the SAM -to be written with the same caution. - - - -The reason the access checking is not handled by the interface itself is -due to the different implementations it make take on. For example, on -ADS, you cannot set a password over a non-SSL connection. Other -backends may have similar requirements - we need to leave this policy up -to the modules. They will naturally have access to 'helper' procedures -and good examples to avoid mishaps. - - - -(Furthermore, some backends my actually chose to push the whole ACL -issue to the remote server, and - assuming ldap for this example - bind -as the user directly) - - - -Each returned handle has an internal 'access permitted', which allows -the 'get' and 'set' routines to return 'ACCESS_DENIED' for things that -were not able to be retrieved from the backend. This removes the need -to specify the NT_TOKEN on every operation, and allows for 'object not -present' to be easily distinguished from 'access denied'. - - - -When you 'set' an object (calling sam_update_account) the internal -details are again used. Each change that has been made to the object -has been flagged, so as to avoid race conditions (on unmodified -components) and to avoid violating any extra ACL requirements on the -actual data store (like the LDAP server). - - - -Finally, we have generic get_sec_desc() and set_sec_desc() routines to -allow external ACL manipulation. These do lookups based on SID. - - - - - -Standalone from UNIX - - -One of the primary tenants of the 'new SAM' is that it would not attempt -to deal with 'what unix id for that'. This would be left to the 'SMS' -(Sid Mapping System') or SID farm, and probably administered via -winbind. We have had constructive discussion on how 'basic' unix -accounts like 'root' would be handled, and we think this can work. -Accounts not preexisting in unix would be served up via winbind. - - - -This is an *optional* part, and my preferred end-game. We have a fare -way to go before things like winbind up to it however. - - - - - -Handles and Races in the new SAM - - -One of the things that the 'new SAM' work has tried to face is both -compatibility with existing code, and a closer alignment to the SAMR -interface. I consider SAMR to be a 'primary customer' to the this work, -because if we get alignment with that wrong, things get more, rather -than less complex. Also, most other parts of Samba are much more -flexible with what they can allow. - - - -In any case, that was a decision taken as to how the general design -would progress. BTW, my understanding of SAMR may be completely flawed. - - - -One of the most race-prone areas of the new code is the conflicting -update problem. We have taken two approaches: - - - - -'Not conflicting' conflicts. Due to the way usrmgr operates, it will -open a user, display all the properties and *save* them all, even if you -don't change any. - - - -For this, see what I've done in rpc_server/srv_samr_util.c. I intend -to take this one step further, and operate on the 'handle' that the -values were read from. This should mean that we only update things that -have *really* changed. - - - - - -'conflicting' updates: Currently we don't deal with this (in passdb -or the new sam stuff), but the design is sufficiently flexible to 'deny' -a second update. I don't foresee locking records however. - - - - - - - -Layers - - -Application - - -This is where smbd, samtest and whatever end-user replacement we have -for pdbedit sits. They use only the SAM interface, and do not get -'special knowledge' of what is below them. - - - -SAM Interface - - -This level 'owns' the various handle structures, the get/set routines on -those structures and provides the public interface. The application -layer may initialize a 'context' to be passed to all interface routines, -else a default, self-initialising context will be supplied. This layser -finds the appropriate backend module for the task, and tries very hard -not to need to much 'knowledge'. It should just provide the required -abstraction to the modules below, and arrange for their initial loading. - - - -We could possibly add ACL checking at this layer, to avoid discrepancies -in implementation modules. - - - - - -SAM Modules - - -These do not communicate with the application directly, only by setting -values in the handles, and receiving requests from the interface. These -modules are responsible for translating values from the handle's -.private into (say) an LDAP modification list. The module is expected -to 'know' things like it's own domain SID, domain name, and any other -state attached to the SAM. Simpler modules may call back to some helper -routine. - - - - - - -SAM Modules - - -Special Module: sam_passdb - - -In order for there to be a smooth transition, kai is writing a module -that reads existing passdb backends, and translates them into SAM -replies. (Also pulling data from the account policy DB etc). We also -intend to write a module that does the reverse - gives the SAM a passdb -interface. - - - - -sam_ads - -This is the first of the SAM modules to be committed to the tree - -mainly because I needed to coordinate work with metze (who authored most -of it). This module aims to use Samba's libads code to provide an -Active Directory LDAP client, suitable for use on a mixed-mode DC. -While it is currently being tested against Win2k servers (with a -password in the smb.conf file) it is expected to eventually use a -(possibly modified) OpenLDAP server. We hope that this will assist in -the construction of an Samba AD DC. - - - -We also intend to construct a Samba 2.2/3.0 compatible ldap module, -again using libads code. - - - - - -Memory Management - - -The 'new SAM' development effort also concerned itself with getting a -sane implementation of memory management. It was decided that we would -be (as much as possible) talloc based, using an 'internal talloc -context' on many objects. That is, the creation of an object would -initiate it's own internal talloc context, and this would be used for -all operations on that object. Much of this is already implemented in -passdb. Also, like passdb, it will be possible to specify that some -object actually be created on a specified context. - - - -Memory management is important here because the APIs in the 'new SAM' do -not use 'pdb_init()' or an equivalent. They always allocate new -objects. Enumeration's are slightly different, and occur on a supplied -context that 'owns' the entire list, rather than per-element. (the -enumeration functions return an array of all elements - not full handles -just basic (and public) info) Likewise for things that fill in a char -**. - - -For example: - - -NTSTATUS sam_lookup_sid(const SAM_CONTEXT *context, const NT_USER_TOKEN -*access_token, TALLOC_CTX *mem_ctx, const DOM_SID *sid, char **name, -uint32 *type) - - -Takes a context to allocate the 'name' on, while: - - -NTSTATUS sam_get_account_by_sid(const SAM_CONTEXT *context, const -NT_USER_TOKEN *access_token, uint32 access_desired, const DOM_SID -*accountsid, SAM_ACCOUNT_HANDLE **account) - - -Allocates a handle and stores the allocation context on that handle. - -I think that the following: - - -NTSTATUS sam_enum_accounts(const SAM_CONTEXT *context, const -NT_USER_TOKEN *access_token, const DOM_SID *domainsid, uint16 acct_ctrl, -int32 *account_count, SAM_ACCOUNT_ENUM **accounts) - - - - - -Testing - - -Testing is vital in any piece of software, and Samba is certainly no -exception. In designing this new subsystem, we have taken care to ensure -it is easily tested, independent of outside protocols. - - - -To this end, Jelmer has constructed 'samtest'. - - - -This utility (see torture/samtest.c) is structured like rpcclient, but -instead operates on the SAM subsystem. It creates a 'custom' SAM -context, that may be distinct from the default values used by the rest -of the system, and can load a separate configuration file. - - - -A small number of commands are currently implemented, but these have -already proved vital in testing. I expect SAM module authors will find -it particularly valuable. - - -Example useage: - -$ bin/samtest - - -> context ads:ldap://192.168.1.96 - -(this loads a new context, using the new ADS module. The parameter is -the 'location' of the ldap server) - - - -> lookup_name DOMAIN abartlet - -(returns a sid). - - - -Because the 'new SAM' is NT ACL based, there will be a command to -specify an arbitrary NT ACL, but for now it uses 'system' by default. - - - diff --git a/docs/devel/unix-smb.xml b/docs/devel/unix-smb.xml index d6a658089c..80a6b67649 100644 --- a/docs/devel/unix-smb.xml +++ b/docs/devel/unix-smb.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/vfs.xml b/docs/devel/vfs.xml index eca5ef3d80..6819faf05d 100644 --- a/docs/devel/vfs.xml +++ b/docs/devel/vfs.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> diff --git a/docs/devel/windows-debug.xml b/docs/devel/windows-debug.xml index 3535c38dbd..27ffbc063c 100644 --- a/docs/devel/windows-debug.xml +++ b/docs/devel/windows-debug.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> &author.jelmer; diff --git a/docs/devel/wins.xml b/docs/devel/wins.xml index 53410316c5..ad3ad67b42 100644 --- a/docs/devel/wins.xml +++ b/docs/devel/wins.xml @@ -1,3 +1,9 @@ + + + %global_entities; +]> -- cgit