trying to get HEAD building again. If you want the code

prior to this merge, checkout HEAD_PRE_3_0_0_BETA_3_MERGE
(This used to be commit adb98e7b7cd0f025b52c570e4034eebf4047b1ad)

1 files changed, 306 insertions, 161 deletions

diff --git a/docs/docbook/projdoc/securing-samba.xml b/docs/docbook/projdoc/securing-samba.xml
index 204fceeb4a..bed4e4ee56 100644
--- a/docs/docbook/projdoc/securing-samba.xml
+++ b/docs/docbook/projdoc/securing-samba.xml
@@ -3,7 +3,7 @@
 <chapterinfo>
 	&author.tridge;
 	&author.jht;
-	<pubdate>17 March 2003</pubdate>
+	<pubdate>May 26, 2003</pubdate>
 </chapterinfo>
 
 <title>Securing Samba</title>
@@ -16,209 +16,354 @@ important security fix.  The information contained here applies to Samba
 installations in general.
 </para>
 
-</sect1>
-
-<sect1>
-<title>Using host based protection</title>
-
 <para>
-In many installations of Samba the greatest threat comes for outside
-your immediate network. By default Samba will accept connections from
-any host, which means that if you run an insecure version of Samba on
-a host that is directly connected to the Internet you can be
-especially vulnerable.
+A new apprentice reported for duty to the Chief Engineer of a boiler house. He said, "Here I am,
+if you will show me the boiler I'll start working on it." Then engineer replied, "You're leaning
+on it!"
 </para>
 
 <para>
-One of the simplest fixes in this case is to use the <command>hosts allow</command> and
-<command>hosts deny</command> options in the Samba &smb.conf; configuration file to only
-allow access to your server from a specific range of hosts. An example
-might be:
-</para>
-
-<para><programlisting>
-	hosts allow = 127.0.0.1 192.168.2.0/24 192.168.3.0/24
-	hosts deny = 0.0.0.0/0
-</programlisting></para>
-
-<para>
-The above will only allow SMB connections from 'localhost' (your own
-computer) and from the two private networks 192.168.2 and
-192.168.3. All other connections will be refused as soon
-as the client sends its first packet. The refusal will be marked as a
-'not listening on called name' error.
+Security concerns are just like that: You need to know a little about the subject to appreciate
+how obvious most of it really is. The challenge for most of us is to discover that first morsel
+of knowledge with which we may unlock the secrets of the masters.
 </para>
 
 </sect1>
 
 <sect1>
-<title>User based protection</title>
+<title>Features and Benefits</title>
 
 <para>
-If you want to restrict access to your server to valid users only then the following
-method may be of use. In the smb.conf [globals] section put:
+There are three level at which security principals must be observed in order to render a site
+at least moderately secure. These are: the perimeter firewall, the configuration of the host
+server that is running Samba, and Samba itself.
 </para>
 
-<para><programlisting>
-	valid users = @smbusers, jacko
-</programlisting></para>
-
 <para>
-What this does is, it restricts all server access to either the user <emphasis>jacko</emphasis>
-or to members of the system group <emphasis>smbusers</emphasis>.
+Samba permits a most flexible approach to network security. As far as possible Samba implements
+the latest protocols to permit more secure MS Windows file and print operations.
 </para>
 
-</sect1>
-
-<sect1>
-
-<title>Using interface protection</title>
-
 <para>
-By default Samba will accept connections on any network interface that
-it finds on your system. That means if you have a ISDN line or a PPP
-connection to the Internet then Samba will accept connections on those
-links. This may not be what you want.
+Samba may be secured from connections that originate from outside the local network. This may be
+done using <emphasis>host based protection</emphasis> (using samba's implementation of a technology
+known as "tcpwrappers", or it may be done be using <emphasis>interface based exclusion</emphasis>
+so that &smbd; will bind only to specifically permitted interfaces. It is also
+possible to set specific share or resource based exclusions, eg: on the <parameter>IPC$</parameter>
+auto-share. The <parameter>IPC$</parameter> share is used for browsing purposes as well as to establish
+TCP/IP connections.
 </para>
 
 <para>
-You can change this behaviour using options like the following:
-</para>
-
-<para><programlisting>
-	interfaces = eth* lo
-	bind interfaces only = yes
-</programlisting></para>
-
-<para>
-This tells Samba to only listen for connections on interfaces with a
-name starting with 'eth' such as eth0, eth1, plus on the loopback
-interface called 'lo'. The name you will need to use depends on what
-OS you are using, in the above I used the common name for Ethernet
-adapters on Linux.
-</para>
-
-<para>
-If you use the above and someone tries to make a SMB connection to
-your host over a PPP interface called 'ppp0' then they will get a TCP
-connection refused reply. In that case no Samba code is run at all as
-the operating system has been told not to pass connections from that
-interface to any samba process.
+Another method by which Samba may be secured is by way of setting Access Control Entries in an Access 
+Control List on the shares themselves. This is discussed in the chapter on File, Directory and Share Access
+Control.
 </para>
 
 </sect1>
 
 <sect1>
-<title>Using a firewall</title>
-
-<para>
-Many people use a firewall to deny access to services that they don't
-want exposed outside their network. This can be a very good idea,
-although I would recommend using it in conjunction with the above
-methods so that you are protected even if your firewall is not active
-for some reason.
-</para>
+<title>Technical Discussion of Protective Measures and Issues</title>
 
 <para>
-If you are setting up a firewall then you need to know what TCP and
-UDP ports to allow and block. Samba uses the following:
-</para>
-
-<para><programlisting>
-	UDP/137    - used by nmbd
-	UDP/138    - used by nmbd
-	TCP/139    - used by smbd
-	TCP/445    - used by smbd
-</programlisting></para>
-
-<para>
-The last one is important as many older firewall setups may not be
-aware of it, given that this port was only added to the protocol in
-recent years. 
+The key challenge of security is the fact that protective measures suffice at best
+only to close the door on known exploits and breach techniques. Never assume that
+because you have followed these few measures that the Samba server is now an impenetrable
+fortress! Given the history of information systems so far, it is only a matter of time
+before someone will find yet another vulnerability.
 </para>
 
+	<sect2>
+	<title>Using host based protection</title>
+
+	<para>
+	In many installations of Samba the greatest threat comes for outside
+	your immediate network. By default Samba will accept connections from
+	any host, which means that if you run an insecure version of Samba on
+	a host that is directly connected to the Internet you can be
+	especially vulnerable.
+	</para>
+
+	<para>
+	One of the simplest fixes in this case is to use the <parameter>hosts allow</parameter> and
+	<parameter>hosts deny</parameter> options in the Samba &smb.conf; configuration file to only
+	allow access to your server from a specific range of hosts. An example
+	might be:
+	</para>
+
+	<para><programlisting>
+		hosts allow = 127.0.0.1 192.168.2.0/24 192.168.3.0/24
+		hosts deny = 0.0.0.0/0
+	</programlisting></para>
+
+	<para>
+	The above will only allow SMB connections from 'localhost' (your own
+	computer) and from the two private networks 192.168.2 and
+	192.168.3. All other connections will be refused as soon
+	as the client sends its first packet. The refusal will be marked as a
+	<errorname>not listening on called name</errorname> error.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>User based protection</title>
+
+	<para>
+	If you want to restrict access to your server to valid users only then the following
+	method may be of use. In the &smb.conf; <parameter>[globals]</parameter> section put:
+	</para>
+
+	<para><programlisting>
+		valid users = @smbusers, jacko
+	</programlisting></para>
+
+	<para>
+	What this does is, it restricts all server access to either the user <emphasis>jacko</emphasis>
+	or to members of the system group <emphasis>smbusers</emphasis>.
+	</para>
+
+	</sect2>
+
+	<sect2>
+
+	<title>Using interface protection</title>
+
+	<para>
+	By default Samba will accept connections on any network interface that
+	it finds on your system. That means if you have a ISDN line or a PPP
+	connection to the Internet then Samba will accept connections on those
+	links. This may not be what you want.
+	</para>
+
+	<para>
+	You can change this behaviour using options like the following:
+	</para>
+
+	<para><programlisting>
+		interfaces = eth* lo
+		bind interfaces only = yes
+	</programlisting></para>
+
+	<para>
+	This tells Samba to only listen for connections on interfaces with a
+	name starting with 'eth' such as eth0, eth1, plus on the loopback
+	interface called 'lo'. The name you will need to use depends on what
+	OS you are using, in the above I used the common name for Ethernet
+	adapters on Linux.
+	</para>
+
+	<para>
+	If you use the above and someone tries to make a SMB connection to
+	your host over a PPP interface called 'ppp0' then they will get a TCP
+	connection refused reply. In that case no Samba code is run at all as
+	the operating system has been told not to pass connections from that
+	interface to any samba process.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Using a firewall</title>
+
+	<para>
+	Many people use a firewall to deny access to services that they don't
+	want exposed outside their network. This can be a very good idea,
+	although I would recommend using it in conjunction with the above
+	methods so that you are protected even if your firewall is not active
+	for some reason.
+	</para>
+
+	<para>
+	If you are setting up a firewall then you need to know what TCP and
+	UDP ports to allow and block. Samba uses the following:
+	</para>
+
+	<simplelist>
+		<member>UDP/137 - used by nmbd</member>
+		<member>UDP/138 - used by nmbd</member>
+		<member>TCP/139 - used by smbd</member>
+		<member>TCP/445 - used by smbd</member>
+	</simplelist>
+
+	<para>
+	The last one is important as many older firewall setups may not be
+	aware of it, given that this port was only added to the protocol in
+	recent years. 
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Using a IPC$ share deny</title>
+
+	<para>
+	If the above methods are not suitable, then you could also place a
+	more specific deny on the IPC$ share that is used in the recently
+	discovered security hole. This allows you to offer access to other
+	shares while denying access to IPC$ from potentially untrustworthy
+	hosts.
+	</para>
+
+	<para>
+	To do that you could use:
+	</para>
+
+	<para><programlisting>
+[ipc$]
+	hosts allow = 192.168.115.0/24 127.0.0.1
+	hosts deny = 0.0.0.0/0
+	</programlisting></para>
+
+	<para>
+	this would tell Samba that IPC$ connections are not allowed from
+	anywhere but the two listed places (localhost and a local
+	subnet). Connections to other shares would still be allowed. As the
+	IPC$ share is the only share that is always accessible anonymously
+	this provides some level of protection against attackers that do not
+	know a username/password for your host.
+	</para>
+
+	<para>
+	If you use this method then clients will be given a <errorname>access denied</errorname>
+	reply when they try to access the IPC$ share. That means that those
+	clients will not be able to browse shares, and may also be unable to
+	access some other resources. 
+	</para>
+
+	<para>
+	This is not recommended unless you cannot use one of the other
+	methods listed above for some reason.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>NTLMv2 Security</title>
+
+	<para>
+	To configure NTLMv2 authentication the following registry keys are worth knowing about:
+	</para>
+
+	<!-- FIXME -->
+	<para>
+	<screen>
+		[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa]
+		"lmcompatibilitylevel"=dword:00000003
+
+		0x3 - Send NTLMv2 response only. Clients will use NTLMv2 authentication,
+		use NTLMv2 session security if the server supports it. Domain
+		controllers accept LM, NTLM and NTLMv2 authentication.
+
+		[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0]
+		"NtlmMinClientSec"=dword:00080000
+
+		0x80000 - NTLMv2 session security. If either NtlmMinClientSec or
+		NtlmMinServerSec is set to 0x80000, the connection will fail if NTLMv2
+		session security is not negotiated.
+	</screen>
+	</para>
+	</sect2>
 </sect1>
 
 <sect1>
-<title>Using a IPC$ share deny</title>
-
-<para>
-If the above methods are not suitable, then you could also place a
-more specific deny on the IPC$ share that is used in the recently
-discovered security hole. This allows you to offer access to other
-shares while denying access to IPC$ from potentially untrustworthy
-hosts.
-</para>
-
-<para>
-To do that you could use:
-</para>
-
-<para><programlisting>
-	[ipc$]
-	     hosts allow = 192.168.115.0/24 127.0.0.1
-	     hosts deny = 0.0.0.0/0
-</programlisting></para>
-
-<para>
-this would tell Samba that IPC$ connections are not allowed from
-anywhere but the two listed places (localhost and a local
-subnet). Connections to other shares would still be allowed. As the
-IPC$ share is the only share that is always accessible anonymously
-this provides some level of protection against attackers that do not
-know a username/password for your host.
-</para>
-
-<para>
-If you use this method then clients will be given a 'access denied'
-reply when they try to access the IPC$ share. That means that those
-clients will not be able to browse shares, and may also be unable to
-access some other resources. 
-</para>
+<title>Upgrading Samba</title>
 
 <para>
-This is not recommended unless you cannot use one of the other
-methods listed above for some reason.
+Please check regularly on <ulink url="http://www.samba.org/">http://www.samba.org/</ulink> for updates and
+important announcements.  Occasionally security releases are made and 
+it is highly recommended to upgrade Samba when a security vulnerability
+is discovered.
 </para>
 
 </sect1>
 
 <sect1>
-<title>NTLMv2 Security</title>
-
-<para>
-To configure NTLMv2 authentication the following registry keys are worth knowing about:
-</para>
+<title>Common Errors</title>
 
 <para>
-<programlisting>
-	[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa]
-	"lmcompatibilitylevel"=dword:00000003
-
-	0x3 - Send NTLMv2 response only. Clients will use NTLMv2 authentication,
-	use NTLMv2 session security if the server supports it. Domain
-	controllers accept LM, NTLM and NTLMv2 authentication.
-
-	[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\MSV1_0]
-	"NtlmMinClientSec"=dword:00080000
-
-	0x80000 - NTLMv2 session security. If either NtlmMinClientSec or
-	NtlmMinServerSec is set to 0x80000, the connection will fail if NTLMv2
-	session security is not negotiated.
-</programlisting>
+If all of samba and host platform configuration were really as intuitive as one might like then this
+section would not be necessary. Security issues are often vexing for a support person to resolve, not
+because of the complexity of the problem, but for reason that most administrators who post what turns
+out to be a security problem request are totally convinced that the problem is with Samba.
 </para>
-</sect1>
-
-<sect1>
-<title>Upgrading Samba</title>
 
-<para>
-Please check regularly on <ulink url="http://www.samba.org/">http://www.samba.org/</ulink> for updates and
-important announcements.  Occasionally security releases are made and 
-it is highly recommended to upgrade Samba when a security vulnerability
-is discovered.
-</para>
+	<sect2>
+	<title>Smbclient works on localhost, but the network is dead</title>
+
+	<para>
+	This is a very common problem. Red Hat Linux (as do others) will install a default firewall.
+	With the default firewall in place only traffic on the loopback adapter (IP address 127.0.0.1)
+	will be allowed through the firewall.
+	</para>
+
+	<para>
+	The solution is either to remove the firewall (stop it) or to modify the firewall script to
+	allow SMB networking traffic through. See section above in this chapter.
+	</para>
+
+	</sect2>
+
+	<sect2>
+	<title>Why can users access home directories of other users?</title>
+
+	<para>
+	<quote>
+	We are unable to keep individual users from mapping to any other user's
+	home directory once they have supplied a valid password! They only need
+	to enter their own password. I have not found *any* method that I can
+	use to configure samba to enforce that only a user may map their own
+	home directory.
+	</quote>
+	</para>
+
+	<para><quote>
+	User xyzzy can map his home directory. Once mapped user xyzzy can also map
+	*anyone* else's home directory!
+	</quote></para>
+
+	<para>
+	This is not a security flaw, it is by design. Samba allows
+	users to have *exactly* the same access to the UNIX filesystem
+	as they would if they were logged onto the UNIX box, except
+	that it only allows such views onto the file system as are
+	allowed by the defined shares.
+	</para>
+
+	<para>
+	This means that if your UNIX home directories are set up
+	such that one user can happily cd into another users
+	directory and do an ls, the UNIX security solution is to
+	change the UNIX file permissions on the users home directories
+	such that the cd and ls would be denied.
+	</para>
+
+	<para>
+	Samba tries very hard not to second guess the UNIX administrators
+	security policies, and trusts the UNIX admin to set
+	the policies and permissions he or she desires.
+	</para>
+
+	<para>
+	Samba does allow the setup you require when you have set the
+	<parameter>only user = yes</parameter> option on the share, is that you have not set the
+	valid users list for the share.
+	</para>
+
+	<para>
+	Note that only user works in conjunction with the users= list,
+	so to get the behavior you require, add the line :
+	<programlisting>
+	users = %S
+	</programlisting>
+	this is equivalent to:
+	<programlisting>
+	valid users = %S
+	</programlisting>
+	to the definition of the <parameter>[homes]</parameter> share, as recommended in
+	the &smb.conf; man page.
+	</para>
+	</sect2>
 
 </sect1>
-
 </chapter>