This commit was manufactured by cvs2svn to create branch 'SAMBA_3_0'.(This used to be commit 6938b5b98abd9ba055a46583a05c4fc07e32f529)

6 files changed, 2627 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/Browsing.sgml b/docs/docbook/projdoc/Browsing.sgml
new file mode 100644
index 0000000000..a463ea786b
--- /dev/null
+++ b/docs/docbook/projdoc/Browsing.sgml
@@ -0,0 +1,800 @@
+<chapter id="improved-browsing">
+<chapterinfo>
+	<author>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+		</affiliation>
+	</author>
+
+
+	<pubdate> (5 July 1998) </pubdate>
+</chapterinfo>
+
+<title>Improved browsing in samba</title>
+
+<sect1>
+<title>Overview of browsing</title>
+
+<para>
+SMB networking provides a mechanism by which clients can access a list
+of machines in a network, a so-called "browse list".  This list
+contains machines that are ready to offer file and/or print services
+to other machines within the network. Thus it does not include
+machines which aren't currently able to do server tasks.  The browse
+list is heavily used by all SMB clients.  Configuration of SMB
+browsing has been problematic for some Samba users, hence this
+document.
+</para>
+
+<para>
+Browsing will NOT work if name resolution from NetBIOS names to IP
+addresses does not function correctly. Use of a WINS server is highly
+recommended to aid the resolution of NetBIOS (SMB) names to IP addresses.
+WINS allows remote segment clients to obtain NetBIOS name_type information
+that can NOT be provided by any other means of name resolution.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Browsing support in samba</title>
+
+<para>
+Samba now fully supports browsing.  The browsing is supported by nmbd
+and is also controlled by options in the smb.conf file (see smb.conf(5)).
+</para>
+
+<para>
+Samba can act as a local browse master for a workgroup and the ability
+for samba to support domain logons and scripts is now available.  See
+DOMAIN.txt for more information on domain logons.
+</para>
+
+<para>
+Samba can also act as a domain master browser for a workgroup.  This
+means that it will collate lists from local browse masters into a
+wide area network server list.  In order for browse clients to
+resolve the names they may find in this list, it is recommended that
+both samba and your clients use a WINS server.
+</para>
+
+<para>
+Note that you should NOT set Samba to be the domain master for a
+workgroup that has the same name as an NT Domain: on each wide area
+network, you must only ever have one domain master browser per workgroup,
+regardless of whether it is NT, Samba or any other type of domain master
+that is providing this service.
+</para>
+
+<para>
+[Note that nmbd can be configured as a WINS server, but it is not
+necessary to specifically use samba as your WINS server.  NTAS can
+be configured as your WINS server.  In a mixed NT server and
+samba environment on a Wide Area Network, it is recommended that
+you use the NT server's WINS server capabilities.  In a samba-only
+environment, it is recommended that you use one and only one nmbd
+as your WINS server].
+</para>
+
+<para>
+To get browsing to work you need to run nmbd as usual, but will need
+to use the "workgroup" option in smb.conf to control what workgroup
+Samba becomes a part of.
+</para>
+
+<para>
+Samba also has a useful option for a Samba server to offer itself for
+browsing on another subnet.  It is recommended that this option is only
+used for 'unusual' purposes: announcements over the internet, for
+example.  See "remote announce" in the smb.conf man page.  
+</para>
+</sect1>
+
+<sect1>
+<title>Problem resolution</title>
+
+<para>
+If something doesn't work then hopefully the log.nmb file will help
+you track down the problem.  Try a debug level of 2 or 3 for finding
+problems. Also note that the current browse list usually gets stored
+in text form in a file called browse.dat.
+</para>
+
+<para>
+Note that if it doesn't work for you, then you should still be able to
+type the server name as \\SERVER in filemanager then hit enter and
+filemanager should display the list of available shares.
+</para>
+
+<para>
+Some people find browsing fails because they don't have the global
+"guest account" set to a valid account.  Remember that the IPC$
+connection that lists the shares is done as guest, and thus you must
+have a valid guest account.
+</para>
+
+<para>
+Also, a lot of people are getting bitten by the problem of too many
+parameters on the command line of nmbd in inetd.conf.  This trick is to
+not use spaces between the option and the parameter (eg: -d2 instead
+of -d 2), and to not use the -B and -N options.  New versions of nmbd
+are now far more likely to correctly find your broadcast and network
+address, so in most cases these aren't needed.
+</para>
+
+<para>
+The other big problem people have is that their broadcast address,
+netmask or IP address is wrong (specified with the "interfaces" option
+in smb.conf)
+</para>
+</sect1>
+
+<sect1>
+<title>Browsing across subnets</title>
+<para>
+With the release of Samba 1.9.17(alpha1 and above) Samba has been
+updated to enable it to support the replication of browse lists
+across subnet boundaries.  New code and options have been added to
+achieve this.  This section describes how to set this feature up
+in different settings.
+</para>
+
+<para>
+To see browse lists that span TCP/IP subnets (ie.  networks separated
+by routers that don't pass broadcast traffic) you must set up at least
+one WINS server.  The WINS server acts as a DNS for NetBIOS names, allowing
+NetBIOS name to IP address translation to be done by doing a direct
+query of the WINS server.  This is done via a directed UDP packet on
+port 137 to the WINS server machine.  The reason for a WINS server is
+that by default, all NetBIOS name to IP address translation is done
+by broadcasts from the querying machine.  This means that machines
+on one subnet will not be able to resolve the names of machines on
+another subnet without using a WINS server.
+</para>
+
+<para>
+Remember, for browsing across subnets to work correctly, all machines,
+be they Windows 95, Windows NT, or Samba servers must have the IP address
+of a WINS server given to them by a DHCP server, or by manual configuration 
+(for Win95 and WinNT, this is in the TCP/IP Properties, under Network 
+settings) for Samba this is in the smb.conf file.
+</para>
+
+<sect2>
+<title>How does cross subnet browsing work ?</title>
+
+<para>
+Cross subnet browsing is a complicated dance, containing multiple
+moving parts.  It has taken Microsoft several years to get the code
+that achieves this correct, and Samba lags behind in some areas.
+However, with the 1.9.17 release, Samba is capable of cross subnet
+browsing when configured correctly.
+</para>
+
+<para>
+Consider a network set up as follows :
+</para>
+
+<para>
+<programlisting>
+                                   (DMB)
+             N1_A      N1_B        N1_C       N1_D        N1_E
+              |          |           |          |           |
+          -------------------------------------------------------
+            |          subnet 1                       |
+          +---+                                      +---+
+          |R1 | Router 1                  Router 2   |R2 |
+          +---+                                      +---+
+            |                                          |
+            |  subnet 2              subnet 3          |
+  --------------------------       ------------------------------------
+  |     |     |      |               |        |         |           |
+ N2_A  N2_B  N2_C   N2_D           N3_A     N3_B      N3_C        N3_D 
+                    (WINS)
+</programlisting>
+</para>
+	
+<para>
+Consisting of 3 subnets (1, 2, 3) connected by two routers
+(R1, R2) - these do not pass broadcasts.  Subnet 1 has 5 machines
+on it, subnet 2 has 4 machines, subnet 3 has 4 machines.  Assume
+for the moment that all these machines are configured to be in the
+same workgroup (for simplicities sake).  Machine N1_C on subnet 1
+is configured as Domain Master Browser (ie.  it will collate the
+browse lists for the workgroup).  Machine N2_D is configured as
+WINS server and all the other machines are configured to register
+their NetBIOS names with it.
+</para>
+
+<para>
+As all these machines are booted up, elections for master browsers
+will take place on each of the three subnets.  Assume that machine
+N1_C wins on subnet 1, N2_B wins on subnet 2, and N3_D wins on
+subnet 3 - these machines are known as local master browsers for
+their particular subnet.  N1_C has an advantage in winning as the
+local master browser on subnet 1 as it is set up as Domain Master
+Browser.
+</para>
+
+<para>
+On each of the three networks, machines that are configured to 
+offer sharing services will broadcast that they are offering
+these services.  The local master browser on each subnet will
+receive these broadcasts and keep a record of the fact that
+the machine is offering a service.  This list of records is
+the basis of the browse list.  For this case, assume that
+all the machines are configured to offer services so all machines
+will be on the browse list.
+</para>
+
+<para>
+For each network, the local master browser on that network is
+considered 'authoritative' for all the names it receives via
+local broadcast.  This is because a machine seen by the local
+master browser via a local broadcast must be on the same 
+network as the local master browser and thus is a 'trusted'
+and 'verifiable' resource.  Machines on other networks that
+the local master browsers learn about when collating their
+browse lists have not been directly seen - these records are
+called 'non-authoritative'.
+</para>
+
+<para>
+At this point the browse lists look as follows (these are 
+the machines you would see in your network neighborhood if
+you looked in it on a particular network right now).
+</para>
+
+<para>
+<programlisting>
+Subnet           Browse Master   List
+------           -------------   ----
+Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E
+
+Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
+
+Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
+</programlisting>
+</para>
+
+<para>
+Note that at this point all the subnets are separate, no
+machine is seen across any of the subnets.
+</para>
+
+<para>
+Now examine subnet 2.  As soon as N2_B has become the local
+master browser it looks for a Domain master browser to synchronize
+its browse list with.  It does this by querying the WINS server
+(N2_D) for the IP address associated with the NetBIOS name 
+WORKGROUP&gt;1B&lt;.  This name was registerd by the Domain master
+browser (N1_C) with the WINS server as soon as it was booted.
+</para>
+
+<para>
+Once N2_B knows the address of the Domain master browser it
+tells it that is the local master browser for subnet 2 by
+sending a MasterAnnouncement packet as a UDP port 138 packet.
+It then synchronizes with it by doing a NetServerEnum2 call.  This
+tells the Domain Master Browser to send it all the server
+names it knows about.  Once the domain master browser receives
+the MasterAnnouncement packet it schedules a synchronization
+request to the sender of that packet.  After both synchronizations
+are done the browse lists look like :
+</para>
+
+<para>
+<programlisting>
+Subnet           Browse Master   List
+------           -------------   ----
+Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
+                                 N2_A(*), N2_B(*), N2_C(*), N2_D(*)
+
+Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
+                                 N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
+
+Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
+
+Servers with a (*) after them are non-authoritative names.
+</programlisting>
+</para>
+
+<para>
+At this point users looking in their network neighborhood on
+subnets 1 or 2 will see all the servers on both, users on
+subnet 3 will still only see the servers on their own subnet.
+</para>
+
+<para>
+The same sequence of events that occured for N2_B now occurs
+for the local master browser on subnet 3 (N3_D).  When it
+synchronizes browse lists with the domain master browser (N1_A)
+it gets both the server entries on subnet 1, and those on
+subnet 2.  After N3_D has synchronized with N1_C and vica-versa
+the browse lists look like.
+</para>
+
+<para>
+<programlisting>
+Subnet           Browse Master   List
+------           -------------   ----
+Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
+                                 N2_A(*), N2_B(*), N2_C(*), N2_D(*),
+                                 N3_A(*), N3_B(*), N3_C(*), N3_D(*)
+
+Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
+                                 N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
+
+Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
+                                 N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*),
+                                 N2_A(*), N2_B(*), N2_C(*), N2_D(*)
+
+Servers with a (*) after them are non-authoritative names.
+</programlisting>
+</para>
+
+<para>
+At this point users looking in their network neighborhood on
+subnets 1 or 3 will see all the servers on all sunbets, users on
+subnet 2 will still only see the servers on subnets 1 and 2, but not 3.
+</para>
+
+<para>
+Finally, the local master browser for subnet 2 (N2_B) will sync again
+with the domain master browser (N1_C) and will recieve the missing
+server entries.  Finally - and as a steady state (if no machines
+are removed or shut off) the browse lists will look like :
+</para>
+
+<para>
+<programlisting>
+Subnet           Browse Master   List
+------           -------------   ----
+Subnet1          N1_C            N1_A, N1_B, N1_C, N1_D, N1_E, 
+                                 N2_A(*), N2_B(*), N2_C(*), N2_D(*),
+                                 N3_A(*), N3_B(*), N3_C(*), N3_D(*)
+
+Subnet2          N2_B            N2_A, N2_B, N2_C, N2_D
+                                 N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*)
+                                 N3_A(*), N3_B(*), N3_C(*), N3_D(*)
+
+Subnet3          N3_D            N3_A, N3_B, N3_C, N3_D
+                                 N1_A(*), N1_B(*), N1_C(*), N1_D(*), N1_E(*),
+                                 N2_A(*), N2_B(*), N2_C(*), N2_D(*)
+	
+Servers with a (*) after them are non-authoritative names.
+</programlisting>
+</para>
+
+<para>
+Synchronizations between the domain master browser and local
+master browsers will continue to occur, but this should be a
+steady state situation.
+</para>
+
+<para>
+If either router R1 or R2 fails the following will occur:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	Names of computers on each side of the inaccessible network fragments
+	will be maintained for as long as 36 minutes, in the network neighbourhood
+	lists.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	Attempts to connect to these inaccessible computers will fail, but the
+	names will not be removed from the network neighbourhood lists.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	If one of the fragments is cut off from the WINS server, it will only
+	be able to access servers on its local subnet, by using subnet-isolated
+	broadcast NetBIOS name resolution.  The effects are similar to that of
+	losing access to a DNS server.
+	</para>
+</listitem>
+</orderedlist>
+</sect2>
+</sect1>
+
+<sect1>
+<title>Setting up a WINS server</title>
+
+<para>
+Either a Samba machine or a Windows NT Server machine may be set up
+as a WINS server.  To set a Samba machine to be a WINS server you must
+add the following option to the smb.conf file on the selected machine :
+in the [globals] section add the line 
+</para>
+
+<para>
+<command>		wins support = yes</command>
+</para>
+
+<para>
+Versions of Samba previous to 1.9.17 had this parameter default to
+yes.  If you have any older versions of Samba on your network it is
+strongly suggested you upgrade to 1.9.17 or above, or at the very
+least set the parameter to 'no' on all these machines.
+</para>
+
+<para>
+Machines with "<command>wins support = yes</command>" will keep a list of 
+all NetBIOS names registered with them, acting as a DNS for NetBIOS names.
+</para>
+
+<para>
+You should set up only ONE wins server.  Do NOT set the
+"<command>wins support = yes</command>" option on more than one Samba 
+server.
+</para>
+
+<para>
+To set up a Windows NT Server as a WINS server you need to set up
+the WINS service - see your NT documentation for details.  Note that
+Windows NT WINS Servers can replicate to each other, allowing more
+than one to be set up in a complex subnet environment.  As Microsoft
+refuse to document these replication protocols Samba cannot currently
+participate in these replications.  It is possible in the future that
+a Samba->Samba WINS replication protocol may be defined, in which
+case more than one Samba machine could be set up as a WINS server
+but currently only one Samba server should have the "wins support = yes"
+parameter set.
+</para>
+
+<para>
+After the WINS server has been configured you must ensure that all
+machines participating on the network are configured with the address
+of this WINS server.  If your WINS server is a Samba machine, fill in
+the Samba machine IP address in the "Primary WINS Server" field of
+the "Control Panel->Network->Protocols->TCP->WINS Server" dialogs
+in Windows 95 or Windows NT.  To tell a Samba server the IP address
+of the WINS server add the following line to the [global] section of
+all smb.conf files :
+</para>
+
+<para>
+<command>		wins server = &gt;name or IP address&lt;</command>
+</para>
+
+<para>
+where &gt;name or IP address&lt; is either the DNS name of the WINS server
+machine or its IP address.
+</para>
+
+<para>
+Note that this line MUST NOT BE SET in the smb.conf file of the Samba
+server acting as the WINS server itself.  If you set both the
+"<command>wins support = yes</command>" option and the 
+"<command>wins server = &gt;name&lt;</command>" option then
+nmbd will fail to start.
+</para>
+
+<para>
+There are two possible scenarios for setting up cross subnet browsing.
+The first details setting up cross subnet browsing on a network containing
+Windows 95, Samba and Windows NT machines that are not configured as
+part of a Windows NT Domain.  The second details setting up cross subnet
+browsing on networks that contain NT Domains.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Setting up Browsing in a WORKGROUP</title>
+
+<para>
+To set up cross subnet browsing on a network containing machines
+in up to be in a WORKGROUP, not an NT Domain you need to set up one
+Samba server to be the Domain Master Browser (note that this is *NOT*
+the same as a Primary Domain Controller, although in an NT Domain the
+same machine plays both roles).  The role of a Domain master browser is
+to collate the browse lists from local master browsers on all the
+subnets that have a machine participating in the workgroup.  Without
+one machine configured as a domain master browser each subnet would
+be an isolated workgroup, unable to see any machines on any other
+subnet.  It is the presense of a domain master browser that makes
+cross subnet browsing possible for a workgroup.
+</para>
+
+<para>
+In an WORKGROUP environment the domain master browser must be a
+Samba server, and there must only be one domain master browser per
+workgroup name.  To set up a Samba server as a domain master browser,
+set the following option in the [global] section of the smb.conf file :
+</para>
+
+<para>
+<command>		domain master = yes</command>
+</para>
+
+<para>
+The domain master browser should also preferrably be the local master
+browser for its own subnet.  In order to achieve this set the following
+options in the [global] section of the smb.conf file :
+</para>
+
+<para>
+<programlisting>
+        domain master = yes
+        local master = yes
+        preferred master = yes
+        os level = 65
+</programlisting>
+</para>
+
+<para>
+The domain master browser may be the same machine as the WINS
+server, if you require.
+</para>
+
+<para>
+Next, you should ensure that each of the subnets contains a
+machine that can act as a local master browser for the
+workgroup.  Any NT machine should be able to do this, as will
+Windows 95 machines (although these tend to get rebooted more
+often, so it's not such a good idea to use these).  To make a 
+Samba server a local master browser set the following
+options in the [global] section of the smb.conf file :
+</para>
+
+<para>
+<programlisting>
+        domain master = no
+        local master = yes
+        preferred master = yes
+        os level = 65
+</programlisting>
+</para>
+
+<para>
+Do not do this for more than one Samba server on each subnet,
+or they will war with each other over which is to be the local
+master browser.
+</para>
+
+<para>
+The "local master" parameter allows Samba to act as a local master
+browser.  The "preferred master" causes nmbd to force a browser
+election on startup and the "os level" parameter sets Samba high
+enough so that it should win any browser elections.
+</para>
+
+<para>
+If you have an NT machine on the subnet that you wish to
+be the local master browser then you can disable Samba from
+becoming a local master browser by setting the following
+options in the [global] section of the smb.conf file :
+</para>
+
+<para>
+<programlisting>
+        domain master = no
+        local master = no
+        preferred master = no
+        os level = 0
+</programlisting>
+</para>
+
+</sect1>
+
+<sect1>
+<title>Setting up Browsing in a DOMAIN</title>
+
+<para>
+If you are adding Samba servers to a Windows NT Domain then
+you must not set up a Samba server as a domain master browser.
+By default, a Windows NT Primary Domain Controller for a Domain
+name is also the Domain master browser for that name, and many
+things will break if a Samba server registers the Domain master
+browser NetBIOS name (DOMAIN&gt;1B&lt;) with WINS instead of the PDC.
+</para>
+
+<para>
+For subnets other than the one containing the Windows NT PDC
+you may set up Samba servers as local master browsers as
+described.  To make a Samba server a local master browser set 
+the following options in the [global] section of the smb.conf 
+file :
+</para>
+
+<para>
+<programlisting>
+        domain master = no
+        local master = yes
+        preferred master = yes
+        os level = 65
+</programlisting>
+</para>
+
+<para>
+If you wish to have a Samba server fight the election with machines
+on the same subnet you may set the "os level" parameter to lower
+levels.  By doing this you can tune the order of machines that
+will become local master browsers if they are running.  For
+more details on this see the section "FORCING SAMBA TO BE THE MASTER"
+below.
+</para>
+
+<para>
+If you have Windows NT machines that are members of the domain
+on all subnets, and you are sure they will always be running then
+you can disable Samba from taking part in browser elections and
+ever becoming a local master browser by setting following options 
+in the [global] section of the smb.conf file :
+</para>
+
+<para>
+<command>
+        domain master = no
+        local master = no
+        preferred master = no
+        os level = 0
+</command>
+</para>
+
+</sect1>
+
+<sect1>
+<title>Forcing samba to be the master</title>
+
+<para>
+Who becomes the "master browser" is determined by an election process
+using broadcasts.  Each election packet contains a number of parameters
+which determine what precedence (bias) a host should have in the
+election.  By default Samba uses a very low precedence and thus loses
+elections to just about anyone else.
+</para>
+
+<para>
+If you want Samba to win elections then just set the "os level" global
+option in smb.conf to a higher number.  It defaults to 0.  Using 34
+would make it win all elections over every other system (except other
+samba systems!)
+</para>
+
+<para>
+A "os level" of 2 would make it beat WfWg and Win95, but not NTAS.  A
+NTAS domain controller uses level 32.
+</para>
+
+<para>The maximum os level is 255</para>
+
+<para>
+If you want samba to force an election on startup, then set the
+"preferred master" global option in smb.conf to "yes".  Samba will
+then have a slight advantage over other potential master browsers
+that are not preferred master browsers.  Use this parameter with
+care, as if you have two hosts (whether they are windows 95 or NT or
+samba) on the same local subnet both set with "preferred master" to
+"yes", then periodically and continually they will force an election
+in order to become the local master browser.
+</para>
+
+<para>
+If you want samba to be a "domain master browser", then it is
+recommended that you also set "preferred master" to "yes", because
+samba will not become a domain master browser for the whole of your
+LAN or WAN if it is not also a local master browser on its own
+broadcast isolated subnet.
+</para>
+
+<para>
+It is possible to configure two samba servers to attempt to become
+the domain master browser for a domain.  The first server that comes
+up will be the domain master browser.  All other samba servers will
+attempt to become the domain master browser every 5 minutes.  They
+will find that another samba server is already the domain master
+browser and will fail.  This provides automatic redundancy, should
+the current domain master browser fail.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Making samba the domain master</title>
+
+<para>
+The domain master is responsible for collating the browse lists of
+multiple subnets so that browsing can occur between subnets.  You can
+make samba act as the domain master by setting "domain master = yes"
+in smb.conf.  By default it will not be a domain master.
+</para>
+
+<para>
+Note that you should NOT set Samba to be the domain master for a
+workgroup that has the same name as an NT Domain.
+</para>
+
+<para>
+When samba is the domain master and the master browser it will listen
+for master announcements (made roughly every twelve minutes) from local
+master browsers on other subnets and then contact them to synchronise
+browse lists.
+</para>
+
+<para>
+If you want samba to be the domain master then I suggest you also set
+the "os level" high enough to make sure it wins elections, and set
+"preferred master" to "yes", to get samba to force an election on
+startup.
+</para>
+
+<para>
+Note that all your servers (including samba) and clients should be
+using a WINS server to resolve NetBIOS names.  If your clients are only
+using broadcasting to resolve NetBIOS names, then two things will occur:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	your local master browsers will be unable to find a domain master
+	browser, as it will only be looking on the local subnet.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	if a client happens to get hold of a domain-wide browse list, and
+	a user attempts to access a host in that list, it will be unable to
+	resolve the NetBIOS name of that host.
+	</para>
+</listitem>
+</orderedlist>
+
+<para>
+If, however, both samba and your clients are using a WINS server, then:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	your local master browsers will contact the WINS server and, as long as
+	samba has registered that it is a domain master browser with the WINS
+	server, your local master browser will receive samba's ip address
+	as its domain master browser.
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	when a client receives a domain-wide browse list, and a user attempts
+	to access a host in that list, it will contact the WINS server to
+	resolve the NetBIOS name of that host.  as long as that host has
+	registered its NetBIOS name with the same WINS server, the user will
+	be able to see that host.  
+	</para>
+</listitem>
+</orderedlist>
+
+</sect1>
+
+<sect1>
+<title>Note about broadcast addresses</title>
+
+<para>
+If your network uses a "0" based broadcast address (for example if it
+ends in a 0) then you will strike problems.  Windows for Workgroups
+does not seem to support a 0's broadcast and you will probably find
+that browsing and name lookups won't work.
+</para>
+</sect1>
+
+<sect1>
+<title>Multiple interfaces</title>
+
+<para>
+Samba now supports machines with multiple network interfaces.  If you
+have multiple interfaces then you will need to use the "interfaces"
+option in smb.conf to configure them.  See smb.conf(5) for details.
+</para>
+</sect1>
+</chapter>
diff --git a/docs/docbook/projdoc/Bugs.sgml b/docs/docbook/projdoc/Bugs.sgml
new file mode 100644
index 0000000000..5a24458e08
--- /dev/null
+++ b/docs/docbook/projdoc/Bugs.sgml
@@ -0,0 +1,202 @@
+<chapter id="bugreport">
+
+<chapterinfo>
+	<author>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+		</affiliation>
+	</author>
+	<pubdate> 27 June 1997 </pubdate>
+</chapterinfo>
+
+<title>Reporting Bugs</title>
+
+<sect1>
+<title>Introduction</title>
+
+<para>
+The email address for bug reports is samba@samba.org
+</para>
+
+<para>
+Please take the time to read this file before you submit a bug
+report. Also, please see if it has changed between releases, as we
+may be changing the bug reporting mechanism at some time.
+</para>
+
+<para>
+Please also do as much as you can yourself to help track down the
+bug. Samba is maintained by a dedicated group of people who volunteer
+their time, skills and efforts. We receive far more mail about it than
+we can possibly answer, so you have a much higher chance of an answer
+and a fix if you send us a "developer friendly" bug report that lets
+us fix it fast. 
+</para>
+
+<para>
+Do not assume that if you post the bug to the comp.protocols.smb
+newsgroup or the mailing list that we will read it. If you suspect that your 
+problem is not a bug but a configuration problem then it is better to send 
+it to the Samba mailing list, as there are (at last count) 5000 other users on
+that list that may be able to help you.
+</para>
+
+<para>
+You may also like to look though the recent mailing list archives,
+which are conveniently accessible on the Samba web pages
+at http://samba.org/samba/ 
+</para>
+
+</sect1>
+
+<sect1>
+<title>General info</title>
+
+<para>
+Before submitting a bug report check your config for silly
+errors. Look in your log files for obvious messages that tell you that
+you've misconfigured something and run testparm to test your config
+file for correct syntax.
+</para>
+
+<para>
+Have you run through the <ulink url="Diagnosis.html">diagnosis</ulink>? 
+This is very important.
+</para>
+
+<para>
+If you include part of a log file with your bug report then be sure to
+annotate it with exactly what you were doing on the client at the
+time, and exactly what the results were.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Debug levels</title>
+
+<para>
+If the bug has anything to do with Samba behaving incorrectly as a
+server (like refusing to open a file) then the log files will probably
+be very useful. Depending on the problem a log level of between 3 and
+10 showing the problem may be appropriate. A higher level givesmore
+detail, but may use too much disk space.
+</para>
+
+<para>
+To set the debug level use <command>log level =</command> in your 
+<filename>smb.conf</filename>. You may also find it useful to set the log 
+level higher for just one machine and keep separate logs for each machine. 
+To do this use:
+</para>
+
+<para><programlisting>
+log level = 10
+log file = /usr/local/samba/lib/log.%m
+include = /usr/local/samba/lib/smb.conf.%m
+</programlisting></para>
+
+<para>
+then create a file 
+<filename>/usr/local/samba/lib/smb.conf.machine</filename> where
+"machine" is the name of the client you wish to debug. In that file
+put any smb.conf commands you want, for example 
+<command>log level=</command> may be useful. This also allows you to 
+experiment with different security systems, protocol levels etc on just 
+one machine.
+</para>
+
+<para>
+The <filename>smb.conf</filename> entry <command>log level =</command> 
+is synonymous with the entry <command>debuglevel =</command> that has been 
+used in older versions of Samba and is being retained for backwards 
+compatibility of smb.conf files.
+</para>
+
+<para>
+As the <command>log level =</command> value is increased you will record 
+a significantly increasing level of debugging information. For most 
+debugging operations you may not need a setting higher than 3. Nearly 
+all bugs can be tracked at a setting of 10, but be prepared for a VERY 
+large volume of log data.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Internal errors</title>
+
+<para>
+If you get a "INTERNAL ERROR" message in your log files it means that
+Samba got an unexpected signal while running. It is probably a
+segmentation fault and almost certainly means a bug in Samba (unless
+you have faulty hardware or system software)
+</para>
+
+<para>
+If the message came from smbd then it will probably be accompanied by
+a message which details the last SMB message received by smbd. This
+info is often very useful in tracking down the problem so please
+include it in your bug report.
+</para>
+
+<para>
+You should also detail how to reproduce the problem, if
+possible. Please make this reasonably detailed.
+</para>
+
+<para>
+You may also find that a core file appeared in a "corefiles"
+subdirectory of the directory where you keep your samba log
+files. This file is the most useful tool for tracking down the bug. To
+use it you do this:
+</para>
+
+<para><command>gdb smbd core</command></para>
+
+<para>
+adding appropriate paths to smbd and core so gdb can find them. If you
+don't have gdb then try "dbx". Then within the debugger use the
+command "where" to give a stack trace of where the problem
+occurred. Include this in your mail.
+</para>
+
+<para>
+If you known any assembly language then do a "disass" of the routine
+where the problem occurred (if its in a library routine then
+disassemble the routine that called it) and try to work out exactly
+where the problem is by looking at the surrounding code. Even if you
+don't know assembly then incuding this info in the bug report can be
+useful. 
+</para>
+</sect1>
+
+<sect1>
+<title>Attaching to a running process</title>
+
+<para>
+Unfortunately some unixes (in particular some recent linux kernels)
+refuse to dump a core file if the task has changed uid (which smbd
+does often). To debug with this sort of system you could try to attach
+to the running process using "gdb smbd PID" where you get PID from
+smbstatus. Then use "c" to continue and try to cause the core dump
+using the client. The debugger should catch the fault and tell you
+where it occurred.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Patches</title>
+
+<para>
+The best sort of bug report is one that includes a fix! If you send us
+patches please use <command>diff -u</command> format if your version of 
+diff supports it, otherwise use <command>diff -c4</command>. Make sure 
+your do the diff against a clean version of the source and let me know 
+exactly what version you used. 
+</para>
+
+</sect1>
+</chapter>
+
diff --git a/docs/docbook/projdoc/Diagnosis.sgml b/docs/docbook/projdoc/Diagnosis.sgml
new file mode 100644
index 0000000000..20b2ccee08
--- /dev/null
+++ b/docs/docbook/projdoc/Diagnosis.sgml
@@ -0,0 +1,509 @@
+<chapter id="diagnosis">
+<chapterinfo>
+	<author>
+		<firstname>Andrew</firstname><surname>Tridgell</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address><email>tridge@samba.org</email></address>
+		</affiliation>
+	</author>
+	<pubdate> 1 November 1999</pubdate>
+</chapterinfo>
+
+<title>Diagnosing your samba server</title>
+
+<sect1>
+<title>Introduction</title>
+
+<para>
+This file contains a list of tests you can perform to validate your
+Samba server. It also tells you what the likely cause of the problem
+is if it fails any one of these steps. If it passes all these tests
+then it is probably working fine.
+</para>
+
+<para>
+You should do ALL the tests, in the order shown. I have tried to
+carefully choose them so later tests only use capabilities verified in
+the earlier tests.
+</para>
+
+<para>
+If you send me an email saying "it doesn't work" and you have not
+followed this test procedure then you should not be surprised if I
+ignore your email.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Assumptions</title>
+
+<para>
+In all of the tests I assume you have a Samba server called BIGSERVER
+and a PC called ACLIENT both in workgroup TESTGROUP. I also assume the
+PC is running windows for workgroups with a recent copy of the
+microsoft tcp/ip stack. Alternatively, your PC may be running Windows
+95 or Windows NT (Workstation or Server).
+</para>
+
+<para>
+The procedure is similar for other types of clients.
+</para>
+
+<para>
+I also assume you know the name of an available share in your
+smb.conf. I will assume this share is called "tmp". You can add a
+"tmp" share like by adding the following to smb.conf:
+</para>
+
+<para><programlisting>
+
+[tmp]
+ comment = temporary files 
+ path = /tmp
+ read only = yes
+
+</programlisting>
+</para>
+
+<para>
+THESE TESTS ASSUME VERSION 2.0.6 OR LATER OF THE SAMBA SUITE. SOME
+COMMANDS SHOWN DID NOT EXIST IN EARLIER VERSIONS
+</para>
+
+<para>
+Please pay attention to the error messages you receive. If any error message
+reports that your server is being unfriendly you should first check that you
+IP name resolution is correctly set up. eg: Make sure your /etc/resolv.conf
+file points to name servers that really do exist.
+</para>
+
+<para>
+Also, if you do not have DNS server access for name resolution please check
+that the settings for your smb.conf file results in "dns proxy = no". The
+best way to check this is with "testparm smb.conf"
+</para>
+
+</sect1>
+
+<sect1>
+<title>Tests</title>
+
+<sect2>
+<title>Test 1</title>
+<para>
+In the directory in which you store your smb.conf file, run the command
+"testparm smb.conf". If it reports any errors then your smb.conf
+configuration file is faulty.
+</para>
+
+<para>
+Note:	Your smb.conf file may be located in: <filename>/etc</filename>
+	Or in:   <filename>/usr/local/samba/lib</filename>
+</para>
+</sect2>
+
+<sect2>
+<title>Test 2</title>
+
+<para>
+Run the command "ping BIGSERVER" from the PC and "ping ACLIENT" from
+the unix box. If you don't get a valid response then your TCP/IP
+software is not correctly installed. 
+</para>
+
+<para>
+Note that you will need to start a "dos prompt" window on the PC to
+run ping.
+</para>
+
+<para>
+If you get a message saying "host not found" or similar then your DNS
+software or /etc/hosts file is not correctly setup. It is possible to
+run samba without DNS entries for the server and client, but I assume
+you do have correct entries for the remainder of these tests. 
+</para>
+
+<para>
+Another reason why ping might fail is if your host is running firewall 
+software. You will need to relax the rules to let in the workstation
+in question, perhaps by allowing access from another subnet (on Linux
+this is done via the ipfwadm program.)
+</para>
+</sect2>
+
+<sect2>
+<title>Test 3</title>
+
+<para>
+Run the command "smbclient -L BIGSERVER" on the unix box. You
+should get a list of available shares back. 
+</para>
+
+<para>
+If you get a error message containing the string "Bad password" then
+you probably have either an incorrect "hosts allow", "hosts deny" or
+"valid users" line in your smb.conf, or your guest account is not
+valid. Check what your guest account is using "testparm" and
+temporarily remove any "hosts allow", "hosts deny", "valid users" or
+"invalid users" lines.
+</para>
+
+<para>
+If you get a "connection refused" response then the smbd server may
+not be running. If you installed it in inetd.conf then you probably edited
+that file incorrectly. If you installed it as a daemon then check that
+it is running, and check that the netbios-ssn port is in a LISTEN
+state using "netstat -a".
+</para>
+
+<para>
+If you get a "session request failed" then the server refused the
+connection. If it says "Your server software is being unfriendly" then
+its probably because you have invalid command line parameters to smbd,
+or a similar fatal problem with the initial startup of smbd. Also
+check your config file (smb.conf) for syntax errors with "testparm"
+and that the various directories where samba keeps its log and lock
+files exist.
+</para>
+
+<para>
+There are a number of reasons for which smbd may refuse or decline
+a session request. The most common of these involve one or more of
+the following smb.conf file entries:
+</para>
+
+<para><programlisting>
+	hosts deny = ALL
+	hosts allow = xxx.xxx.xxx.xxx/yy
+	bind interfaces only = Yes
+</programlisting></para>
+
+<para>
+In the above, no allowance has been made for any session requests that
+will automatically translate to the loopback adaptor address 127.0.0.1.
+To solve this problem change these lines to:
+</para>
+
+<para><programlisting>
+	hosts deny = ALL
+	hosts allow = xxx.xxx.xxx.xxx/yy 127.
+</programlisting></para>
+
+<para>
+Do NOT use the "bind interfaces only" parameter where you may wish to
+use the samba password change facility, or where smbclient may need to
+access local service for name resolution or for local resource
+connections. (Note: the "bind interfaces only" parameter deficiency
+where it will not allow connections to the loopback address will be
+fixed soon).
+</para>
+
+<para>
+Another common cause of these two errors is having something already running 
+on port 139, such as Samba (ie: smbd is running from inetd already) or
+something like Digital's Pathworks. Check your inetd.conf file before trying
+to start smbd as a daemon, it can avoid a lot of frustration!
+</para>
+
+<para>
+And yet another possible cause for failure of TEST 3 is when the subnet mask
+and / or broadcast address settings are incorrect. Please check that the
+network interface IP Address / Broadcast Address / Subnet Mask settings are
+correct and that Samba has correctly noted these in the log.nmb file.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 4</title>
+
+<para>
+Run the command "nmblookup -B BIGSERVER __SAMBA__". You should get the
+IP address of your Samba server back.
+</para>
+
+<para>
+If you don't then nmbd is incorrectly installed. Check your inetd.conf
+if you run it from there, or that the daemon is running and listening
+to udp port 137.
+</para>
+
+<para>
+One common problem is that many inetd implementations can't take many
+parameters on the command line. If this is the case then create a
+one-line script that contains the right parameters and run that from
+inetd.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 5</title>
+
+<para>run the command <command>nmblookup -B ACLIENT '*'</command></para>
+
+<para>
+You should get the PCs IP address back. If you don't then the client
+software on the PC isn't installed correctly, or isn't started, or you
+got the name of the PC wrong. 
+</para>
+
+<para>
+If ACLIENT doesn't resolve via DNS then use the IP address of the
+client in the above test.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 6</title>
+
+<para>
+Run the command <command>nmblookup -d 2 '*'</command>
+</para>
+
+<para>
+This time we are trying the same as the previous test but are trying
+it via a broadcast to the default broadcast address. A number of
+Netbios/TCPIP hosts on the network should respond, although Samba may
+not catch all of the responses in the short time it listens. You
+should see "got a positive name query response" messages from several
+hosts.
+</para>
+
+<para>
+If this doesn't give a similar result to the previous test then
+nmblookup isn't correctly getting your broadcast address through its
+automatic mechanism. In this case you should experiment use the
+"interfaces" option in smb.conf to manually configure your IP
+address, broadcast and netmask. 
+</para>
+
+<para>
+If your PC and server aren't on the same subnet then you will need to
+use the -B option to set the broadcast address to the that of the PCs
+subnet.
+</para>
+
+<para>
+This test will probably fail if your subnet mask and broadcast address are
+not correct. (Refer to TEST 3 notes above).
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 7</title>
+
+<para>
+Run the command <command>smbclient //BIGSERVER/TMP</command>. You should 
+then be prompted for a password. You should use the password of the account
+you are logged into the unix box with. If you want to test with
+another account then add the -U &gt;accountname&lt; option to the end of
+the command line.  eg: 
+<command>smbclient //bigserver/tmp -Ujohndoe</command>
+</para>
+
+<para>
+Note: It is possible to specify the password along with the username
+as follows:
+<command>smbclient //bigserver/tmp -Ujohndoe%secret</command>
+</para>
+
+<para>
+Once you enter the password you should get the "smb>" prompt. If you
+don't then look at the error message. If it says "invalid network
+name" then the service "tmp" is not correctly setup in your smb.conf.
+</para>
+
+<para>
+If it says "bad password" then the likely causes are:
+</para>
+
+<orderedlist>
+<listitem>
+	<para>
+	you have shadow passords (or some other password system) but didn't
+	compile in support for them in smbd
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	your "valid users" configuration is incorrect
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	you have a mixed case password and you haven't enabled the "password
+	level" option at a high enough level
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	the "path =" line in smb.conf is incorrect. Check it with testparm
+	</para>
+</listitem>
+
+<listitem>
+	<para>
+	you enabled password encryption but didn't create the SMB encrypted
+	password file
+	</para>
+</listitem>
+</orderedlist>
+
+<para>
+Once connected you should be able to use the commands 
+<command>dir</command> <command>get</command> <command>put</command> etc. 
+Type <command>help &gt;command&lt;</command> for instructions. You should
+especially check that the amount of free disk space shown is correct
+when you type <command>dir</command>.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 8</title>
+
+<para>
+On the PC type the command <command>net view \\BIGSERVER</command>. You will 
+need to do this from within a "dos prompt" window. You should get back a 
+list of available shares on the server.
+</para>
+
+<para>
+If you get a "network name not found" or similar error then netbios
+name resolution is not working. This is usually caused by a problem in
+nmbd. To overcome it you could do one of the following (you only need
+to choose one of them):
+</para>
+
+<orderedlist>
+<listitem><para>
+	fixup the nmbd installation
+</para></listitem>
+
+<listitem><para>
+	add the IP address of BIGSERVER to the "wins server" box in the
+	advanced tcp/ip setup on the PC.
+</para></listitem>
+
+<listitem><para>
+	enable windows name resolution via DNS in the advanced section of
+	the tcp/ip setup
+</para></listitem>
+
+<listitem><para>
+	add BIGSERVER to your lmhosts file on the PC.
+</para></listitem>
+</orderedlist>
+
+<para>
+If you get a "invalid network name" or "bad password error" then the
+same fixes apply as they did for the "smbclient -L" test above. In
+particular, make sure your "hosts allow" line is correct (see the man
+pages)
+</para>
+
+<para>
+Also, do not overlook that fact that when the workstation requests the
+connection to the samba server it will attempt to connect using the 
+name with which you logged onto your Windows machine. You need to make
+sure that an account exists on your Samba server with that exact same
+name and password.
+</para>
+
+<para>
+If you get "specified computer is not receiving requests" or similar
+it probably means that the host is not contactable via tcp services.
+Check to see if the host is running tcp wrappers, and if so add an entry in
+the hosts.allow file for your client (or subnet, etc.)
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 9</title>
+
+<para>
+Run the command <command>net use x: \\BIGSERVER\TMP</command>. You should 
+be prompted for a password then you should get a "command completed 
+successfully" message. If not then your PC software is incorrectly 
+installed or your smb.conf is incorrect. make sure your "hosts allow" 
+and other config lines in smb.conf are correct.
+</para>
+
+<para>
+It's also possible that the server can't work out what user name to
+connect you as. To see if this is the problem add the line "user =
+USERNAME" to the [tmp] section of smb.conf where "USERNAME" is the
+username corresponding to the password you typed. If you find this
+fixes things you may need the username mapping option.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 10</title>
+
+<para>
+Run the command <command>nmblookup -M TESTGROUP</command> where 
+TESTGROUP is the name of the workgroup that your Samba server and 
+Windows PCs belong to. You should get back the IP address of the 
+master browser for that workgroup.
+</para>
+
+<para>
+If you don't then the election process has failed. Wait a minute to
+see if it is just being slow then try again. If it still fails after
+that then look at the browsing options you have set in smb.conf. Make
+sure you have <command>preferred master = yes</command> to ensure that 
+an election is held at startup.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Test 11</title>
+
+<para>
+From file manager try to browse the server. Your samba server should
+appear in the browse list of your local workgroup (or the one you
+specified in smb.conf). You should be able to double click on the name
+of the server and get a list of shares. If you get a "invalid
+password" error when you do then you are probably running WinNT and it
+is refusing to browse a server that has no encrypted password
+capability and is in user level security mode. In this case either set
+<command>security = server</command> AND 
+<command>password server = Windows_NT_Machine</command> in your
+smb.conf file, or enable encrypted passwords AFTER compiling in support
+for encrypted passwords (refer to the Makefile).
+</para>
+
+</sect2>
+</sect1>
+
+<sect1>
+<title>Still having troubles?</title>
+
+<para>
+Try the mailing list or newsgroup, or use the ethereal utility to
+sniff the problem. The official samba mailing list can be reached at
+<ulink url="mailto:samba@samba.org">samba@samba.org</ulink>. To find 
+out more about samba and how to subscribe to the mailing list check 
+out the samba web page at 
+<ulink url="http://samba.org/samba">http://samba.org/samba</ulink>
+</para>
+
+<para>
+Also look at the other docs in the Samba package!
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/docbook/projdoc/Printing.sgml b/docs/docbook/projdoc/Printing.sgml
new file mode 100644
index 0000000000..cb7e5cdfb7
--- /dev/null
+++ b/docs/docbook/projdoc/Printing.sgml
@@ -0,0 +1,398 @@
+<chapter id="printing_debug">
+<chapterinfo>
+	<author>
+		<firstname>Patrick</firstname><surname>Powell</surname>
+		<affiliation>
+			<address><email>papowell@lprng.org</email></address>
+		</affiliation>
+	</author>
+	<pubdate>11 August 2000</pubdate>
+</chapterinfo>
+
+<title>Debugging Printing Problems</title>
+
+<sect1>
+<title>Introduction</title>
+
+<para>
+This is a short description of how to debug printing problems with
+Samba. This describes how to debug problems with printing from a SMB
+client to a Samba server, not the other way around. For the reverse
+see the examples/printing directory.
+</para>
+
+<para>
+Ok, so you want to print to a Samba server from your PC. The first
+thing you need to understand is that Samba does not actually do any
+printing itself, it just acts as a middleman between your PC client
+and your Unix printing subsystem. Samba receives the file from the PC
+then passes the file to a external "print command". What print command
+you use is up to you.
+</para>
+
+<para>
+The whole things is controlled using options in smb.conf. The most
+relevant options (which you should look up in the smb.conf man page)
+are:
+</para>
+
+<para><programlisting>
+      [global]
+        print command     - send a file to a spooler
+        lpq command       - get spool queue status
+        lprm command      - remove a job
+      [printers]
+        path = /var/spool/lpd/samba
+</programlisting></para>
+
+<para>
+The following are nice to know about:
+</para>
+
+<para><programlisting>
+        queuepause command   - stop a printer or print queue
+        queueresume command  - start a printer or print queue
+</programlisting></para>
+
+<para>
+Example:
+</para>
+
+<para><programlisting>
+        print command = /usr/bin/lpr -r -P%p %s
+        lpq command   = /usr/bin/lpq    -P%p %s
+        lprm command  = /usr/bin/lprm   -P%p %j
+        queuepause command = /usr/sbin/lpc -P%p stop
+        queuepause command = /usr/sbin/lpc -P%p start
+</programlisting></para>
+
+<para>
+Samba should set reasonable defaults for these depending on your
+system type, but it isn't clairvoyant. It is not uncommon that you
+have to tweak these for local conditions.  The commands should
+always have fully specified pathnames,  as the smdb may not have
+the correct PATH values.
+</para>
+
+<para>
+When you send a job to Samba to be printed,  it will make a temporary
+copy of it in the directory specified in the [printers] section.
+and it should be periodically cleaned out.  The lpr -r option
+requests that the temporary copy be removed after printing; If
+printing fails then you might find leftover files in this directory,
+and it should be periodically cleaned out.  Samba used the lpq
+command to determine the "job number" assigned to your print job
+by the spooler.
+</para>
+
+<para>
+The %&gt;letter&lt; are "macros" that get dynamically replaced with appropriate
+values when they are used. The %s gets replaced with the name of the spool
+file that Samba creates and the %p gets replaced with the name of the
+printer. The %j gets replaced with the "job number" which comes from
+the lpq output.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Debugging printer problems</title>
+
+<para>
+One way to debug printing problems is to start by replacing these
+command with shell scripts that record the arguments and the contents
+of the print file. A simple example of this kind of things might
+be:
+</para>
+
+<para><programlisting>
+	print command = /tmp/saveprint %p %s
+
+    #!/bin/saveprint
+    # we make sure that we are the right user
+    /usr/bin/id -p >/tmp/tmp.print
+    # we run the command and save the error messages
+    # replace the command with the one appropriate for your system
+    /usr/bin/lpr -r -P$1 $2 2>>&/tmp/tmp.print
+</programlisting></para>
+
+<para>
+Then you print a file and try removing it.  You may find that the
+print queue needs to be stopped in order to see the queue status
+and remove the job:
+</para>
+
+<para><programlisting>
+
+h4: {42} % echo hi >/tmp/hi
+h4: {43} % smbclient //localhost/lw4
+added interface ip=10.0.0.4 bcast=10.0.0.255 nmask=255.255.255.0
+Password: 
+Domain=[ASTART] OS=[Unix] Server=[Samba 2.0.7]
+smb: \> print /tmp/hi
+putting file /tmp/hi as hi-17534 (0.0 kb/s) (average 0.0 kb/s)
+smb: \> queue
+1049     3            hi-17534
+smb: \> cancel 1049
+Error cancelling job 1049 : code 0
+smb: \> cancel 1049
+Job 1049 cancelled
+smb: \> queue
+smb: \> exit
+</programlisting></para>
+
+<para>
+The 'code 0' indicates that the job was removed.  The comment
+by the  smbclient is a bit misleading on this.
+You can observe the command output and then and look at the
+/tmp/tmp.print file to see what the results are.  You can quickly
+find out if the problem is with your printing system.  Often people
+have problems with their /etc/printcap file or permissions on
+various print queues.
+</para>
+</sect1>
+
+<sect1>
+<title>What printers do I have?</title>
+
+<para>
+You can use the 'testprns' program to check to see if the printer
+name you are using is recognized by Samba.  For example,  you can
+use:
+</para>
+
+<para><programlisting>
+    testprns printer /etc/printcap
+</programlisting></para>
+
+<para>
+Samba can get its printcap information from a file or from a program.
+You can try the following to see the format of the extracted
+information:
+</para>
+
+<para><programlisting>
+    testprns -a printer /etc/printcap
+
+    testprns -a printer '|/bin/cat printcap'
+</programlisting></para>
+
+</sect1>
+
+<sect1>
+<title>Setting up printcap and print servers</title>
+
+<para>
+You may need to set up some printcaps for your Samba system to use.
+It is strongly recommended that you use the facilities provided by
+the print spooler to set up queues and printcap information.
+</para>
+
+<para>
+Samba requires either a printcap or program to deliver printcap
+information.  This printcap information has the format:
+</para>
+
+<para><programlisting>
+  name|alias1|alias2...:option=value:...
+</programlisting></para>
+
+<para>
+For almost all printing systems, the printer 'name' must be composed
+only of alphanumeric or underscore '_' characters.  Some systems also
+allow hyphens ('-') as well.  An alias is an alternative name for the
+printer,  and an alias with a space in it is used as a 'comment'
+about the printer.  The printcap format optionally uses a \ at the end of lines
+to extend the printcap to multiple lines.
+</para>
+
+<para>
+Here are some examples of printcap files:
+</para>
+
+<para>
+<orderedlist>
+<listitem><para>
+pr              just printer name
+</para></listitem>
+<listitem><para>
+pr|alias        printer name and alias
+</para></listitem>
+<listitem><para>
+pr|My Printer   printer name, alias used as comment
+</para></listitem>
+<listitem><para>
+pr:sh:\        Same as pr:sh:cm= testing
+  :cm= \ 
+  testing
+</para></listitem>
+<listitem><para>
+pr:sh           Same as pr:sh:cm= testing
+  :cm= testing
+</para></listitem>
+</orderedlist>
+</para>
+
+<para>
+Samba reads the printcap information when first started.  If you make
+changes in the printcap information, then you must do the following:
+</para>
+
+<orderedlist>
+
+<listitem><para>
+make sure that the print spooler is aware of these changes.
+The LPRng system uses the 'lpc reread' command to do this.
+</para></listitem>
+
+<listitem><para>
+make sure that the spool queues, etc., exist and have the
+correct permissions.  The LPRng system uses the 'checkpc -f'
+command to do this.
+</para></listitem>
+
+<listitem><para>
+You now should send a SIGHUP signal to the smbd server to have
+it reread the printcap information.
+</para></listitem>
+</orderedlist>
+
+</sect1>
+
+<sect1>
+<title>Job sent, no output</title>
+
+<para>
+This is the most frustrating part of printing.  You may have sent the
+job,  verified that the job was forwarded,  set up a wrapper around
+the command to send the file,  but there was no output from the printer.
+</para>
+
+<para>
+First,  check to make sure that the job REALLY is getting to the
+right print queue.  If you are using a BSD or LPRng print spooler,
+you can temporarily stop the printing of jobs.  Jobs can still be
+submitted, but they will not be printed.  Use:
+</para>
+
+<para><programlisting>
+  lpc -Pprinter stop
+</programlisting></para>
+
+<para>
+Now submit a print job and then use 'lpq -Pprinter' to see if the
+job is in the print queue.  If it is not in the print queue then
+you will have to find out why it is not being accepted for printing.
+</para>
+
+<para>
+Next, you may want to check to see what the format of the job really
+was.  With the assistance of the system administrator you can view
+the submitted jobs files.  You may be surprised to find that these
+are not in what you would expect to call a printable format.
+You can use the UNIX 'file' utitily to determine what the job
+format actually is:
+</para>
+
+<para><programlisting>
+    cd /var/spool/lpd/printer   # spool directory of print jobs
+    ls                          # find job files
+    file dfA001myhost
+</programlisting></para>
+
+<para>
+You should make sure that your printer supports this format OR that
+your system administrator has installed a 'print filter' that will
+convert the file to a format appropriate for your printer.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Job sent, strange output</title>
+
+<para>
+Once you have the job printing, you can then start worrying about
+making it print nicely.
+</para>
+
+<para>
+The most common problem is extra pages of output: banner pages
+OR blank pages at the end.
+</para>
+
+<para>
+If you are getting banner pages,  check and make sure that the
+printcap option or printer option is configured for no banners.
+If you have a printcap,  this is the :sh (suppress header or banner
+page) option.  You should have the following in your printer.
+</para>
+
+<para><programlisting>
+   printer: ... :sh
+</programlisting></para>
+
+<para>
+If you have this option and are still getting banner pages,  there
+is a strong chance that your printer is generating them for you
+automatically.  You should make sure that banner printing is disabled
+for the printer.  This usually requires using the printer setup software
+or procedures supplied by the printer manufacturer.
+</para>
+
+<para>
+If you get an extra page of output,  this could be due to problems
+with your job format,  or if you are generating PostScript jobs,
+incorrect setting on your printer driver on the MicroSoft client.
+For example, under Win95 there is a option:
+</para>
+
+<para><programlisting>
+  Printers|Printer Name|(Right Click)Properties|Postscript|Advanced|
+</programlisting></para>
+
+<para>
+that allows you to choose if a Ctrl-D is appended to all jobs.
+This is a very bad thing to do, as most spooling systems will
+automatically add a ^D to the end of the job if it is detected as
+PostScript.  The multiple ^D may cause an additional page of output.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Raw PostScript printed</title>
+
+<para>
+This is a problem that is usually caused by either the print spooling
+system putting information at the start of the print job that makes
+the printer think the job is a text file, or your printer simply
+does not support PostScript.  You may need to enable 'Automatic
+Format Detection' on your printer.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Advanced Printing</title>
+
+<para>
+Note that you can do some pretty magic things by using your
+imagination with the "print command" option and some shell scripts.
+Doing print accounting is easy by passing the %U option to a print
+command shell script. You could even make the print command detect
+the type of output and its size and send it to an appropriate
+printer.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Real debugging</title>
+
+<para>
+If the above debug tips don't help, then maybe you need to bring in
+the bug guns, system tracing. See Tracing.txt in this directory.
+</para>
+</sect1>
+</chapter>
diff --git a/docs/docbook/projdoc/Speed.sgml b/docs/docbook/projdoc/Speed.sgml
new file mode 100644
index 0000000000..17adf10429
--- /dev/null
+++ b/docs/docbook/projdoc/Speed.sgml
@@ -0,0 +1,578 @@
+<chapter id="speed">
+
+<chapterinfo>
+	<author>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address><email>samba@samba.org</email></address>
+		</affiliation>
+	</author>
+	<author>
+		<firstname>Paul</firstname><surname>Cochrane</surname>
+		<affiliation>
+			<orgname>Dundee Limb Fitting Centre</orgname>
+			<address><email>paulc@dth.scot.nhs.uk</email></address>
+		</affiliation>
+	</author>
+</chapterinfo>
+
+<title>Samba performance issues</title>
+
+<sect1>
+<title>Comparisons</title>
+
+<para>
+The Samba server uses TCP to talk to the client. Thus if you are
+trying to see if it performs well you should really compare it to
+programs that use the same protocol. The most readily available
+programs for file transfer that use TCP are ftp or another TCP based
+SMB server.
+</para>
+
+<para>
+If you want to test against something like a NT or WfWg server then
+you will have to disable all but TCP on either the client or
+server. Otherwise you may well be using a totally different protocol
+(such as Netbeui) and comparisons may not be valid.
+</para>
+
+<para>
+Generally you should find that Samba performs similarly to ftp at raw
+transfer speed. It should perform quite a bit faster than NFS,
+although this very much depends on your system.
+</para>
+
+<para>
+Several people have done comparisons between Samba and Novell, NFS or
+WinNT. In some cases Samba performed the best, in others the worst. I
+suspect the biggest factor is not Samba vs some other system but the
+hardware and drivers used on the various systems. Given similar
+hardware Samba should certainly be competitive in speed with other
+systems.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Oplocks</title>
+
+<sect2>
+<title>Overview</title>
+
+<para>
+Oplocks are the way that SMB clients get permission from a server to
+locally cache file operations. If a server grants an oplock
+(opportunistic lock) then the client is free to assume that it is the
+only one accessing the file and it will agressively cache file
+data. With some oplock types the client may even cache file open/close
+operations. This can give enormous performance benefits.
+</para>
+
+<para>
+With the release of Samba 1.9.18 we now correctly support opportunistic 
+locks. This is turned on by default, and can be turned off on a share-
+by-share basis by setting the parameter :
+</para>
+
+<para>
+<command>oplocks = False</command>
+</para>
+
+<para>
+We recommend that you leave oplocks on however, as current benchmark
+tests with NetBench seem to give approximately a 30% improvement in
+speed with them on. This is on average however, and the actual 
+improvement seen can be orders of magnitude greater, depending on
+what the client redirector is doing.
+</para>
+
+<para>
+Previous to Samba 1.9.18 there was a 'fake oplocks' option. This
+option has been left in the code for backwards compatibility reasons
+but it's use is now deprecated. A short summary of what the old
+code did follows.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Level2 Oplocks</title>
+
+<para>
+With Samba 2.0.5 a new capability - level2 (read only) oplocks is
+supported (although the option is off by default - see the smb.conf
+man page for details). Turning on level2 oplocks (on a share-by-share basis)
+by setting the parameter :
+</para>
+
+<para>
+<command>level2 oplocks = true</command>
+</para>
+
+<para>
+should speed concurrent access to files that are not commonly written
+to, such as application serving shares (ie. shares that contain common
+.EXE files - such as a Microsoft Office share) as it allows clients to
+read-ahread cache copies of these files.
+</para>
+
+</sect2>
+
+<sect2>
+<title>Old 'fake oplocks' option - deprecated</title>
+
+<para>
+Samba can also fake oplocks, by granting a oplock whenever a client 
+asks for one. This is controlled using the smb.conf option "fake 
+oplocks". If you set "fake oplocks = yes" then you are telling the 
+client that it may agressively cache the file data for all opens.
+</para>
+
+<para>
+Enabling 'fake oplocks' on all read-only shares or shares that you know
+will only be accessed from one client at a time you will see a big
+performance improvement on many operations. If you enable this option
+on shares where multiple clients may be accessing the files read-write
+at the same time you can get data corruption.
+</para>
+
+</sect2>
+</sect1>
+
+<sect1>
+<title>Socket options</title>
+
+<para>
+There are a number of socket options that can greatly affect the
+performance of a TCP based server like Samba.
+</para>
+
+<para>
+The socket options that Samba uses are settable both on the command
+line with the -O option, or in the smb.conf file.
+</para>
+
+<para>
+The "socket options" section of the smb.conf manual page describes how
+to set these and gives recommendations.
+</para>
+
+<para>
+Getting the socket options right can make a big difference to your
+performance, but getting them wrong can degrade it by just as
+much. The correct settings are very dependent on your local network.
+</para>
+
+<para>
+The socket option TCP_NODELAY is the one that seems to make the
+biggest single difference for most networks. Many people report that
+adding "socket options = TCP_NODELAY" doubles the read performance of
+a Samba drive. The best explanation I have seen for this is that the
+Microsoft TCP/IP stack is slow in sending tcp ACKs.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Read size</title>
+
+<para>
+The option "read size" affects the overlap of disk reads/writes with
+network reads/writes. If the amount of data being transferred in
+several of the SMB commands (currently SMBwrite, SMBwriteX and
+SMBreadbraw) is larger than this value then the server begins writing
+the data before it has received the whole packet from the network, or
+in the case of SMBreadbraw, it begins writing to the network before
+all the data has been read from disk.
+</para>
+
+<para>
+This overlapping works best when the speeds of disk and network access
+are similar, having very little effect when the speed of one is much
+greater than the other.
+</para>
+
+<para>
+The default value is 16384, but very little experimentation has been
+done yet to determine the optimal value, and it is likely that the best
+value will vary greatly between systems anyway. A value over 65536 is
+pointless and will cause you to allocate memory unnecessarily.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Max xmit</title>
+
+<para>
+At startup the client and server negotiate a "maximum transmit" size,
+which limits the size of nearly all SMB commands. You can set the
+maximum size that Samba will negotiate using the "max xmit = " option
+in smb.conf. Note that this is the maximum size of SMB request that 
+Samba will accept, but not the maximum size that the *client* will accept.
+The client maximum receive size is sent to Samba by the client and Samba
+honours this limit.
+</para>
+
+<para>
+It defaults to 65536 bytes (the maximum), but it is possible that some
+clients may perform better with a smaller transmit unit. Trying values
+of less than 2048 is likely to cause severe problems.
+</para>
+
+<para>
+In most cases the default is the best option.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Locking</title>
+
+<para>
+By default Samba does not implement strict locking on each read/write
+call (although it did in previous versions). If you enable strict
+locking (using "strict locking = yes") then you may find that you
+suffer a severe performance hit on some systems.
+</para>
+
+<para>
+The performance hit will probably be greater on NFS mounted
+filesystems, but could be quite high even on local disks.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Share modes</title>
+
+<para>
+Some people find that opening files is very slow. This is often
+because of the "share modes" code needed to fully implement the dos
+share modes stuff. You can disable this code using "share modes =
+no". This will gain you a lot in opening and closing files but will
+mean that (in some cases) the system won't force a second user of a
+file to open the file read-only if the first has it open
+read-write. For many applications that do their own locking this
+doesn't matter, but for some it may. Most Windows applications
+depend heavily on "share modes" working correctly and it is
+recommended that the Samba share mode support be left at the
+default of "on".
+</para>
+
+<para>
+The share mode code in Samba has been re-written in the 1.9.17
+release following tests with the Ziff-Davis NetBench PC Benchmarking
+tool. It is now believed that Samba 1.9.17 implements share modes
+similarly to Windows NT.
+</para>
+
+<para>
+NOTE: In the most recent versions of Samba there is an option to use
+shared memory via mmap() to implement the share modes. This makes
+things much faster. See the Makefile for how to enable this.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Log level</title>
+
+<para>
+If you set the log level (also known as "debug level") higher than 2
+then you may suffer a large drop in performance. This is because the
+server flushes the log file after each operation, which can be very
+expensive. 
+</para>
+</sect1>
+
+<sect1>
+<title>Wide lines</title>
+
+<para>
+The "wide links" option is now enabled by default, but if you disable
+it (for better security) then you may suffer a performance hit in
+resolving filenames. The performance loss is lessened if you have
+"getwd cache = yes", which is now the default.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Read raw</title>
+
+<para>
+The "read raw" operation is designed to be an optimised, low-latency
+file read operation. A server may choose to not support it,
+however. and Samba makes support for "read raw" optional, with it
+being enabled by default.
+</para>
+
+<para>
+In some cases clients don't handle "read raw" very well and actually
+get lower performance using it than they get using the conventional
+read operations. 
+</para>
+
+<para>
+So you might like to try "read raw = no" and see what happens on your
+network. It might lower, raise or not affect your performance. Only
+testing can really tell.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Write raw</title>
+
+<para>
+The "write raw" operation is designed to be an optimised, low-latency
+file write operation. A server may choose to not support it,
+however. and Samba makes support for "write raw" optional, with it
+being enabled by default.
+</para>
+
+<para>
+Some machines may find "write raw" slower than normal write, in which
+case you may wish to change this option.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Read prediction</title>
+
+<para>
+Samba can do read prediction on some of the SMB commands. Read
+prediction means that Samba reads some extra data on the last file it
+read while waiting for the next SMB command to arrive. It can then
+respond more quickly when the next read request arrives.
+</para>
+
+<para>
+This is disabled by default. You can enable it by using "read
+prediction = yes".
+</para>
+
+<para>
+Note that read prediction is only used on files that were opened read
+only.
+</para>
+
+<para>
+Read prediction should particularly help for those silly clients (such
+as "Write" under NT) which do lots of very small reads on a file.
+</para>
+
+<para>
+Samba will not read ahead more data than the amount specified in the
+"read size" option. It always reads ahead on 1k block boundaries.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Memory mapping</title>
+
+<para>
+Samba supports reading files via memory mapping them. One some
+machines this can give a large boost to performance, on others it
+makes not difference at all, and on some it may reduce performance.
+</para>
+
+<para>
+To enable you you have to recompile Samba with the -DUSE_MMAP option
+on the FLAGS line of the Makefile.
+</para>
+
+<para>
+Note that memory mapping is only used on files opened read only, and
+is not used by the "read raw" operation. Thus you may find memory
+mapping is more effective if you disable "read raw" using "read raw =
+no".
+</para>
+
+</sect1>
+
+<sect1>
+<title>Slow Clients</title>
+
+<para>
+One person has reported that setting the protocol to COREPLUS rather
+than LANMAN2 gave a dramatic speed improvement (from 10k/s to 150k/s).
+</para>
+
+<para>
+I suspect that his PC's (386sx16 based) were asking for more data than
+they could chew. I suspect a similar speed could be had by setting
+"read raw = no" and "max xmit = 2048", instead of changing the
+protocol. Lowering the "read size" might also help.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Slow Logins</title>
+
+<para>
+Slow logins are almost always due to the password checking time. Using
+the lowest practical "password level" will improve things a lot. You
+could also enable the "UFC crypt" option in the Makefile.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Client tuning</title>
+
+<para>
+Often a speed problem can be traced to the client. The client (for
+example Windows for Workgroups) can often be tuned for better TCP
+performance.
+</para>
+
+<para>
+See your client docs for details. In particular, I have heard rumours
+that the WfWg options TCPWINDOWSIZE and TCPSEGMENTSIZE can have a
+large impact on performance.
+</para>
+
+<para>
+Also note that some people have found that setting DefaultRcvWindow in
+the [MSTCP] section of the SYSTEM.INI file under WfWg to 3072 gives a
+big improvement. I don't know why.
+</para>
+
+<para>
+My own experience wth DefaultRcvWindow is that I get much better
+performance with a large value (16384 or larger). Other people have
+reported that anything over 3072 slows things down enourmously. One
+person even reported a speed drop of a factor of 30 when he went from
+3072 to 8192. I don't know why.
+</para>
+
+<para>
+It probably depends a lot on your hardware, and the type of unix box
+you have at the other end of the link.
+</para>
+
+<para>
+Paul Cochrane has done some testing on client side tuning and come 
+to the following conclusions:
+</para>
+
+<para>
+Install the W2setup.exe file from www.microsoft.com. This is an 
+update for the winsock stack and utilities which improve performance.
+</para>
+
+<para>
+Configure the win95 TCPIP registry settings to give better 
+perfomance. I use a program called MTUSPEED.exe which I got off the 
+net. There are various other utilities of this type freely available. 
+The setting which give the best performance for me are:
+</para>
+
+<orderedlist>
+<listitem><para>
+MaxMTU                  Remove
+</para></listitem>
+<listitem><para>
+RWIN                    Remove
+</para></listitem>
+<listitem><para>
+MTUAutoDiscover         Disable
+</para></listitem>
+<listitem><para>
+MTUBlackHoleDetect      Disable
+</para></listitem>
+<listitem><para>
+Time To Live            Enabled
+</para></listitem>
+<listitem><para>
+Time To Live - HOPS     32
+</para></listitem>
+<listitem><para>
+NDI Cache Size          0
+</para></listitem>
+</orderedlist>
+
+<para>
+I tried virtually all of the items mentioned in the document and 
+the only one which made a difference to me was the socket options. It 
+turned out I was better off without any!!!!!
+</para>
+
+<para>
+In terms of overall speed of transfer, between various win95 clients 
+and a DX2-66 20MB server with a crappy NE2000 compatible and old IDE 
+drive (Kernel 2.0.30). The transfer rate was reasonable for 10 baseT.
+</para>
+
+<para>
+FIXME
+The figures are:          Put              Get 
+P166 client 3Com card:    420-440kB/s      500-520kB/s
+P100 client 3Com card:    390-410kB/s      490-510kB/s
+DX4-75 client NE2000:     370-380kB/s      330-350kB/s
+</para>
+
+<para>
+I based these test on transfer two files a 4.5MB text file and a 15MB 
+textfile. The results arn't bad considering the hardware Samba is 
+running on. It's a crap machine!!!!
+</para>
+
+<para>
+The updates mentioned in 1 and 2 brought up the transfer rates from 
+just over 100kB/s in some clients.
+</para>
+
+<para>
+A new client is a P333 connected via a 100MB/s card and hub. The 
+transfer rates from this were good: 450-500kB/s on put and 600+kB/s 
+on get.
+</para>
+
+<para>
+Looking at standard FTP throughput, Samba is a bit slower (100kB/s 
+upwards). I suppose there is more going on in the samba protocol, but 
+if it could get up to the rate of FTP the perfomance would be quite 
+staggering.
+</para>
+
+</sect1>
+
+<sect1>
+<title>My Results</title>
+
+<para>
+Some people want to see real numbers in a document like this, so here
+they are. I have a 486sx33 client running WfWg 3.11 with the 3.11b
+tcp/ip stack. It has a slow IDE drive and 20Mb of ram. It has a SMC
+Elite-16 ISA bus ethernet card. The only WfWg tuning I've done is to
+set DefaultRcvWindow in the [MSTCP] section of system.ini to 16384. My
+server is a 486dx3-66 running Linux. It also has 20Mb of ram and a SMC
+Elite-16 card. You can see my server config in the examples/tridge/
+subdirectory of the distribution.
+</para>
+
+<para>
+I get 490k/s on reading a 8Mb file with copy.
+I get 441k/s writing the same file to the samba server.
+</para>
+
+<para>
+Of course, there's a lot more to benchmarks than 2 raw throughput
+figures, but it gives you a ballpark figure.
+</para>
+
+<para>
+I've also tested Win95 and WinNT, and found WinNT gave me the best
+speed as a samba client. The fastest client of all (for me) is
+smbclient running on another linux box. Maybe I'll add those results
+here someday ...
+</para>
+
+</sect1>
+</chapter>
diff --git a/docs/docbook/projdoc/security_level.sgml b/docs/docbook/projdoc/security_level.sgml
new file mode 100644
index 0000000000..46a2ad7fe4
--- /dev/null
+++ b/docs/docbook/projdoc/security_level.sgml
@@ -0,0 +1,140 @@
+<chapter id="security_levels">
+<chapterinfo>
+	<author>
+		<firstname>Andrew</firstname><surname>Tridgell</surname>
+		<affiliation>
+			<orgname>Samba Team</orgname>
+			<address><email>samba@samba.org</email></address>
+		</affiliation>
+	</author>
+</chapterinfo>
+
+<title>Security levels</title>
+
+<sect1>
+<title>Introduction</title>
+
+<para>
+Samba supports the following options to the global smb.conf parameter
+</para>
+
+<para><programlisting>
+[global]
+<ulink url="smb.conf.5.html#SECURITY"><parameter>security</parameter></ulink> = [share|user(default)|domain|ads]
+</programlisting></para>
+
+<para>
+Please refer to the smb.conf man page for usage information and to the document
+<ulink url="DOMAIN_MEMBER.html">DOMAIN_MEMBER.html</ulink> for further background details
+on domain mode security.  The Windows 2000 Kerberos domain security model
+(security = ads) is described in the <ulink url="ADS-HOWTO.html">ADS-HOWTO.html</ulink>.
+</para>
+
+<para>
+Of the above, "security = server" means that Samba reports to clients that
+it is running in "user mode" but actually passes off all authentication
+requests to another "user mode" server. This requires an additional
+parameter "password server =" that points to the real authentication server.
+That real authentication server can be another Samba server or can be a
+Windows NT server, the later natively capable of encrypted password support.
+</para>
+
+</sect1>
+
+<sect1>
+<title>More complete description of security levels</title>
+
+<para>
+A SMB server tells the client at startup what "security level" it is
+running. There are two options "share level" and "user level". Which
+of these two the client receives affects the way the client then tries
+to authenticate itself. It does not directly affect (to any great
+extent) the way the Samba server does security. I know this is
+strange, but it fits in with the client/server approach of SMB. In SMB
+everything is initiated and controlled by the client, and the server
+can only tell the client what is available and whether an action is
+allowed. 
+</para>
+
+<para>
+I'll describe user level security first, as its simpler. In user level
+security the client will send a "session setup" command directly after
+the protocol negotiation. This contains a username and password. The
+server can either accept or reject that username/password
+combination. Note that at this stage the server has no idea what
+share the client will eventually try to connect to, so it can't base
+the "accept/reject" on anything other than:
+</para>
+
+<orderedlist>
+<listitem><para>the username/password</para></listitem>
+<listitem><para>the machine that the client is coming from</para></listitem>
+</orderedlist>
+
+<para>
+If the server accepts the username/password then the client expects to
+be able to mount any share (using a "tree connection") without
+specifying a password. It expects that all access rights will be as
+the username/password specified in the "session setup". 
+</para>
+
+<para>
+It is also possible for a client to send multiple "session setup"
+requests. When the server responds it gives the client a "uid" to use
+as an authentication tag for that username/password. The client can
+maintain multiple authentication contexts in this way (WinDD is an
+example of an application that does this)
+</para>
+
+<para>
+Ok, now for share level security. In share level security the client
+authenticates itself separately for each share. It will send a
+password along with each "tree connection" (share mount). It does not
+explicitly send a username with this operation. The client is
+expecting a password to be associated with each share, independent of
+the user. This means that samba has to work out what username the
+client probably wants to use. It is never explicitly sent the
+username. Some commercial SMB servers such as NT actually associate
+passwords directly with shares in share level security, but samba
+always uses the unix authentication scheme where it is a
+username/password that is authenticated, not a "share/password".
+</para>
+
+<para>
+Many clients send a "session setup" even if the server is in share
+level security. They normally send a valid username but no
+password. Samba records this username in a list of "possible
+usernames". When the client then does a "tree connection" it also adds
+to this list the name of the share they try to connect to (useful for
+home directories) and any users listed in the "user =" smb.conf
+line. The password is then checked in turn against these "possible
+usernames". If a match is found then the client is authenticated as
+that user.
+</para>
+
+<para>
+Finally "server level" security. In server level security the samba
+server reports to the client that it is in user level security. The
+client then does a "session setup" as described earlier. The samba
+server takes the username/password that the client sends and attempts
+to login to the "password server" by sending exactly the same
+username/password that it got from the client. If that server is in
+user level security and accepts the password then samba accepts the
+clients connection. This allows the samba server to use another SMB
+server as the "password server". 
+</para>
+
+<para>
+You should also note that at the very start of all this, where the
+server tells the client what security level it is in, it also tells
+the client if it supports encryption. If it does then it supplies the
+client with a random "cryptkey". The client will then send all
+passwords in encrypted form. You have to compile samba with encryption
+enabled to support this feature, and you have to maintain a separate
+smbpasswd file with SMB style encrypted passwords. It is
+cryptographically impossible to translate from unix style encryption
+to SMB style encryption, although there are some fairly simple management
+schemes by which the two could be kept in sync.
+</para>
+</sect1>
+</chapter>