I'm still working on this. More to come.

(This used to be commit cb2172541849c96c9156233da9b34e5e08801ae3)

1 files changed, 87 insertions, 99 deletions

diff --git a/docs/docbook/projdoc/securing-samba.xml b/docs/docbook/projdoc/securing-samba.xml
index d59b0f381e..52e07f2206 100644
--- a/docs/docbook/projdoc/securing-samba.xml
+++ b/docs/docbook/projdoc/securing-samba.xml
@@ -12,18 +12,20 @@
 <title>Introduction</title>
 <para>
 This note was attached to the Samba 2.2.8 release notes as it contained an
-important security fix.  The information contained here applies to Samba
+important security fix. The information contained here applies to Samba
 installations in general.
 </para>
 
+<blockquote>
 <para>
-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!"
+A new apprentice reported for duty to the chief engineer of a boiler house. He said, <quote>Here I am,
+if you will show me the boiler I'll start working on it.</quote> Then engineer replied, <quote>You're leaning
+on it!</quote>
 </para>
+</blockquote>
 
 <para>
-Security concerns are just like that: You need to know a little about the subject to appreciate
+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>
@@ -34,9 +36,9 @@ of knowledge with which we may unlock the secrets of the masters.
 <title>Features and Benefits</title>
 
 <para>
-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.
+There are three levels at which security principals must be observed in order to render a site
+at least moderately secure. They are the perimeter firewall, the configuration of the host
+server that is running Samba and Samba itself.
 </para>
 
 <para>
@@ -46,18 +48,17 @@ the latest protocols to permit more secure MS Windows file and print operations.
 
 <para>
 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 <smbconfsection>[IPC$]</smbconfsection>
+done using <emphasis>host-based protection</emphasis> (using samba's implementation of a technology
+known as <quote>tcpwrappers,</quote> or it may be done be using <emphasis>interface-based exclusion</emphasis>
+so &smbd; will bind only to specifically permitted interfaces. It is also
+possible to set specific share or resource-based exclusions, for example on the <smbconfsection>[IPC$]</smbconfsection>
 auto-share. The <smbconfsection>[IPC$]</smbconfsection> share is used for browsing purposes as well as to establish
 TCP/IP connections.
 </para>
 
 <para>
-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.
+Another method by which Samba may be secured is by setting Access Control Entries (ACEs) in an Access 
+Control List (ACL) on the shares themselves. This is discussed in <link linkend="AccessControls"/>.
 </para>
 
 </sect1>
@@ -74,11 +75,11 @@ before someone will find yet another vulnerability.
 </para>
 
 	<sect2>
-	<title>Using host based protection</title>
+	<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
+	In many installations of Samba, the greatest threat comes from 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.
@@ -87,8 +88,7 @@ before someone will find yet another vulnerability.
 	<para>
 	One of the simplest fixes in this case is to use the <smbconfoption><name>hosts allow</name></smbconfoption> and
 	<smbconfoption><name>hosts deny</name></smbconfoption> 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:
+	allow access to your server from a specific range of hosts. An example might be:
 	</para>
 
 	<para><smbconfblock>
@@ -97,20 +97,19 @@ before someone will find yet another vulnerability.
 	</smbconfblock></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.
+	The above will only allow SMB connections from <constant>localhost</constant> (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 <errorname>not listening on called name</errorname> error.
 	</para>
 
 	</sect2>
 
 	<sect2>
-	<title>User based protection</title>
+	<title>User-Based Protection</title>
 
 	<para>
-	If you want to restrict access to your server to valid users only then the following
+	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; <smbconfsection>[global]</smbconfsection> section put:
 	</para>
 
@@ -119,7 +118,7 @@ before someone will find yet another vulnerability.
 	</smbconfblock></para>
 
 	<para>
-	What this does is, it restricts all server access to either the user <emphasis>jacko</emphasis>
+	This restricts all server access to either the user <emphasis>jacko</emphasis>
 	or to members of the system group <emphasis>smbusers</emphasis>.
 	</para>
 
@@ -127,17 +126,17 @@ before someone will find yet another vulnerability.
 
 	<sect2>
 
-	<title>Using interface protection</title>
+	<title>Using Interface Protection</title>
 
 	<para>
-	By default Samba will accept connections on any network interface that
+	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:
+	You can change this behavior using options like this:
 	</para>
 
 	<para><smbconfblock>
@@ -147,35 +146,35 @@ before someone will find yet another vulnerability.
 
 	<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
+	name starting with <constant>eth</constant> such as <constant>eth0, eth1</constant> plus on the loopback
+	interface called <constant>lo</constant>. 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
+	If you use the above and someone tries to make an SMB connection to
+	your host over a PPP interface called <constant>ppp0,</constant> 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.
+	interface to any Samba process.
 	</para>
 
 	</sect2>
 
 	<sect2>
-	<title>Using a firewall</title>
+	<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
+	Many people use a firewall to deny access to services they do not
+	want exposed outside their network. This can be a good idea,
+	although I recommend using it in conjunction with the above
+	methods so 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
+	If you are setting up a firewall, you need to know what TCP and
 	UDP ports to allow and block. Samba uses the following:
 	</para>
 
@@ -195,7 +194,7 @@ before someone will find yet another vulnerability.
 	</sect2>
 
 	<sect2>
-	<title>Using a IPC$ share deny</title>
+	<title>Using IPC$ Share-Based Denials </title>
 
 	<para>
 	If the above methods are not suitable, then you could also place a
@@ -206,34 +205,29 @@ before someone will find yet another vulnerability.
 	</para>
 
 	<para>
-	To do that you could use:
+	To do this you could use:
 	</para>
 
 	<para><smbconfblock>
-<smbconfsection>[ipc$]</smbconfsection>
+<smbconfsection>[IPC$]</smbconfsection>
 <smbconfoption><name>hosts allow</name><value>192.168.115.0/24 127.0.0.1</value></smbconfoption>
 <smbconfoption><name>hosts deny</name><value>0.0.0.0/0</value></smbconfoption>
 	</smbconfblock></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 instructs Samba that IPC$ connections are not allowed from
+	anywhere except from the two listed network addresses (localhost and the 192.168.115
+	subnet). Connections to other shares are still 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.
+	know a valid 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.
+	If you use this method, then clients will be given an <errorname>`access denied'</errorname>
+	reply when they try to access the IPC$ share. Those clients will not be able to
+	browse shares, and may also be unable to access some other resources.  This is not
+	recommended unless you cannot use one of the other methods listed above for some reason.
 	</para>
 
 	</sect2>
@@ -242,7 +236,7 @@ before someone will find yet another vulnerability.
 	<title>NTLMv2 Security</title>
 
 	<para>
-	To configure NTLMv2 authentication the following registry keys are worth knowing about:
+	To configure NTLMv2 authentication, the following registry keys are worth knowing about:
 	</para>
 
 	<para>
@@ -253,9 +247,9 @@ before someone will find yet another vulnerability.
 	</para>
 
 	<para>
-		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.
+	The value 0x00000003 means 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.
 	</para>
 
 	<para>
@@ -266,9 +260,9 @@ before someone will find yet another vulnerability.
 	</para>
 
 	<para>
-		0x80000 - NTLMv2 session security. If either NtlmMinClientSec or
-		NtlmMinServerSec is set to 0x80000, the connection will fail if NTLMv2
-		session security is not negotiated.
+	The value 0x00080000 means permit only NTLMv2 session security. If either NtlmMinClientSec or
+	NtlmMinServerSec is set to 0x00080000, the connection will fail if NTLMv2
+	session security is not negotiated.
 	</para>
 	</sect2>
 </sect1>
@@ -278,7 +272,7 @@ before someone will find yet another vulnerability.
 
 <para>
 Please check regularly on <ulink noescape="1" url="http://www.samba.org/">http://www.samba.org/</ulink> for updates and
-important announcements.  Occasionally security releases are made and 
+important announcements. Occasionally security releases are made and 
 it is highly recommended to upgrade Samba when a security vulnerability
 is discovered. Check with your OS vendor for OS specific upgrades.
 </para>
@@ -289,81 +283,75 @@ is discovered. Check with your OS vendor for OS specific upgrades.
 <title>Common Errors</title>
 
 <para>
-If all of samba and host platform configuration were really as intuitive as one might like then this
+If all of Samba and host platform configuration were really as intuitive as one might like them to be, 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
+because of the complexity of the problem, but for the 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>
 
 	<sect2>
-	<title>Smbclient works on localhost, but the network is dead</title>
+	<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.
+	This is a common problem. Red Hat Linux (and others) installs a default firewall.
+	With the default firewall in place, only traffic on the loopback adapter (IP address 127.0.0.1)
+	is allowed through the firewall.
 	</para>
 
 	<para>
-	The solution is either to remove the firewall (stop it) or to modify the firewall script to
+	The solution is either to remove the firewall (stop it) or 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>
+	<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.
+	to enter their own password. I have not found any method to configure
+	Samba so that  users may map only 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!
+	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.
+	This is not a security flaw, it is by design. Samba allows users to have
+	exactly the same access to the UNIX file system as when 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.
+	If your UNIX home directories are set up so that one user can happily <command>cd</command>
+	into another users directory and execute <command>ls</command>, the UNIX security solution is to change file
+	permissions on the user's home directories such that the <command>cd</command> and <command>ls</command> are 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.
+	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
-	<smbconfoption><name>only user</name><value>yes</value></smbconfoption> option on the share, is that you have not set the
-	valid users list for the share.
+	Samba allows the behavior you require. Simply put the <smbconfoption><name>only user</name><value>%S</value></smbconfoption>
+	option in the <smbconfsection>[homes]</smbconfsection> share definition.
 	</para>
 
 	<para>
-	Note that only user works in conjunction with the users= list,
+	The <smbconfoption><name>only user</name><value></value></smbconfoption> works in conjunction with the <smbconfoption><name>users</name><value>list</value></smbconfoption>,
 	so to get the behavior you require, add the line :
 	<smbconfblock>
 <smbconfoption><name>users</name><value>%S</value></smbconfoption>
 </smbconfblock>
-	this is equivalent to:
+	this is equivalent to adding
 	<smbconfblock>
 <smbconfoption><name>valid users</name><value>%S</value></smbconfoption>
 	</smbconfblock>