mirror of
https://github.com/samba-team/samba.git
synced 2025-02-24 13:57:43 +03:00
Fix Makefile.in (use variables instead of directory names, don't try to put files in ../../htmldocs, etc)
Add sam.sgml
This commit is contained in:
Jelmer Vernooij
-
parent
598039599c
commit
dfb3ee0bb6
@ -38,9 +38,13 @@ HTMLDOC = @HTMLDOC@
|
||||
SRCDIR = @srcdir@
|
||||
MANDIR=../manpages
|
||||
HTMLDIR=../htmldocs
|
||||
MANSGMLDIR = manpages/
|
||||
SGMLDIR = projdoc/
|
||||
MANPROJDOC = manpages/
|
||||
PROJDOC = projdoc/
|
||||
DEVDOC = devdoc/
|
||||
PERL = @PERL@
|
||||
PSDIR = ..
|
||||
PDFDIR = ..
|
||||
TXTDIR = ../textdocs
|
||||
|
||||
MANPAGES=$(patsubst %,$(MANDIR)/%,$(MANPAGES_NAMES))
|
||||
MANPAGES_HTML=$(patsubst %,$(HTMLDIR)/%.html,$(MANPAGES_NAMES))
|
||||
@ -55,55 +59,68 @@ all:
|
||||
@echo "html - Build HTML version of HOWTO Collection"
|
||||
@echo "htmlman - Build html version of manpages"
|
||||
@echo "txt - Build plain text version of HOWTO Collection"
|
||||
@echo "everything - Build all of the above"
|
||||
|
||||
everything: manpages ps pdf html-single html htmlman txt
|
||||
|
||||
# Global rules
|
||||
|
||||
manpages: $(MANPAGES)
|
||||
pdf: ../Samba-HOWTO-Collection.pdf ../Samba-Developers-Guide.pdf
|
||||
ps: ../Samba-HOWTO-Collection.ps ../Samba-Developers-Guide.ps
|
||||
txt: ../textdocs/Samba-HOWTO-Collection.txt ../textdocs/Samba-Developers-Guide.txt
|
||||
pdf: $(PDFDIR)/Samba-HOWTO-Collection.pdf ../Samba-Developers-Guide.pdf
|
||||
ps: $(PSDIR)/Samba-HOWTO-Collection.ps ../Samba-Developers-Guide.ps
|
||||
txt: $(TXTDIR)/Samba-HOWTO-Collection.txt $(TXTDIR)/Samba-Developers-Guide.txt
|
||||
htmlman: $(MANPAGES_HTML)
|
||||
html-single: ../$(HTMLDIR)/Samba-HOWTO-Collection.html ../$(HTMLDIR)/Samba-Developers-Guide.html
|
||||
html-single: $(HTMLDIR)/Samba-HOWTO-Collection.html $(HTMLDIR)/Samba-Developers-Guide.html
|
||||
html:
|
||||
$(DOCBOOK2HTML) -d samba.dsl -o $(HTMLDIR) projdoc/samba-doc.sgml
|
||||
|
||||
../Samba-HOWTO-Collection.txt: $(SGMLDIR)/samba-doc.sgml
|
||||
$(DOCBOOK2TXT) -o .. $<
|
||||
mv ../samba-doc.txt $@
|
||||
# Text files
|
||||
|
||||
../Samba-Developers-Guide.txt: $(SGMLDIR)/samba-doc.sgml
|
||||
$(DOCBOOK2TXT) -o .. $<
|
||||
mv ../samba-doc.txt $@
|
||||
$(TXTDIR)/Samba-HOWTO-Collection.txt: $(PROJDOC)/samba-doc.sgml
|
||||
$(DOCBOOK2TXT) -o . $<
|
||||
mv ./samba-doc.txt $@
|
||||
|
||||
../Samba-HOWTO-Collection.ps: $(SGMLDIR)/samba-doc.sgml
|
||||
$(DOCBOOK2PS) -o .. $<
|
||||
mv ../samba-doc.ps $@
|
||||
$(TXTDIR)/Samba-Developers-Guide.txt: $(PROJDOC)/samba-doc.sgml
|
||||
$(DOCBOOK2TXT) -o . $<
|
||||
mv ./samba-doc.txt $@
|
||||
|
||||
../Samba-Developers-Guide.ps: $(SGMLDIR)/samba-doc.sgml
|
||||
$(DOCBOOK2PS) -o .. $<
|
||||
mv ../samba-doc.ps $@
|
||||
# PostScript
|
||||
|
||||
../Samba-HOWTO-Collection.pdf: ../$(HTMLDIR)/Samba-HOWTO-Collection.html
|
||||
$(PSDIR)/Samba-HOWTO-Collection.ps: $(PROJDOC)/samba-doc.sgml
|
||||
$(DOCBOOK2PS) -o . $<
|
||||
mv ./samba-doc.ps $@
|
||||
|
||||
$(PSDIR)/Samba-Developers-Guide.ps: $(PROJDOC)/samba-doc.sgml
|
||||
$(DOCBOOK2PS) -o . $<
|
||||
mv ./samba-doc.ps $@
|
||||
|
||||
# Adobe PDF files
|
||||
|
||||
$(PDFDIR)/Samba-HOWTO-Collection.pdf: $(HTMLDIR)/Samba-HOWTO-Collection.html
|
||||
$(HTMLDOC) --book --color --links -f $@ $<
|
||||
|
||||
../Samba-Developers-Guide.pdf: ../$(HTMLDIR)/Samba-Developers-Guide.html
|
||||
$(PDFDIR)/Samba-Developers-Guide.pdf: $(HTMLDIR)/Samba-Developers-Guide.html
|
||||
$(HTMLDOC) --book --color --links -f $@ $<
|
||||
|
||||
../$(HTMLDIR)/Samba-HOWTO-Collection.html: $(SGMLDIR)/samba-doc.sgml
|
||||
$(DOCBOOK2HTML) -u -o .. $<
|
||||
mv ../samba-doc.html $@
|
||||
# Single large HTML files
|
||||
|
||||
../$(HTMLDIR)/Samba-Developers-Guide.html: devdoc/dev-doc.sgml
|
||||
$(DOCBOOK2HTML) -u -o .. $<
|
||||
mv ../dev-doc.html $@
|
||||
$(HTMLDIR)/Samba-HOWTO-Collection.html: $(PROJDOC)/samba-doc.sgml
|
||||
$(DOCBOOK2HTML) -u -o . $<
|
||||
mv ./samba-doc.html $@
|
||||
|
||||
$(HTMLDIR)/Samba-Developers-Guide.html: $(DEVDOC)/dev-doc.sgml
|
||||
$(DOCBOOK2HTML) -u -o . $<
|
||||
mv ./dev-doc.html $@
|
||||
|
||||
|
||||
$(HTMLDIR)/%.html: $(MANSGMLDIR)/%.sgml
|
||||
$(DOCBOOK2HTML) -o $(HTMLDIR) $<
|
||||
mv $(HTMLDIR)/index.html $@
|
||||
$(HTMLDIR)/%.html: $(MANPROJDOC)/%.sgml
|
||||
$(DOCBOOK2HTML) -o . $<
|
||||
mv ./index.html $@
|
||||
|
||||
$(MANDIR)/%: $(MANSGMLDIR)/%.sgml
|
||||
$(MANDIR)/%: $(MANPROJDOC)/%.sgml
|
||||
$(DOCBOOK2MAN) -o $(MANDIR) $< || rm $@
|
||||
$(PERL) scripts/strip-links.pl < $@ > $@.temp
|
||||
mv $@.temp $@
|
||||
|
||||
clean:
|
||||
rm -f $(MANPAGES) $(MANPAGES_HTML) ../$(HTMLDIR)/*.html ../Samba-HOWTO-Collection.p* ../Samba-Developers-Guide.p*
|
||||
rm -f $(MANPAGES) $(MANPAGES_HTML) $(HTMLDIR)/*.html $(TXTDIR)/*.txt $(PSDIR)/*.ps $(PDFDIR)/*.pdf
|
||||
|
||||
@ -10,6 +10,7 @@
|
||||
<!ENTITY cifsntdomain SYSTEM "cifsntdomain.sgml">
|
||||
<!ENTITY printing SYSTEM "printing.sgml">
|
||||
<!ENTITY wins SYSTEM "wins.sgml">
|
||||
<!ENTITY sam SYSTEM "sam.sgml">
|
||||
]>
|
||||
|
||||
<book id="Samba-Developer-Documentation">
|
||||
@ -62,5 +63,6 @@ url="http://www.fsf.org/licenses/gpl.txt">http://www.fsf.org/licenses/gpl.txt</u
|
||||
&cifsntdomain;
|
||||
&printing;
|
||||
&wins;
|
||||
&sam;
|
||||
|
||||
</book>
|
||||
|
||||
357
docs/docbook/devdoc/sam.sgml
Normal file
357
docs/docbook/devdoc/sam.sgml
Normal file
@ -0,0 +1,357 @@
|
||||
<chapter id="sam">
|
||||
|
||||
<chapterinfo>
|
||||
<author>
|
||||
<firstname>Andrew</firstname><surname>Bartlett</surname>
|
||||
</author>
|
||||
<pubdate>1 October 2002</pubdate>
|
||||
</chapterinfo>
|
||||
|
||||
<title>The Upcoming SAM System</title>
|
||||
|
||||
<sect1>
|
||||
<title>Security in the 'new SAM'</title>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>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.</para>
|
||||
|
||||
<para>
|
||||
For example, when you call
|
||||
</para>
|
||||
|
||||
<programlisting><
|
||||
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)
|
||||
</programlisting>
|
||||
|
||||
<para>
|
||||
The context can be NULL (and is used to allow import/export by setting
|
||||
up 2 contexts, and allowing calls on both simultaneously)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The access token *must* be specified. Normally the user's token out of
|
||||
current_user, this can also be a global 'system' context.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
The access desired is as per the ACL, for passing to the seaccess stuff.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
(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)
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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'.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
Finally, we have generic get_sec_desc() and set_sec_desc() routines to
|
||||
allow external ACL manipulation. These do lookups based on SID.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Standalone from UNIX</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Handles and Races in the new SAM</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
One of the most race-prone areas of the new code is the conflicting
|
||||
update problem. We have taken two approaches:
|
||||
</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>'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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>
|
||||
'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.
|
||||
</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Layers</title>
|
||||
|
||||
<sect2>
|
||||
<title>Application</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<sect2>
|
||||
<title>SAM Interface</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We could possibly add ACL checking at this layer, to avoid discrepancies
|
||||
in implementation modules.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>SAM Modules</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>SAM Modules</title>
|
||||
|
||||
<sect2>
|
||||
<title>Special Module: sam_passdb</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect2>
|
||||
|
||||
<sect2>
|
||||
<title>sam_ads</title>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
We also intend to construct a Samba 2.2/3.0 compatible ldap module,
|
||||
again using libads code.
|
||||
</para>
|
||||
</sect2>
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Memory Management</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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
|
||||
**.
|
||||
</para>
|
||||
|
||||
<para>For example:</para>
|
||||
|
||||
<para><programlisting>
|
||||
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)
|
||||
</programlisting></para>
|
||||
|
||||
<para>Takes a context to allocate the 'name' on, while:</para>
|
||||
|
||||
<para><programlisting>
|
||||
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)
|
||||
</programlisting></para>
|
||||
|
||||
<para>Allocates a handle and stores the allocation context on that handle.</para>
|
||||
|
||||
<para>I think that the following:</para>
|
||||
|
||||
<para><programlisting>
|
||||
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)
|
||||
</programlisting></para>
|
||||
|
||||
</sect1>
|
||||
|
||||
<sect1>
|
||||
<title>Testing</title>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
To this end, Jelmer has constructed 'samtest'.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>Example useage:</para>
|
||||
|
||||
<para><prompt>$</prompt> <command>bin/samtest</command></para>
|
||||
|
||||
<para><programlisting>
|
||||
> context ads:ldap://192.168.1.96
|
||||
</programlisting>
|
||||
(this loads a new context, using the new ADS module. The parameter is
|
||||
the 'location' of the ldap server)
|
||||
</para>
|
||||
|
||||
<para><programlisting>
|
||||
> lookup_name DOMAIN abartlet
|
||||
</programlisting>
|
||||
(returns a sid).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
Loading…
x
Reference in New Issue
Block a user