Move existing samba4 documentation to Samba-docs trunk

(This used to be commit ee3dfdcf09d6a657cf7e7325f10aa3154867c351)

18 files changed, 474 insertions, 0 deletions

diff --git a/docs/Samba4-HOWTO/ad-dc.xml b/docs/Samba4-HOWTO/ad-dc.xml
new file mode 100644
index 0000000000..cdfc358edc
--- /dev/null
+++ b/docs/Samba4-HOWTO/ad-dc.xml
@@ -0,0 +1,4 @@
+<chapter id="ad-dc">
+	<title>Active Directory - Domain Controller</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/ad-member.xml b/docs/Samba4-HOWTO/ad-member.xml
new file mode 100644
index 0000000000..b46d99be74
--- /dev/null
+++ b/docs/Samba4-HOWTO/ad-member.xml
@@ -0,0 +1,4 @@
+<chapter id="ad-member">
+	<title>Active Directory - Member</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/auth.xml b/docs/Samba4-HOWTO/auth.xml
new file mode 100644
index 0000000000..58b25f4035
--- /dev/null
+++ b/docs/Samba4-HOWTO/auth.xml
@@ -0,0 +1,4 @@
+<chapter id="authentication">
+	<title>Authentication</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/cifsfs.xml b/docs/Samba4-HOWTO/cifsfs.xml
new file mode 100644
index 0000000000..190c3840d6
--- /dev/null
+++ b/docs/Samba4-HOWTO/cifsfs.xml
@@ -0,0 +1,4 @@
+<chapter id="cifsfs">
+	<title>CIFSFS</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/compiling.xml b/docs/Samba4-HOWTO/compiling.xml
new file mode 100644
index 0000000000..048a0f4b8e
--- /dev/null
+++ b/docs/Samba4-HOWTO/compiling.xml
@@ -0,0 +1,24 @@
+<chapter id="compiling">
+	<title>Compiling</title>
+
+	<sect1>
+		<title>Downloading the source - Tar Ball</title>
+
+	</sect1>
+
+	<sect1>
+		<title>Downloading the source - Subversion</title>
+
+	</sect1>
+
+	<sect1>
+		<title>Compiling the source</title>
+
+	</sect1>
+
+	<sect1>
+		<title>Installing</title>
+
+	</sect1>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/config.xml b/docs/Samba4-HOWTO/config.xml
new file mode 100644
index 0000000000..e251c698ab
--- /dev/null
+++ b/docs/Samba4-HOWTO/config.xml
@@ -0,0 +1,5 @@
+<chapter id="config">
+	<title>Configuration</title>
+
+	<para>Chapter describing Samba's configuration in detail.</para>
+</chapter>
diff --git a/docs/Samba4-HOWTO/domain-bdc.xml b/docs/Samba4-HOWTO/domain-bdc.xml
new file mode 100644
index 0000000000..61c420fe7b
--- /dev/null
+++ b/docs/Samba4-HOWTO/domain-bdc.xml
@@ -0,0 +1,4 @@
+<chapter id="bdc">
+	<title>Backup Domain Controller</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/domain-member.xml b/docs/Samba4-HOWTO/domain-member.xml
new file mode 100644
index 0000000000..8be3758792
--- /dev/null
+++ b/docs/Samba4-HOWTO/domain-member.xml
@@ -0,0 +1,2 @@
+<chapter id="domain-member">
+</chapter>
diff --git a/docs/Samba4-HOWTO/domain-pdc.xml b/docs/Samba4-HOWTO/domain-pdc.xml
new file mode 100644
index 0000000000..b3fb6e6f7b
--- /dev/null
+++ b/docs/Samba4-HOWTO/domain-pdc.xml
@@ -0,0 +1 @@
+<chapter id="domain-pdc"/>
diff --git a/docs/Samba4-HOWTO/history.xml b/docs/Samba4-HOWTO/history.xml
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/docs/Samba4-HOWTO/history.xml
diff --git a/docs/Samba4-HOWTO/index.xml b/docs/Samba4-HOWTO/index.xml
new file mode 100644
index 0000000000..6562a7ed34
--- /dev/null
+++ b/docs/Samba4-HOWTO/index.xml
@@ -0,0 +1,137 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+
+<book id="Samba-HOWTO"
+	xmlns:xi="http://www.w3.org/2003/XInclude">
+<title>The Official Samba-4 HOWTO</title>
+
+<bookinfo>
+	<authorgroup>
+	<editor>&person.jelmer;</editor>
+	</authorgroup>
+	<pubdate><?latex \today ?></pubdate>
+
+</bookinfo>
+
+<?latex \setcounter{page}{5} ?>
+
+<preface>
+	<title>Attribution</title>
+	<para>
+		<xi:include href="../Samba4-HOWTO-attributions.xml"/>
+	</para>
+</preface>
+
+<?latex \cleardoublepage ?>
+
+<!-- Contents -->
+<toc/>
+<?latex \cleardoublepage ?>
+
+<part>
+	<title>Introduction to SMB networks</title>
+
+	<para>Not everybody is already familiar with SMB networks and the jargon 
+		used in such networks. This part describes the evolution of SMB, 
+		how the protocol is structured and what Samba can be used for. </para>
+
+	<para>NT admins, already familiar with SMB networks, are probably only 
+		interested in the chapter about Samba itself.</para>
+
+	<xi:include href="protocol.xml"/>
+	<xi:include href="samba.xml"/>
+
+</part>
+
+<part>
+	<title>Samba 4 Basics</title>
+
+	<para>FIXME</para>
+
+	<xi:include href="config.xml"/>
+	<xi:include href="ldb.xml"/>
+</part>
+
+<part>
+	<title>Network model</title>
+
+	<para>
+		A SMB server is used in a certain network type 
+		(workgroup, domain, active directory) with a specific 
+		role (stand-alone, primary domain controller, backup domain controller, etc) in that network. Samba has to be configured according to that role. 
+		Each of the chapters in this part describes how to configure Samba 
+		for a specific role.
+	</para>
+
+</part>
+
+<part>
+	<title>Network Model: Share-based security</title>
+		
+	<xi:include href="security=share.xml"/>
+</part>
+
+<part>
+	<title>Network Model: User-based security</title>
+	<xi:include href="security=user.xml"/>
+</part>
+
+<part id="domain">
+	<title>Network Model: NT4-style domains</title>
+
+	<xi:include href="domain-pdc.xml"/>
+	<xi:include href="domain-bdc.xml"/>
+	<xi:include href="domain-member.xml"/>
+</part>
+
+<part id="ad">
+	<title>Network Model - Active Directory</title>
+
+	<xi:include href="ad-dc.xml"/>
+	<xi:include href="ad-member.xml"/>
+</part>
+
+<part>
+	<title>Common services</title>
+
+	<para>
+		Independent of the role the server has, it can provide services. 
+		Examples of services are printing, user management, authentication, etc.
+	</para>
+
+	<xi:include href="shares.xml"/>
+	<xi:include href="printing.xml"/>
+	<xi:include href="auth.xml"/>
+	<xi:include href="registry.xml"/>
+</part>
+
+<part>
+	<title>Clients</title>
+
+	<para>Samba includes a number of different clients for accessing 
+	SMB file, print and other services. Pretty much every service can 
+	be access using a command-line utility, though there are several 
+	GUI clients available as well.</para>
+
+	<xi:include href="smbclient.xml"/>
+	<xi:include href="cifsfs.xml"/>
+	<xi:include href="gui-clients.xml"/>
+</part>
+
+<part>
+	<title>Appendices</title>
+
+	<xi:include href="compiling.xml"/>
+
+</part>
+
+<lot/>
+
+<?latex \include{gpl}?>
+
+<!--<xi:include href="../Samba-HOWTO-Collection/glossary.xml"/>-->
+
+<?latex \chaptermark{Subject index} ?>
+<index/>
+
+</book>
diff --git a/docs/Samba4-HOWTO/printing.xml b/docs/Samba4-HOWTO/printing.xml
new file mode 100644
index 0000000000..5ffb2b7680
--- /dev/null
+++ b/docs/Samba4-HOWTO/printing.xml
@@ -0,0 +1,11 @@
+<chapter id="printing">
+	<title>Printing</title>
+
+	<!--FIXME: Some Windows printing background information -->
+
+	<sect1 id="unix">
+		<title>Unix printing types</title>
+
+	</sect1>
+	
+</chapter>
diff --git a/docs/Samba4-HOWTO/protocol.xml b/docs/Samba4-HOWTO/protocol.xml
new file mode 100644
index 0000000000..f2961116e0
--- /dev/null
+++ b/docs/Samba4-HOWTO/protocol.xml
@@ -0,0 +1,204 @@
+<chapter id="protocol">
+	<title>The SMB/CIFS protocol</title>
+
+	<!-- 
+	Some parts shamelessly borrowed from myself. 
+	Original on http://jelmer.vernstok.nl/publications/cifs-developments.pdf
+	-->
+
+	<para>
+		"SMB" (also known as "CIFS") is a 
+		file-sharing protocol that has been used since the mid-eighties. 
+		Most people know SMB as the protocol behind the "Network Neighbourhood" 
+		and remote printing in Windows.
+	</para>
+
+	<para>
+		Several parts of the protocol are not discussed in this chapter, such 
+		as mailslots, browsing and dfs, to prevent it from getting too complex. 
+		CIFS internals are documented in detail in <citation>Hertel, 2003</citation>.
+	</para>
+
+
+	<sect1>
+		<title>History</title>
+
+		<sect2>
+			<title>Invention by IBM</title>
+
+			<para>
+				SMB is not very old, but it has a long history of modifications and extensions.
+				The original protocol was meant to run over ``NetBIOS'', which was the 
+				name of the DOS interface to a very simple LAN system developed by IBM.
+				NetBIOS was developed because SNA, IBM's other main 
+				protocol at the time, was much too advanced for use in DOS.
+			</para>
+
+			<para>
+				The NetBIOS API in these days (early eighties) was nothing more then the 
+				interface to a very simple link-layer protocol 
+				over which several protocols, including SMB, were used. It could do reads and 
+				writes to services on remote hosts, which were identified by case-insensitive 
+				names, and discover all available hosts and services.
+			</para>
+
+			<para>
+				Dr. Barry Feigenbau, an IBM employee, invented the core of the original SMB protocol, 
+				which he initially named after himself: ``BAF''. He later changed the name to 
+				be ``SMB'' (for ``Server Message Block''). Every packet in the protocol 
+				starts with a byte $0xFF$ and these three letters. 
+			</para>
+
+			<para>
+				IBM, Microsoft, 3Com and Intel made up the rest of the initial protocol 
+				together. The commands the protocol supported at this stage were basically
+				a mirror of the DOS File IO API calls, which meant the protocol wasn't very 
+				efficient. The protocol also lacked authentication support. Everybody on the 
+				network could do reads and writes, which meant this protocol 
+				wasn't very suitable for large enterprises.
+			</para>
+
+			<para>
+				NetBIOS is an API that has had various implementations; there is 
+				NetBIOS over TCP/IP (NBT), NetBIOS over IPX, NetBIOS over SNA and 
+				even NetBIOS over DECNEt. Mostly used these days is
+				NetBIOS over TCP (NBT). 
+			</para>
+
+			<para>
+				This is also were things are starting to get hairy. Since NetBIOS identifies 
+				hosts by their name, NetBIOS clients had to start doing IP broadcasts to 
+				figure out the IP of the host they had to connect to. Several schemes were 
+				introduced to do name lookups crossing subnet boundaries, using name servers, 
+				etc. We're basically emulating a NetBIOS LAN in order to be able to run SMB.
+			</para>
+
+			<para>
+				Doing NetBIOS over IP is not very sane, however, the NBT implementation itself 
+				in Windows isn't very nice either. It has horrible 
+				limits, special exceptions, several broken schemes for looking up 
+				names (including two kinds of name servers). NetBIOS and NetBIOS over TCP/IP 
+				are described in RFC1001 and RFC1002.
+			</para>	
+		</sect2>
+
+		<sect2>
+			<title>The various incarnations of SMB</title>
+
+			<para>Over the years, several usage models for SMB have been developed. While SMB originally started out as a file sharing protocol, it was later extended to include support for network management and other network services 
+				as well.</para>
+
+			<para>
+				One of the reasons for the various "upgrades" of the SMB 
+				protocol is the fact that networks have become larger 
+				and larger and with them the need for privilege separation 
+				and scalability has increased.
+			</para>
+
+			<sect3>
+				<title>DOS</title>
+
+				<para>
+					The original model in which SMB was used was as a 
+					simple file-sharing service in a NetBIOS-environment.
+				</para>
+				
+				<para>
+					File sharing worked basically by specifying a list of directories that had 
+					to be shared and what name they had to be shared under ("shares"). Eventually, 
+					one could password-protect a share. At most one password per share could be set.
+				</para>
+			</sect3>
+
+			<sect3>
+				<title>Windows For Workgroups</title>
+				
+				<para>
+					After the ``CORE'' dialect, 
+					IBM and Microsoft implemented a new dialect known as ``LANMAN''.
+					This dialect was used by Windows for 
+					Workgroups, OS/2 and Windows 9x which all know it under a different name. A 
+					'virtual' file system was also added, which was used for doing remote function 
+					calls (RAP, for ``Remote Administration Protocol'').
+				</para>
+
+				<para>
+					Computers are grouped into "Workgroups" in this model. Everybody is equal to 
+					the others and there is no central point of control.
+				</para>
+			</sect3>
+
+			<sect3>
+				<title>Windows NT</title>
+				<para>
+					For Windows NT, yet another dialect was added, named 'NT'. The NT dialect 
+					had it's own set of file I/O functions (similar to the NT File I/O API) 
+					and it had support for yet another way of doing remote function calls:
+					DCE/RPC. RPC's are used for DCOM and several of the subsystems in NT
+					that can be accessed remotely (registry, printing, user management, logging 
+					on, etc).
+				</para>
+
+				<para>
+					Windows NT works with a new concept for grouping computers called ``domains''<footnote>In the protocol, domains are actually an upgraded version of a workgroup</footnote>. Each computer is member of exactly one domain. There are several roles a computer can have in the domain: PDC (primary domain controller, the "manager" of the domain, that coordinates all authentication and authorization), BDC (Backup domain controller, in case the PDC goes down) or just a regular domain member. The PDC decides who is to be a member of the domain.
+				</para>
+			</sect3>
+
+			<sect3>
+				<title>Windows 2000</title>
+				<para>
+					In Windows NT 5 (marketing name: Windows 2000), NetBIOS-less SMB was
+					introduced. This means SMB is used directly over TCP port 445 instead of 
+					via NetBIOS over TCP/IP. DNS 
+					is used for looking up machine names. 
+				</para>
+
+				<para>Windows 2000 was also the first operating system from Microsoft
+					that had support for Active Directory. Active Directory is very 
+					similar to the "domain" concept used by NT4, though it 
+					is implemented differently (using modified open protocols), 
+					and has some additional features (one of the most important ones being decentralized).
+				</para>
+
+				<para>
+					Active directory no longer uses a central point of authority 
+					and there are fewer limits to the size of a domain. Several 
+					DC's can exist, so there is no longer a single point of 
+					failure as well as better scalability. 
+				</para>
+			</sect3>
+		</sect2>
+
+		<sect2>
+			<title>Samba versions and their support for the SMB models</title>
+
+			<sect3>
+				<title>Samba 2.2</title>
+
+				<para>Full CORE and Workgroup support. Somewhat basic 
+					NT4-style support.</para>
+			</sect3>
+
+			<sect3>
+				<title>Samba 3.0</title>
+
+				<para>Full CORE and Workgroup support. Almost complete 
+					NT4-style support.
+				</para>
+			</sect3>
+
+			<sect3>
+				<title>Samba 3.2</title>
+
+				<para>FIXME</para>
+			</sect3>
+
+			<sect3>
+				<title>Samba 4.0</title>
+				
+				<para>Full CORE, Workgroup, NT4 and ADS support.</para>
+
+			</sect3>
+		</sect2>
+	</sect1>
+</chapter>
diff --git a/docs/Samba4-HOWTO/registry.xml b/docs/Samba4-HOWTO/registry.xml
new file mode 100644
index 0000000000..2ef11d3457
--- /dev/null
+++ b/docs/Samba4-HOWTO/registry.xml
@@ -0,0 +1,4 @@
+<chapter id="registry">
+	<title>Registry</title>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/samba.xml b/docs/Samba4-HOWTO/samba.xml
new file mode 100644
index 0000000000..8fed58559a
--- /dev/null
+++ b/docs/Samba4-HOWTO/samba.xml
@@ -0,0 +1,48 @@
+<chapter id="samba">
+	<title>Samba</title>
+
+	<para>
+		Samba is an Open Source application that provides 
+		an SMB implementation for POSIX-compatible 
+		operating systems. 
+	</para>
+
+	<para>
+		Providing support for a Windows-based file-sharing protocol
+		on POSIX servers sometimes requires mapping Windows semantics to 
+		POSIX semantics.
+	</para>
+
+	<para>
+		Samba has always been catching up with Microsoft. Here is a list 
+		of Samba releases and what they support (or will support).
+	</para>
+
+	<sect1>
+	<title>Samba 2.2</title>
+
+	<para>Full CORE and Workgroup support. Somewhat basic 
+		NT4-style support.</para>
+	</sect1>
+
+	<sect1>
+		<title>Samba 3.0</title>
+
+		<para>Full CORE and Workgroup support. Almost complete 
+			NT4-style support.
+		</para>
+	</sect1>
+
+	<sect1>
+		<title>Samba 3.2</title>
+
+		<para>FIXME</para>
+	</sect1>
+
+	<sect1>
+		<title>Samba 4.0</title>
+		
+		<para>Full CORE, Workgroup, NT4 and ADS support.</para>
+
+	</sect1>
+</chapter>
diff --git a/docs/Samba4-HOWTO/security=share.xml b/docs/Samba4-HOWTO/security=share.xml
new file mode 100644
index 0000000000..1731bc0862
--- /dev/null
+++ b/docs/Samba4-HOWTO/security=share.xml
@@ -0,0 +1,8 @@
+<chapter id="security=share">
+	<title>Share-based stand-alone server</title>
+
+<para>
+	One of the simplest 
+</para>
+
+</chapter>
diff --git a/docs/Samba4-HOWTO/security=user.xml b/docs/Samba4-HOWTO/security=user.xml
new file mode 100644
index 0000000000..1713c99c7c
--- /dev/null
+++ b/docs/Samba4-HOWTO/security=user.xml
@@ -0,0 +1,6 @@
+<chapter id="security=user">
+	<title>User-based Stand-alone server</title>
+
+	<para></para>
+	
+</chapter>
diff --git a/docs/Samba4-HOWTO/smbclient.xml b/docs/Samba4-HOWTO/smbclient.xml
new file mode 100644
index 0000000000..1f97ce6265
--- /dev/null
+++ b/docs/Samba4-HOWTO/smbclient.xml
@@ -0,0 +1,4 @@
+<chapter id="smbclient">
+	<title>smbclient</title>
+
+</chapter>