s3-dbwrap: Add "db_context" to "db_record"

[Samba/gebeck_regimport.git] / docs-xml / Samba3-ByExample / SBE-preface.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE preface PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<preface id="preface">
  <title>Preface</title>

        <para>
        Network administrators live busy lives. We face distractions and pressures
        that drive us to seek proven, working case scenarios that can be easily
        implemented. Often this approach lands us in trouble. There is a 
        saying that, geometrically speaking, the shortest distance between two 
        points is a straight line, but practically we find that the quickest 
        route to a stable network solution is the long way around.
        </para>

        <para>
        This book is your means to the straight path. It provides step-by-step,
        proven, working examples of Samba deployments.  If you want to deploy
        Samba-3 with the least effort, or if you want to become an expert at deploying
        Samba-3 without having to search through lots of documentation, this
        book is the ticket to your destination.
        </para>

        <para>
        Samba is software that can be run on a platform other than Microsoft Windows,
        for example, UNIX, Linux, IBM System 390, OpenVMS, and other operating systems.
        Samba uses the TCP/IP protocol that is installed on the host server. When
        correctly configured, it allows that host to interact with a Microsoft Windows
        client or server as if it is a Windows file and print server. This book
        will help you to implement Windows-compatible file and print services.
        </para>

        <para>
        The examples presented in this book are typical of various businesses and
        reflect the problems and challenges they face. Care has been taken to preserve
        attitudes, perceptions, practices, and demands from real network case studies.
        The maximum benefit may be obtained from this book by working carefully through
        each exercise. You may be in a hurry to satisfy a specific need, so feel
        free to locate the example that most closely matches your need, copy it, and
        innovate as much as you like. Above all, enjoy the process of learning the
        secrets of MS Windows networking that is truly liberated by Samba.
        </para>

        <para>
        The focus of attention in this book is Samba-3. Specific notes are made in
        respect of how Samba may be made secure. This book does not attempt to provide
        detailed information regarding secure operation and configuration of peripheral
        services and applications such as OpenLDAP, DNS and DHCP, the need for which
        can be met from other resources that are dedicated to the subject.
        </para>

  <sect1>
        <title>Why Is This Book Necessary?</title>

        <para>
        This book is the result of observations and feedback. The feedback from
        the Samba-HOWTO-Collection has been positive and complimentary. There
        have been requests for far more worked examples, a
        <quote>Samba Cookbook,</quote> and for training materials to
        help kick-start the process of mastering Samba.
        </para>

        <para>
        The Samba mailing lists users have asked for sample configuration files
        that work. It is natural to question one's own ability to correctly
        configure a complex tool such as Samba until a minimum necessary
        knowledge level has been attained.
        </para>

        <para>
        The Samba-HOWTO-Collection &smbmdash; as does <emphasis>The Official Samba-3 HOWTO and 
        Reference Guide</emphasis> &smbmdash; documents Samba features and functionality in
        a topical context.  This book takes a completely different approach. It
        walks through Samba network configurations that are working within particular
        environmental contexts, providing documented step-by-step implementations.
        All example case configuration files, scripts, and other tools are provided
        on the CD-ROM. This book is descriptive, provides detailed diagrams, and
        makes deployment of Samba-3 a breeze.
        </para>

        <sect2>
        <title>Samba 3.0.20 Update Edition</title>

        <para>
        The Samba 3.0.x series has been remarkably popular. At the time this book first
        went to print samba-3.0.2 was being released. There have been significant modifications
        and enhancements between samba-3.0.2 and samba-3.0.14 (the current release) that
        necessitate this documentation update. This update has the specific intent to
        refocus this book so that its guidance can be followed for samba-3.0.20
        and beyond. Further changes are expected as Samba-3 matures further and will 
        be reflected in future updates.
        </para>

        <para>
        The changes shown in <link linkend="pref-new"/> are incorporated in this update.
        </para>

        <table id="pref-new">
                <title>Samba Changes &smbmdash; 3.0.2 to 3.0.20</title>
                <tgroup cols="2">
                        <colspec align="left"/>
                        <colspec align="justify"/>
                        <thead>
                                <row>
                                        <entry align="left">
                                                <para>
                                                New Feature
                                                </para>
                                        </entry>
                                        <entry align="left">
                                                <para>
                                                Description
                                                </para>
                                        </entry>
                                </row>
                        </thead>
                        <tbody>
                                <row>
                                        <entry>
                                                <para>
                                                Winbind Case Handling
                                                </para>
                                        </entry>
                                        <entry>
                                                <para>
                                                User and group names returned by <command>winbindd</command> are now converted to lower case
                                                for better consistency. Samba implementations that depend on the case of information returned
                                                by winbind (such as %u and %U) must now convert the dependency to expecting lower case values.
                                                This affects mail spool files, home directories, valid user lines in the &smb.conf; file, etc.
                                                </para>
                                        </entry>
                                </row>
                                <row>
                                        <entry>
                                                <para>
                                                Schema Changes
                                                </para>
                                        </entry>
                                        <entry>
                                                <para>
                                                Addition of code to handle password aging, password uniqueness controls, bad
                                                password instances at logon time, have made necessary extensions to the SambaSAM
                                                schema. This change affects all sites that use LDAP and means that the directory
                                                schema must be updated. 
                                                </para>
                                        </entry>
                                </row>
                                <row>
                                        <entry>
                                                <para>
                                                Username Map Handling
                                                </para>
                                        </entry>
                                        <entry>
                                                <para>
                                                Samba-3.0.8 redefined the behavior: Local authentication results in a username map file
                                                lookup before authenticating the connection. All authentication via an external domain
                                                controller will result in the use of the fully qualified name (i.e.: DOMAIN\username)
                                                after the user has been successfully authenticated.
                                                </para>
                                        </entry>
                                </row>
                                <row>
                                        <entry>
                                                <para>
                                                UNIX Extension Handling
                                                </para>
                                        </entry>
                                        <entry>
                                                <para>
                                                Symbolically linked files and directories on the UNIX host to absolute paths will
                                                now be followed. This can be turned off using <quote>wide links = No</quote> in
                                                the share stanza in the &smb.conf; file. Turning off <quote>wide links</quote>
                                                support will degrade server performance because each path must be checked.
                                                </para>
                                        </entry>
                                </row>
                                <row>
                                        <entry>
                                                <para>
                                                Privileges Support
                                                </para>
                                        </entry>
                                        <entry>
                                                <para>
                                                Versions of Samba prior to samba-3.0.11 required the use of the UNIX <constant>root</constant>
                                                account from network Windows clients. The new <quote>enable privileges = Yes</quote> capability
                                                means that functions such as adding machines to the domain, managing printers, etc. can now
                                                be delegated to normal user accounts or to groups of users.
                                                </para>
                                        </entry>
                                </row>
                        </tbody>
                </tgroup>
        </table>
        </sect2>

  </sect1>

  <sect1>
  <title>Prerequisites</title>

        <para>
        This book is not a tutorial on UNIX or Linux administration. UNIX and Linux
        training is best obtained from books dedicated to the subject. This book
        assumes that you have at least the basic skill necessary to use these operating
        systems, and that you can use a basic system editor to edit and configure files.
        It has been written with the assumption that you have experience with Samba, 
        have read <emphasis>The Official Samba-3 HOWTO and Reference Guide</emphasis> and
        the Samba-HOWTO-Collection, or that you have familiarity with Microsoft Windows.
        </para>

        <para>
        If you do not have this experience, you can follow the examples in this book but may
        find yourself at times intimidated by assumptions made. In this situation, you
        may need to refer to administrative guides or manuals for your operating system
        platform to find what is the best method to achieve what the text of this book describes.
        </para>

  </sect1>

  <sect1>
        <title>Approach</title>

        <para>
        The first chapter deals with some rather thorny network analysis issues. Do not be
        put off by this. The information you glean, even without a detailed understanding
        of network protocol analysis, can help you understand how Windows networking functions.
        </para>

        <para>
        Each following chapter of this book opens with the description of a networking solution
        sought by a hypothetical site. Bob Jordan is a hypothetical decision maker
        for an imaginary company, <constant>Abmas Biz NL</constant>. We will use the
        non-existent domain name <constant>abmas.biz</constant>. All <emphasis>facts</emphasis> 
        presented regarding this company are fictitious and have been drawn from a variety of real 
        business scenarios over many years. Not one of these reveal the identify of the 
        real-world company from which the scenario originated.
        </para>

        <para> 
        In any case, Mr. Jordan likes to give all his staff nasty little assignments.
        Stanley Saroka is one of his proteges; Christine Roberson is the network administrator 
        Bob trusts. Jordan is inclined to treat other departments well because they finance 
        Abmas IT operations.
        </para>

        <para>
        Each chapter presents a summary of the network solution we have chosen to
        demonstrate together with a rationale to help you to understand the
        thought process that drove that solution. The chapter then documents in precise
        detail all configuration files and steps that must be taken to implement the
        example solution. Anyone wishing to gain serious value from this book will
        do well to take note of the implications of points made, so watch out for the
        <emphasis>this means that</emphasis> notations.
        </para>

        <para>
        Each chapter has a set of questions and answers to help you to
        to understand and digest key attributes of the solutions presented.
        </para>

  </sect1>

  <sect1>
        <title>Summary of Topics</title>

        <para>
        The contents of this second edition of <emphasis>Samba-3 by Example</emphasis>
        have been rearranged based on feedback from purchasers of the first edition.
        </para>

        <para>
        Clearly the first edition contained most of what was needed and that was missing
        from other books that cover this difficult subject. The new arrangement adds
        additional material to meet consumer requests and includes changes that originated
        as suggestions for improvement.
        </para>

        <para>
        Chapter 1 now dives directly into the heart of the implementation of Windows
        file and print server networks that use Samba at the heart.
        </para>

        <variablelist>
                <varlistentry>
                <term>Chapter 1 &smbmdash; No Frills Samba Servers.</term><listitem>
                <para>
                Here you design a solution for three different business scenarios, each for a 
                company called Abmas. There are two simple networking problems and one slightly 
                more complex networking challenge. In the first two cases, Abmas has a small 
                simple office, and they want to replace a Windows 9x peer-to-peer network. The 
                third example business uses Windows 2000 Professional. This must be simple, 
                so let's see how far we can get. If successful, Abmas grows quickly and
                soon needs to replace all servers and workstations.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This chapter demands:
                        <itemizedlist>
                                <listitem><para>Case 1: The simplest &smb.conf; file that may
                                        reasonably be used. Works with Samba-2.x also. This
                                        configuration uses Share Mode security. Encrypted
                                        passwords are not used, so there is no 
                                        <filename>smbpasswd</filename> file.
                                        </para></listitem>

                                <listitem><para>Case 2: Another simple &smb.conf; file that adds
                                        WINS support and printing support. This case deals with
                                        a special requirement that demonstrates how to deal with
                                        purpose-built software that has a particular requirement
                                        for certain share names and printing demands. This
                                        configuration uses Share Mode security and also works with
                                        Samba-2.x. Encrypted passwords are not used, so there is no
                                        <filename>smbpasswd</filename> file.
                                        </para></listitem>

                                <listitem><para>Case 3: This &smb.conf; configuration uses User Mode
                                        security. The file share configuration demonstrates
                                        the ability to provide master access to an administrator
                                        while restricting all staff to their own work areas.
                                        Encrypted passwords are used, so there is an implicit
                                        <filename>smbpasswd</filename> file.
                                        </para></listitem>
                        </itemizedlist>
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 2 &smbmdash; Small Office Networking.</term><listitem>
                <para>
                Abmas is a successful company now. They have 50 network users
                and want a little more varoom from the network. This is a typical
                small office and they want better systems to help them to grow. This is
                your chance to really give advanced users a bit more functionality and usefulness.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
                makes use of encrypted passwords, so there is an <filename>smbpasswd</filename>
                file. It also demonstrates use of the <parameter>valid users</parameter> and
                <parameter>valid groups</parameter> to restrict share access. The Windows
                clients access the server as Domain members. Mobile users log onto
                the Domain while in the office, but use a local machine account while on the
                road. The result is an environment that answers mobile computing user needs.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 3 &smbmdash; Secure Office Networking.</term><listitem>
                <para>
                Abmas is growing rapidly now. Money is a little tight, but with 130
                network users, security has become a concern. They have many new machines
                to install and the old equipment will be retired. This time they want the
                new network to scale and grow for at least two years. Start with a sufficient
                system and allow room for growth. You are now implementing an Internet
                connection and have a few reservations about user expectations.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
                makes use of encrypted passwords, and you can use a <filename>tdbsam</filename>
                password backend. Domain logons are introduced. Applications are served from the central
                server. Roaming profiles are mandated. Access to the server is tightened up
                so that only domain members can access server resources. Mobile computing
                needs still are catered to.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 4 &smbmdash; The 500 User Office.</term><listitem>
                <para>
                The two-year projections were met. Congratulations, you are a star.
                Now Abmas needs to replace the network. Into the existing user base, they
                need to merge a 280-user company they just acquired. It is time to build a serious
                network. There are now three buildings on one campus and your assignment is 
                to keep everyone working while a new network is rolled out. Oh, isn't it nice 
                to roll out brand new clients and servers! Money is no longer tight, you get 
                to buy and install what you ask for. You will install routers and a firewall.
                This is exciting!
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
                makes use of encrypted passwords, and a <filename>tdbsam</filename>
                password backend is used. You are not ready to launch into LDAP yet, so you
                accept the limitation of having one central Domain Controller with a Domain
                Member server in two buildings on your campus. A number of clever techniques
                are used to demonstrate some of the smart options built into Samba.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 5 &smbmdash; Making Happy Users.</term><listitem>
                <para>
                Congratulations again. Abmas is happy with your services and you have been given another raise.
                Your users are becoming much more capable and are complaining about little
                things that need to be fixed. Are you up to the task? Mary says it takes her 20 minutes
                to log onto the network and it is killing her productivity. Email is a bit <emphasis>
                unreliable</emphasis> &smbmdash; have you been sleeping on the job? We do not discuss the
                technology of email but when the use of mail clients breaks because of networking
                problems, you had better get on top of it. It's time for a change.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This &smb.conf; file
                makes use of encrypted passwords; a distributed <filename>ldapsam</filename>
                password backend is used. Roaming profiles are enabled. Desktop profile controls
                are introduced. Check out the techniques that can improve the user experience 
                of network performance. As a special bonus, this chapter documents how to configure
                smart downloading of printer drivers for drag-and-drop printing support. And, yes,
                the secret of configuring CUPS is clearly documented. Go for it; this one will
                tease you, too.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 6 &smbmdash; A Distributed 2000 User Network.</term><listitem>
                <para>
                Only eight months have passed, and Abmas has acquired another company. You now need to expand
                the network further. You have to deal with a network that spans several countries.
                There are three new networks in addition to the original three buildings at the head-office 
                campus. The head office is in New York and you have branch offices in Washington, Los Angeles, and 
                London. Your desktop standard is Windows XP Professional. In many ways, everything has changed
                and yet it must remain the same. Your team is primed for another roll-out. You know there are
                further challenges ahead.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; Slave LDAP servers are introduced. Samba is
                configured to use multiple LDAP backends. This is a brief chapter; it assumes that the
                technology has been mastered and gets right down to concepts and how to deploy them.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 7 &smbmdash; Adding UNIX/Linux Servers and Clients.</term><listitem>
                <para>
                Well done, Bob, your team has achieved much. Now help Abmas integrate the entire network.
                You want central control and central support and you need to cut costs. How can you reduce administrative
                overheads and yet get better control of the network?
                </para>

                <para>
                This chapter has been contributed by Mark Taylor <email>mark.taylor@siriusit.co.uk</email>
                and is based on a live site. For further information regarding this example case, 
                please contact Mark directly.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; It is time to consider how to add Samba servers
                and UNIX and Linux network clients. Users who convert to Linux want to be able to log on
                using Windows network accounts. You explore nss_ldap, pam_ldap, winbind, and a few neat
                techniques for taking control. Are you ready for this?
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 8 &smbmdash; Updating Samba-3.</term><listitem>
                <para>
                This chapter is the result of repeated requests for better documentation of the steps
                that must be followed when updating or upgrading a Samba server. It attempts to cover
                the entire subject in broad-brush but at the same time provides detailed background
                information that is not covered elsewhere in the Samba documentation.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; Samba stores a lot of essential network
                information in a large and growing collection of files. This chapter documents the
                essentials of where those files may be located and how to find them. It also provides
                an insight into inter-related matters that affect a Samba installation.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 9 &smbmdash; Migrating NT4 Domain to Samba-3.</term><listitem>
                <para>
                Another six months have passed. Abmas has acquired yet another company. You will find a
                way to migrate all users off the old network onto the existing network without loss
                of passwords and will effect the change-over during one weekend. May the force (and caffeine) be with
                you, may you keep your back to the wind and may the sun shine on your face.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This chapter demonstrates the use of
                the <command>net rpc migrate</command> facility using an LDAP ldapsam backend, and also
                using a tdbsam passdb backend. Both are much-asked-for examples of NT4 Domain migration.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 10 &smbmdash; Migrating NetWare 4.11 Server to Samba.</term><listitem>
                <para>
                Misty Stanley-Jones has contributed information that summarizes her experience at migration
                from a NetWare server to Samba-3.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; The documentation provided demonstrates
                how one site migrated from NetWare to Samba. Some alternatives tools are mentioned. These
                could be used to provide another pathway to a successful migration.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 11 &smbmdash; Active Directory, Kerberos and Security.</term><listitem>
                <para>
                Abmas has acquired another company that has just migrated to running Windows Server 2003 and 
                Active Directory. One of your staff makes offhand comments that land you in hot water.
                A network security auditor is hired by the head of the new business and files a damning 
                report, and you must address the <emphasis>defects</emphasis> reported. You have hired new 
                network engineers who want to replace Microsoft Active Directory with a pure Kerberos 
                solution. How will you handle this? 
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; This chapter is your answer. Learn about
                share access controls, proper use of UNIX/Linux file system access controls, and Windows
                200x Access Control Lists. Follow these steps to beat the critics.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 12 &smbmdash; Integrating Additional Services.</term><listitem>
                <para>
                The battle is almost over, Samba-3 has won the day. Your team are delighted and now you
                find yourself at yet another cross-roads. Abmas have acquired a snack food business, you
                made promises you must keep. IT costs must be reduced, you have new resistance, but you
                will win again. This time you choose to install the Squid proxy server to validate the
                fact that Samba is far more than just a file and print server. SPNEGO authentication 
                support means that your Microsoft Windows clients gain transparent proxy access.
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; Samba provides the <command>ntlm_auth</command>
                module that makes it possible for MS Windows Internet Explorer to connect via the Squid Web
                and FTP proxy server. You will configure Samba-3 as well as Squid to deliver authenticated
                access control using the Active Directory Domain user security credentials.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 13 &smbmdash; Performance, Reliability and Availability.</term><listitem>
                <para>
                Bob, are you sure the new Samba server is up to the load? Your network is serving many
                users who risk becoming unproductive. What can you do to keep ahead of demand? Can you
                keep the cost under control also? What can go wrong?
                </para>

                <para><emphasis>TechInfo</emphasis> &smbmdash; Hot tips that put chili into your
                network. Avoid name resolution problems, identify potential causes of network collisions,
                avoid Samba configuration options that will weigh the server down. MS distributed file
                services to make your network fly and much more. This chapter contains a good deal of 
                <quote>Did I tell you about this...?</quote> type of hints to help keep your name on the top
                performers list.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 14 &smbmdash; Samba Support.</term><listitem>
                <para>
                This chapter has been added specifically to help those who are seeking professional
                paid support for Samba. The critics of Open Source Software often assert that
                there is no support for free software. Some critics argue that free software 
                undermines the service that proprietary commercial software vendors depend on.
                This chapter explains what are the support options for Samba and the fact that
                a growing number of businesses make money by providing commercial paid-for
                Samba support.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 15 &smbmdash; A Collection of Useful Tid-bits.</term><listitem>
                <para>
                Sometimes it seems that there is not a good place for certain odds and ends that
                impact Samba deployment. Some readers would argue that everyone can be expected
                to know this information, or at least be able to find it easily. So to avoid
                offending a reader's sensitivities, the tid-bits have been placed in this chapter.
                Do check out the contents, you may find something of value among the loose ends.
                </para>
                </listitem>
                </varlistentry>

                <varlistentry>
                <term>Chapter 16 &smbmdash; Windows Networking Primer.</term><listitem>
                <para>
                Here we cover practical exercises to help us to understand how MS Windows
                network protocols function. A network protocol analyzer helps you to
                appreciate the fact that Windows networking is highly dependent on broadcast
                messaging. Additionally, you can look into network packets that a Windows
                client sends to a network server to set up a network connection. On completion,
                you should have a basic understanding of how network browsing functions and
                have seen some of the information a Windows client sends to
                a file and print server to create a connection over which file and print
                operations may take place.
                </para>
                </listitem>
                </varlistentry>

        </variablelist>

  </sect1>

  <!-- the conventions used in this book -->
  <xi:include href="conventions.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />

</preface>