diff options
Diffstat (limited to 'docs/docbook')
| -rw-r--r-- | docs/docbook/devdoc/sam.sgml | 357 | ||||
| -rw-r--r-- | docs/docbook/faq/clientapp.sgml | 101 | ||||
| -rw-r--r-- | docs/docbook/faq/general.sgml | 168 | ||||
| -rw-r--r-- | docs/docbook/faq/install.sgml | 330 | ||||
| -rw-r--r-- | docs/docbook/projdoc/ADS-HOWTO.sgml | 195 |
5 files changed, 1151 insertions, 0 deletions
diff --git a/docs/docbook/devdoc/sam.sgml b/docs/docbook/devdoc/sam.sgml new file mode 100644 index 0000000000..654bd5fe9c --- /dev/null +++ b/docs/docbook/devdoc/sam.sgml @@ -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> diff --git a/docs/docbook/faq/clientapp.sgml b/docs/docbook/faq/clientapp.sgml new file mode 100644 index 0000000000..6d687bf772 --- /dev/null +++ b/docs/docbook/faq/clientapp.sgml @@ -0,0 +1,101 @@ +<chapter id="ClientApp"> +<title>Specific client application problems</title> + +<sect1> +<title>MS Office Setup reports "Cannot change properties of '\MSOFFICE\SETUP.INI'"</title> +<para> +When installing MS Office on a Samba drive for which you have admin +user permissions, ie. admin users = username, you will find the +setup program unable to complete the installation. +</para> + +<para> +To get around this problem, do the installation without admin user +permissions The problem is that MS Office Setup checks that a file is +rdonly by trying to open it for writing. +</para> + +<para> +Admin users can always open a file for writing, as they run as root. +You just have to install as a non-admin user and then use "chown -R" +to fix the owner. +</para> + +</sect1> + +<sect1> +<title>How to use a Samba share as an administrative share for MS Office, etc.</title> + +<para> +Microsoft Office products can be installed as an administrative installation +from which the application can either be run off the administratively installed +product that resides on a shared resource, or from which that product can be +installed onto workstation clients. +</para> + +<para> +The general mechanism for implementing an adminstrative installation involves +running <command>X:\setup /A</command>, where X is the drive letter of either CDROM or floppy. +</para> + +<para> +This installation process will NOT install the product for use per se, but +rather results in unpacking of the compressed distribution files into a target +shared folder. For this process you need write privilidge to the share and it +is desirable to enable file locking and share mode operation during this +process. +</para> + +<para> +Subsequent installation of MS Office from this share will FAIL unless certain +precautions are taken. This failure will be caused by share mode operation +which will prevent the MS Office installation process from re-opening various +dynamic link library files and will cause sporadic file not found problems. +</para> + +<itemizedlist> +<listitem><para> +As soon as the administrative installation (unpacking) has completed +set the following parameters on the share containing it: +</para> + +<para><programlisting> + [MSOP95] + path = /where_you_put_it + comment = Your comment + volume = "The_CD_ROM_Label" + read only = yes + available = yes + share modes = no + locking = no + browseable = yes + public = yes +</programlisting></para> + +</listitem> + +<listitem> +<para>Now you are ready to run the setup program from the Microsoft Windows +workstation as follows: <command>\\"Server_Name"\MSOP95\msoffice\setup</command> +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1> +<title>Microsoft Access database opening errors</title> + +<para> +Here are some notes on running MS-Access on a Samba drive from <ulink url="stefank@esi.com.au">Stefan Kjellberg</ulink> +</para> + +<para><simplelist> +<member>Opening a database in 'exclusive' mode does NOT work. Samba ignores r/w/share modes on file open.</member> +<member>Make sure that you open the database as 'shared' and to 'lock modified records'</member> +<member>Of course locking must be enabled for the particular share (smb.conf)</member> +</simplelist> +</para> + +</sect1> +</chapter> diff --git a/docs/docbook/faq/general.sgml b/docs/docbook/faq/general.sgml new file mode 100644 index 0000000000..5111e69bec --- /dev/null +++ b/docs/docbook/faq/general.sgml @@ -0,0 +1,168 @@ +<chapter id="general"> +<title>General Information</title> + +<sect1> +<title>Where can I get it?</title> +<para> +The Samba suite is available at the <ulink url="http://samba.org/">samba website</ulink>. +</sect1> + +<sect1> +<title>What do the version numbers mean?</title> +<para> +It is not recommended that you run a version of Samba with the word +"alpha" in its name unless you know what you are doing and are willing +to do some debugging. Many, many people just get the latest +recommended stable release version and are happy. If you are brave, by +all means take the plunge and help with the testing and development - +but don't install it on your departmental server. Samba is typically +very stable and safe, and this is mostly due to the policy of many +public releases. +</para> + +<para> +How the scheme works: +<simplelist> +<member>When major changes are made the version number is increased. For +example, the transition from 1.9.15 to 1.9.16. However, this version +number will not appear immediately and people should continue to use +1.9.15 for production systems (see next point.)</member> + +<member>Just after major changes are made the software is considered +unstable, and a series of alpha releases are distributed, for example +1.9.16alpha1. These are for testing by those who know what they are +doing. The "alpha" in the filename will hopefully scare off those who +are just looking for the latest version to install.</member> + +<member>When Andrew thinks that the alphas have stabilised to the point +where he would recommend new users install it, he renames it to the +same version number without the alpha, for example 1.9.16.</member> + +<member>Inevitably bugs are found in the "stable" releases and minor patch +levels are released which give us the pXX series, for example 1.9.16p2.</member> +</simplelist> + +<para> +So the progression goes: + +<programlisting> +1.9.15p7 (production) +1.9.15p8 (production) +1.9.16alpha1 (test sites only) +: +1.9.16alpha20 (test sites only) +1.9.16 (production) +1.9.16p1 (production) +</programlisting> +</para> + +<para> +The above system means that whenever someone looks at the samba ftp +site they will be able to grab the highest numbered release without an +alpha in the name and be sure of getting the current recommended +version. +</para> + +</sect1> + +<sect1> +<title>What platforms are supported?</title> +<para> +Many different platforms have run Samba successfully. The platforms +most widely used and thus best tested are Linux and SunOS.</para> + +<para> +At time of writing, there is support (or has been support for in earlier +versions): +</para> + +<simplelist> +<member>A/UX 3.0</member> +<member>AIX</member> +<member>Altos Series 386/1000</member> +<member>Amiga</member> +<member>Apollo Domain/OS sr10.3</member> +<member>BSDI </member> +<member>B.O.S. (Bull Operating System)</member> +<member>Cray, Unicos 8.0</member> +<member>Convex</member> +<member>DGUX. </member> +<member>DNIX.</member> +<member>FreeBSD</member> +<member>HP-UX</member> +<member>Intergraph. </member> +<member>Linux with/without shadow passwords and quota</member> +<member>LYNX 2.3.0</member> +<member>MachTen (a unix like system for Macintoshes)</member> +<member>Motorola 88xxx/9xx range of machines</member> +<member>NetBSD</member> +<member>NEXTSTEP Release 2.X, 3.0 and greater (including OPENSTEP for Mach).</member> +<member>OS/2 using EMX 0.9b</member> +<member>OSF1</member> +<member>QNX 4.22</member> +<member>RiscIX. </member> +<member>RISCOs 5.0B</member> +<member>SEQUENT. </member> +<member>SCO (including: 3.2v2, European dist., OpenServer 5)</member> +<member>SGI.</member> +<member>SMP_DC.OSx v1.1-94c079 on Pyramid S series</member> +<member>SONY NEWS, NEWS-OS (4.2.x and 6.1.x)</member> +<member>SUNOS 4</member> +<member>SUNOS 5.2, 5.3, and 5.4 (Solaris 2.2, 2.3, and '2.4 and later')</member> +<member>Sunsoft ISC SVR3V4</member> +<member>SVR4</member> +<member>System V with some berkely extensions (Motorola 88k R32V3.2).</member> +<member>ULTRIX.</member> +<member>UNIXWARE</member> +<member>UXP/DS</member> +</simplelist> + +</sect1> + +<sect1> +<title>How do I subscribe to the Samba Mailing Lists?</title> +<para> +Look at <ulink url="http://samba.org/samba/archives.html">the samba mailing list page</ulink> +</para> +</sect1> + +<sect1> +<title>Pizza supply details</title> +<para> +Those who have registered in the Samba survey as "Pizza Factory" will +already know this, but the rest may need some help. Andrew doesn't ask +for payment, but he does appreciate it when people give him +pizza. This calls for a little organisation when the pizza donor is +twenty thousand kilometres away, but it has been done. +<?para> + +<para> +Method 1: Ring up your local branch of an international pizza chain +and see if they honour their vouchers internationally. Pizza Hut do, +which is how the entire Canberra Linux Users Group got to eat pizza +one night, courtesy of someone in the US. +</para> + +<para> +Method 2: Ring up a local pizza shop in Canberra and quote a credit +card number for a certain amount, and tell them that Andrew will be +collecting it (don't forget to tell him.) One kind soul from Germany +did this. +</para> + +<para> +Method 3: Purchase a pizza voucher from your local pizza shop that has +no international affiliations and send it to Andrew. It is completely +useless but he can hang it on the wall next to the one he already has +from Germany :-) +</para> + +<para> +Method 4: Air freight him a pizza with your favourite regional +flavours. It will probably get stuck in customs or torn apart by +hungry sniffer dogs but it will have been a noble gesture. +</para> + +</sect1> + +</chapter> diff --git a/docs/docbook/faq/install.sgml b/docs/docbook/faq/install.sgml new file mode 100644 index 0000000000..288e3a5f32 --- /dev/null +++ b/docs/docbook/faq/install.sgml @@ -0,0 +1,330 @@ +<chapter id="Install"> +<title>Compiling and installing Samba on a Unix host</title> + +<sect1> +<title>I can't see the Samba server in any browse lists!</title> +<para> +See Browsing.html in the docs directory of the samba source +for more information on browsing. +</para> + +<para> +If your GUI client does not permit you to select non-browsable +servers, you may need to do so on the command line. For example, under +Lan Manager you might connect to the above service as disk drive M: +thusly: +<programlisting> + net use M: \\mary\fred +</programlisting> +The details of how to do this and the specific syntax varies from +client to client - check your client's documentation. +</para> + +<sect1> +<title>Some files that I KNOW are on the server doesn't show up when I view the files from my client! +<para>See the next question.</para> +</sect1> + +<sect1> +<title>Some files on the server show up with really wierd filenames when I view the files from my client!</title> +<para> +If you check what files are not showing up, you will note that they +are files which contain upper case letters or which are otherwise not +DOS-compatible (ie, they are not legal DOS filenames for some reason). +</para> + +<para> +The Samba server can be configured either to ignore such files +completely, or to present them to the client in "mangled" form. If you +are not seeing the files at all, the Samba server has most likely been +configured to ignore them. Consult the man page smb.conf(5) for +details of how to change this - the parameter you need to set is +"mangled names = yes". +</para> +</sect1> + +<sect1> +<title>My client reports "cannot locate specified computer" or similar</title> +<para> +This indicates one of three things: You supplied an incorrect server +name, the underlying TCP/IP layer is not working correctly, or the +name you specified cannot be resolved. +</para> + +<para> +After carefully checking that the name you typed is the name you +should have typed, try doing things like pinging a host or telnetting +to somewhere on your network to see if TCP/IP is functioning OK. If it +is, the problem is most likely name resolution. +</para> + +<para> +If your client has a facility to do so, hardcode a mapping between the +hosts IP and the name you want to use. For example, with Lan Manager +or Windows for Workgroups you would put a suitable entry in the file +LMHOSTS. If this works, the problem is in the communication between +your client and the netbios name server. If it does not work, then +there is something fundamental wrong with your naming and the solution +is beyond the scope of this document. +</para> + +<para> +If you do not have any server on your subnet supplying netbios name +resolution, hardcoded mappings are your only option. If you DO have a +netbios name server running (such as the Samba suite's nmbd program), +the problem probably lies in the way it is set up. Refer to Section +Two of this FAQ for more ideas. +</para> + +<para> +By the way, remember to REMOVE the hardcoded mapping before further +tests :-) +</para> + +</sect1> + +<sect1> +<title>My client reports "cannot locate specified share name" or similar</title> +<para> +This message indicates that your client CAN locate the specified +server, which is a good start, but that it cannot find a service of +the name you gave. +</para> + +<para> +The first step is to check the exact name of the service you are +trying to connect to (consult your system administrator). Assuming it +exists and you specified it correctly (read your client's docs on how +to specify a service name correctly), read on: +</para> + +<simplelist> +<member>Many clients cannot accept or use service names longer than eight characters.</member> +<member>Many clients cannot accept or use service names containing spaces.</member> +<member>Some servers (not Samba though) are case sensitive with service names.</member> +<member>Some clients force service names into upper case.</member> +</simplelist> +</sect1> + +<sect1> +<title>Printing doesn't work</title> +<para> +Make sure that the specified print command for the service you are +connecting to is correct and that it has a fully-qualified path (eg., +use "/usr/bin/lpr" rather than just "lpr"). +</para> + +<para> +Make sure that the spool directory specified for the service is +writable by the user connected to the service. In particular the user +"nobody" often has problems with printing, even if it worked with an +earlier version of Samba. Try creating another guest user other than +"nobody". +</para> + +<para> +Make sure that the user specified in the service is permitted to use +the printer. +</para> + +<para> +Check the debug log produced by smbd. Search for the printer name and +see if the log turns up any clues. Note that error messages to do with +a service ipc$ are meaningless - they relate to the way the client +attempts to retrieve status information when using the LANMAN1 +protocol. +</para> + +<para> +If using WfWg then you need to set the default protocol to TCP/IP, not +Netbeui. This is a WfWg bug. +</para> + +<para> +If using the Lanman1 protocol (the default) then try switching to +coreplus. Also not that print status error messages don't mean +printing won't work. The print status is received by a different +mechanism. +</para> + +<sect1> +<title>My client reports "This server is not configured to list shared resources"</title> +<para> +Your guest account is probably invalid for some reason. Samba uses the +guest account for browsing in smbd. Check that your guest account is +valid. +</para> + +<para>See also 'guest account' in smb.conf man page.</para> + +</sect1> + +<sect1> +<title>Log message "you appear to have a trapdoor uid system" </title> +<para> +This can have several causes. It might be because you are using a uid +or gid of 65535 or -1. This is a VERY bad idea, and is a big security +hole. Check carefully in your /etc/passwd file and make sure that no +user has uid 65535 or -1. Especially check the "nobody" user, as many +broken systems are shipped with nobody setup with a uid of 65535. +</para> + +<para>It might also mean that your OS has a trapdoor uid/gid system :-)</para> + +<para> +This means that once a process changes effective uid from root to +another user it can't go back to root. Unfortunately Samba relies on +being able to change effective uid from root to non-root and back +again to implement its security policy. If your OS has a trapdoor uid +system this won't work, and several things in Samba may break. Less +things will break if you use user or server level security instead of +the default share level security, but you may still strike +problems. +</para> + +<para> +The problems don't give rise to any security holes, so don't panic, +but it does mean some of Samba's capabilities will be unavailable. +In particular you will not be able to connect to the Samba server as +two different uids at once. This may happen if you try to print as a +"guest" while accessing a share as a normal user. It may also affect +your ability to list the available shares as this is normally done as +the guest user. +</para> + +<para> +Complain to your OS vendor and ask them to fix their system. +</para> + +<para> +Note: the reason why 65535 is a VERY bad choice of uid and gid is that +it casts to -1 as a uid, and the setreuid() system call ignores (with +no error) uid changes to -1. This means any daemon attempting to run +as uid 65535 will actually run as root. This is not good! +</para> + +</sect1> + +<sect1> +<title>Why are my file's timestamps off by an hour, or by a few hours?</title> +<para> +This is from Paul Eggert eggert@twinsun.com. +</para> + +<para> +Most likely it's a problem with your time zone settings. +</para> + +<para> +Internally, Samba maintains time in traditional Unix format, +namely, the number of seconds since 1970-01-01 00:00:00 Universal Time +(or ``GMT''), not counting leap seconds. +</para> + +<para> +On the server side, Samba uses the Unix TZ variable to convert +internal timestamps to and from local time. So on the server side, there are +two things to get right. +<simplelist> +<member>The Unix system clock must have the correct Universal time. Use the shell command "sh -c 'TZ=UTC0 date'" to check this.</member> +<member>The TZ environment variable must be set on the server before Samba is invoked. The details of this depend on the server OS, but typically you must edit a file whose name is /etc/TIMEZONE or /etc/default/init, or run the command `zic -l'.</member> +</simplelist> +</para> + +<para>TZ must have the correct value.</para> + +<para> +If possible, use geographical time zone settings +(e.g. TZ='America/Los_Angeles' or perhaps + TZ=':US/Pacific'). These are supported by most +popular Unix OSes, are easier to get right, and are +more accurate for historical timestamps. If your +operating system has out-of-date tables, you should be +able to update them from the public domain time zone +tables at <ulink url="ftp://elsie.nci.nih.gov/pub/">ftp://elsie.nci.nih.gov/pub/</ulink>. +</para> + +<para>If your system does not support geographical timezone +settings, you must use a Posix-style TZ strings, e.g. +TZ='PST8PDT,M4.1.0/2,M10.5.0/2' for US Pacific time. +Posix TZ strings can take the following form (with optional + items in brackets): +<programlisting> + StdOffset[Dst[Offset],Date/Time,Date/Time] +</programlisting> + where: +</para> + +<para><simplelist> +<member>`Std' is the standard time designation (e.g. `PST').</member> +<member>`Offset' is the number of hours behind UTC (e.g. `8'). +Prepend a `-' if you are ahead of UTC, and +append `:30' if you are at a half-hour offset. +Omit all the remaining items if you do not use +daylight-saving time.</member> + +<member>`Dst' is the daylight-saving time designation +(e.g. `PDT').</member> + +<member>The optional second `Offset' is the number of +hours that daylight-saving time is behind UTC. +The default is 1 hour ahead of standard time. +</member> + +<member>`Date/Time,Date/Time' specify when daylight-saving +time starts and ends. The format for a date is +`Mm.n.d', which specifies the dth day (0 is Sunday) +of the nth week of the mth month, where week 5 means +the last such day in the month. The format for a +time is [h]h[:mm[:ss]], using a 24-hour clock. +</member> + +</simplelist> +</para> + +<para> +Other Posix string formats are allowed but you don't want +to know about them.</para> + +<para> +On the client side, you must make sure that your client's clock and +time zone is also set appropriately. [[I don't know how to do this.]] +Samba traditionally has had many problems dealing with time zones, due +to the bizarre ways that Microsoft network protocols handle time +zones. +</para> + +<sect1> +<title>How do I set the printer driver name correctly?</title> +<para>Question:<para> +<quote> On NT, I opened "Printer Manager" and "Connect to Printer". + Enter ["\\ptdi270\ps1"] in the box of printer. I got the + following error message + </quote> + <para> + <programlisting> + You do not have sufficient access to your machine + to connect to the selected printer, since a driver + needs to be installed locally. + </programlisting> + </para> + + <para>Answer:</para> + + <para>In the more recent versions of Samba you can now set the "printer +driver" in smb.conf. This tells the client what driver to use. For +example:</para> +<para><programlisting> + printer driver = HP LaserJet 4L +</programlisting></para> +<para>With this, NT knows to use the right driver. You have to get this string +exactly right.</para> + +<para>To find the exact string to use, you need to get to the dialog box in +your client where you select which printer driver to install. The +correct strings for all the different printers are shown in a listbox +in that dialog box.</para> + +</sect1> + +</chapter> diff --git a/docs/docbook/projdoc/ADS-HOWTO.sgml b/docs/docbook/projdoc/ADS-HOWTO.sgml new file mode 100644 index 0000000000..0d2fda5f78 --- /dev/null +++ b/docs/docbook/projdoc/ADS-HOWTO.sgml @@ -0,0 +1,195 @@ +<chapter id="ADS"> + +<chapterinfo> + <author> + <firstname>Andrew</firstname><surname>Tridgell</surname> + </author> + <pubdate>2002</pubdate> +</chapterinfo> + +<title>Using samba 3.0 with ActiveDirectory support</title> + +<para> +This is a VERY ROUGH guide to setting up the current (November 2001) +pre-alpha version of Samba 3.0 with kerberos authentication against a +Windows2000 KDC. The procedures listed here are likely to change as +the code develops. +</para> + +<para>Pieces you need before you begin: +<simplelist> +<member>a Windows 2000 server.</member> +<member>samba 3.0 or higher.</member> +<member>the MIT kerberos development libraries (either install from the above sources or use a package). The heimdal libraries will not work.</member> +<member>the OpenLDAP development libraries.</member> +</simplelist> +</para> + +<sect1> +<title>Installing the required packages for Debian</title> + +<para>On Debian you need to install the following packages: +<simplelist> +<member>libkrb5-dev</member> +<member>krb5-user</member> +</simplelist> +</para> +</sect1> + +<sect1> +<title>Installing the required packages for RedHat</title> + +<para>On RedHat this means you should have at least: +<simplelist> +<member>krb5-workstation (for kinit)</member> +<member>krb5-libs (for linking with)</member> +<member>krb5-devel (because you are compiling from source)</member> +</simplelist> +</para> + +<para>in addition to the standard development environment.</para> + +<para>Note that these are not standard on a RedHat install, and you may need +to get them off CD2.</para> + +</sect1> + +<sect1> +<title>Compile Samba</title> +<para>If your kerberos libraries are in a non-standard location then + remember to add the configure option --with-krb5=DIR.</para> + +<para>After you run configure make sure that include/config.h contains + lines like this:</para> + +<para><programlisting> +#define HAVE_KRB5 1 +#define HAVE_LDAP 1 +</programlisting></para> + +<para>If it doesn't then configure did not find your krb5 libraries or + your ldap libraries. Look in config.log to figure out why and fix + it.</para> + +<para>Then compile and install Samba as usual. You must use at least the + following 3 options in smb.conf:</para> + +<para><programlisting> + realm = YOUR.KERBEROS.REALM + ads server = your.kerberos.server + security = ADS + encrypt passwords = yes +</programlisting></para> + +<para>Strictly speaking, you can omit the realm name and you can use an IP + address for the ads server. In that case Samba will auto-detect these.</para> + +<para>You do *not* need a smbpasswd file, although it won't do any harm + and if you have one then Samba will be able to fall back to normal + password security for older clients. I expect that the above + required options will change soon when we get better active + directory integration.</para> +</sect1> + +<sect1> +<title>Setup your /etc/krb5.conf</title> + +<para>The minimal configuration for krb5.conf is:</para> + +<para><programlisting> + [realms] + YOUR.KERBEROS.REALM = { + kdc = your.kerberos.server + } +</programlisting></para> + +<para>Test your config by doing a "kinit USERNAME@REALM" and making sure that + your password is accepted by the Win2000 KDC. </para> + +<para>NOTE: The realm must be uppercase. </para> + +<para> +You also must ensure that you can do a reverse DNS lookup on the IP +address of your KDC. Also, the name that this reverse lookup maps to +must either be the netbios name of the KDC (ie. the hostname with no +domain attached) or it can alternatively be the netbios name +followed by the realm. +</para> + +<para> +The easiest way to ensure you get this right is to add a /etc/hosts +entry mapping the IP address of your KDC to its netbios name. If you +don't get this right then you will get a "local error" when you try +to join the realm. +</para> + +<para> +If all you want is kerberos support in smbclient then you can skip +straight to step 5 now. Step 3 is only needed if you want kerberos +support in smbd. +</para> + +</sect1> + +<sect1> +<title>Create the computer account</title> + +<para> +Do a "kinit" as a user that has authority to change arbitrary +passwords on the KDC ("Administrator" is a good choice). Then as a +user that has write permission on the Samba private directory +(usually root) run: +<command>net ads join</command> +</para> + +<sect2> +<title>Possible errors</title> + +<para> +<variablelist> +<varlistentry><term>"bash: kinit: command not found"</term> +<listitem><para>kinit is in the krb5-workstation RPM on RedHat systems, and is in /usr/kerberos/bin, so it won't be in the path until you log in again (or open a new terminal)</para></listitem></varlistentry> +<varlistentry><term>"ADS support not compiled in"</term> +<listitem><para>Samba must be reconfigured (remove config.cache) and recompiled (make clean all install) after the kerberos libs and headers are installed.</para></listitem></varlistentry> +</variablelist> +</para> + +</sect2> + +</sect1> + +<sect1> +<title>Test your server setup</title> + +<para> +On a Windows 2000 client try <command>net use * \\server\share</command>. You should +be logged in with kerberos without needing to know a password. If +this fails then run <command>klist tickets</command>. Did you get a ticket for the +server? Does it have an encoding type of DES-CBC-MD5 ? +</para> + +</sect1> + +<sect1> +<title>Testing with smbclient</title> + +<para> +On your Samba server try to login to a Win2000 server or your Samba +server using smbclient and kerberos. Use smbclient as usual, but +specify the -k option to choose kerberos authentication. +</para> + +</sect1> + +<sect1> +<title>Notes</title> + +<para>You must change administrator password at least once after DC install, + to create the right encoding types</para> + +<para>w2k doesn't seem to create the _kerberos._udp and _ldap._tcp in + their defaults DNS setup. Maybe fixed in service packs?</para> + +</sect1> + +</chapter> |