r19387: Exit with 0 if failures were expected
[sfrench/samba-autobuild/.git] / howto.txt
index bc3978964e3e28ba94bc2fe02fa771b42b940e50..3991781268150e6b3257b77d3543d04e4cf43ad2 100644 (file)
--- a/howto.txt
+++ b/howto.txt
@@ -22,28 +22,36 @@ There are 2 methods of doing this:
 both methods will create a directory called "samba4" in the current
 directory. If you don't have rsync or svn then install one of them. 
 
+Since only released versions of Samba contain a pregenerated configure script, 
+you will have to generate it by hand:
+
+ $ cd samba4/source
+ $ ./autogen.sh
+
 Note that the above rsync command will give you a checked out svn
 repository. So if you also have svn you can update it to the latest
 version at some future date using:
 
-  cd samba4
-  svn up
-
+  $ cd samba4
+  $ svn up
 
 Step 2: compile Samba4
 ----------------------
 
+Recommended optional development libraries:
+- acl and xattr development libraries
+- gnutls
+- readline
+
 Run this:
 
-  cd samba4/source
-  ./autogen.sh
-  ./configure.developer -C
-  make
+  $ cd samba4/source
+  $ ./configure
+  $ make proto all
 
-If you have gcc 3.4 or newer, then run "make pch" before "make" to
+If you have gcc 3.4 or newer, then substitute "pch" for "proto" to
 greatly speed up the compile process (about 5x faster).
 
-
 Step 3: install Samba4
 ----------------------
 
@@ -51,38 +59,38 @@ Run this as a user who have permission to write to the install
 directory (defaults to /usr/local/samba). Use --prefix option to
 configure above to change this.
  
-  make install
+  make install
 
 
 Step 4: provision Samba4
 ------------------------
 
-The "provision" step sets up a basic user database. 
-
-  cd source
-  ./script/provision.pl --realm=YOUR.REALM --domain=YOURDOM --adminpass=SOMEPASSWORD
+The "provision" step sets up a basic user database. Make sure your smbscript
+binary is installed in a directory listed in your PATH environment variable.
+It is presumed it's available just like any other commands from your shell.
+Must be run as a user with permission to write to the install directory.
 
-This will create a file called newsam.ldb. You need to copy this to
-sam.ldb in the "private" subdirectory of your install. For example:
+  # cd source
+  # ./setup/provision --realm=YOUR.REALM --domain=YOURDOM --adminpass=SOMEPASSWORD
 
-  cp newsam.ldb /usr/local/samba/private/sam.ldb
+REMINDER: Add the "bin" directory of the path you installed to
+          (e.g. /usr/local/samba/bin) to your path, or the provision command
+          will not work.
 
+'YOURDOM' is the NT4 style domain name. 'YOUR.REALM' is your kerberos
+realm, which is typically your DNS domain name.
 
 Step 5: Create a simple smb.conf
 --------------------------------
 
-You need to create a smb.conf file in the lib/ directory of your
-install. The default is /usr/local/samba/lib/smb.conf. A minimal
-smb.conf would be:
-
-  workgroup = YOURDOM
+The provisioning will create a very simple smb.conf with no shares by
+default. You will need to update it to add at least one share. For
+example:
 
   [test]
        path = /data/test
        read only = no
 
-The workgroup must exactly match the --domain argument you gave to provision.pl
-
 
 Step 6: starting Samba4
 -----------------------
@@ -90,11 +98,15 @@ Step 6: starting Samba4
 The simplest is to just run "smbd", but as a developer you may find
 the following more useful:
 
-   smbd -i -M single -d3
+   # smbd -i -M single
 
 that means "start smbd without messages in stdout, and running a
-single process, with level 3 debugging". That mode of operation makes
-debugging smbd with gdb particularly easy.
+single process. That mode of operation makes debugging smbd with gdb
+particularly easy.
+
+Note that now it is no longer necessary to have an instance of nmbd
+from Samba 3 running.  If you are running any smbd or nmbd processes
+they need to be stopped before starting smbd from Samba 4.
 
 Make sure you put the bin and sbin directories from your new install
 in your $PATH. Make sure you run the right version!
@@ -105,14 +117,67 @@ Step 7: testing Samba4
 
 try these commands:
 
-      smbclient //localhost/test -Uadministrator%SOMEPASSWORD
+     $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD
     or
-     ./script/tests/test_posix.sh //localhost/test administrator
-    SOMEPASSWORD
+     $ ./script/tests/test_posix.sh //localhost/test administrator SOMEPASSWORD
+
+
+NOTE about filesystem support
+-----------------------------
+
+To use the advanced features of Samba4 you need a filesystem that
+supports both the "user" and "system" xattr namespaces.
+
+If you run Linux with a 2.6 kernel and ext3 this means you need to
+include the option "user_xattr" in your /etc/fstab. For example:
+
+/dev/hda3              /home                   ext3    user_xattr     1 1
+
+You also need to compile your kernel with the XATTR and SECURITY
+options for your filesystem. For ext3 that means you need:
+
+   CONFIG_EXT3_FS_XATTR=y
+   CONFIG_EXT3_FS_SECURITY=y
+
+If you are running a Linux 2.6 kernel with CONFIG_IKCONFIG_PROC
+defined you can check this with the following command:
+
+   $ zgrep CONFIG_EXT3_FS /proc/config.gz
+
+If you don't have a filesystem with xattr support, then you can
+simulate it by using the option:
+
+   posix:eadb = /usr/local/samba/eadb.tdb
+
+that will place all extra file attributes (NT ACLs, DOS EAs, streams
+etc), in that tdb. It is not efficient, and doesn't scale well, but at
+least it gives you a choice when you don't have a modern filesystem.
+
+Testing your filesystem
+-----------------------
+
+To test your filesystem support, install the 'attr' package and run
+the following 4 commands as root:
+
+  # touch test.txt
+  # setfattr -n user.test -v test test.txt
+  # setfattr -n security.test -v test2 test.txt
+  # getfattr -d test.txt
+  # getfattr -n security.test -d test.txt
+
+You should see output like this:
+
+  # file: test.txt
+  user.test="test"
+
+  # file: test.txt
+  security.test="test2"
+
+If you get any "Operation not supported" errors then it means your
+kernel is not configured correctly, or your filesystem is not mounted
+with the right options.
 
-Note that to pass all the tests you would need to be using a
-filesystem with user_xattr support. On many Linux systems with an ext3
-filesystem this means mounting with the "-o user_xattr"
-option. Consult your filesystem and kernel docs for more details.
+If you get any "Operation not permitted" errors then it probably means
+you didn't try the test as root.