Add python bindings for unixinfo.
[jelmer/samba4-debian.git] / howto.txt
index cc728b904a27dc423fc4d58c93491294f7848d01..d128baa5bd47ca483ab3262b2ad1a2ce573cc259 100644 (file)
--- a/howto.txt
+++ b/howto.txt
@@ -1,83 +1,72 @@
 Samba4 developer howto
-----------------------
+======================
 
 tridge@samba.org, December 2004
 
+A more up to date version of this howto can be found in the wiki 
+at http://wiki.samba.org/index.php/Samba4/HOWTO.
 
 This is a very basic document on how to setup a simple Samba4
 server. This is aimed at developers who are already familiar with
 Samba3 and wish to participate in Samba4 development. This is not
 aimed at production use of Samba4.
 
+.. contents::
 
 Step 1: download Samba4
 -----------------------
 
+If you have downloaded the Samba4 code via a tarball released from the
+samba.org website, Step 1 has already been completed for you.  For testing
+with the version released in the tarball, you may continue on to Step 2.  Note
+that the references below to the top-level directory named "samba4" will
+instead be based on the name of the tarball downloaded (e.g.
+"samba-4.0.0alpha3" for the tarball samba-4.0.0alpha3.tar.gz).
+
 There are 2 methods of doing this:
 
-  method 1:  "rsync -avz samba.org::ftp/unpacked/samba4 ."
+  method 1:  "rsync -avz samba.org::ftp/unpacked/samba_4_0_test/ samba4"
 
-  method 2:  "svn co svn://svnanon.samba.org/samba/branches/SAMBA_4_0 samba4"
+  method 2:  "git clone git://git.samba.org/samba.git samba4; cd samba4; git checkout v4-0-test; cd .."
 
 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. 
-
-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
-
-Step 1a: Use Lorikeet/Heimdal
------------------------------
-
-If you want to use Kerberos in Samba4, you must use
-'Lorikeet/heimdal', and place a checkout into samba4/source/heimdal
-
-There are 2 methods of doing this:
-
-  method 1:  
-    $ cd samba4/source
-    $ rsync -avz samba.org::ftp/unpacked/lorikeet-heimdal heimdal
+directory. If you don't have rsync or git then install one of them. 
 
-  method 2:  
+Since only released versions of Samba contain a pregenerated configure script, 
+you will have to generate it by hand::
 
   $ cd samba4/source
-    $ svn co svn://svnanon.samba.org/lorikeet/trunk/heimdal heimdal
+ $ cd samba4/source
+ $ ./autogen.sh
 
-both methods will create a directory called "heimdal" in the samba4/source
-directory. 
+Note that the above rsync command will give you a checked out git
+repository. So if you also have git you can update it to the latest
+version at some future date using::
 
-(Long-term, we will either import Heimdal from 'lorikeet', or setup a
-reference between the repositories, so this and svn update works
-automaticly. In the short term, you must manually update this directory). 
+  $ cd samba4
+  $ git pull origin v4-0-test
 
 Step 2: compile Samba4
 ----------------------
 
-Run this:
+Recommended optional development libraries:
+- acl and xattr development libraries
+- gnutls
+- readline
 
-  $ cd samba4/source
-  $ ./autogen.sh
-  $ ./configure.developer -C
+Run this::
 
-If you did not include heimdal, run this:
+  $ cd samba4/source
+  $ ./configure
   $ make
 
-If you did include Heimdal, a different step is required:
-  $ make HEIMDAL_EXTERNAL all
-
-If you have gcc 3.4 or newer, then run "make pch" before "make" to
-greatly speed up the compile process (about 5x faster).
-
-
 Step 3: install Samba4
 ----------------------
 
 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
 
@@ -86,44 +75,43 @@ Step 4: provision Samba4
 ------------------------
 
 The "provision" step sets up a basic user database. 
+Must be run as a user with permission to write to the install directory.
 
-  $ cd source
-  $ ./setup/provision.pl --realm=YOUR.REALM --domain=YOURDOM --adminpass=SOMEPASSWORD
+::
 
-This will create a number of new 'ldb' database files in a directory
-newdb.XXX. You need to move these to the "private" subdirectory of
-your install. For example:
+  # cd source
+  # bin/smbpython ./setup/provision --realm=YOUR.REALM --domain=YOURDOM \
+  #  --adminpass=SOMEPASSWORD --server-role='domain controller'
 
-  # mv newdb.123/*.ldb /usr/local/samba/private/
+REMINDER: Use the path to smbpython, as the provision command
+          will not work with the system python.
 
+'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
 -----------------------
 
 The simplest is to just run "smbd", but as a developer you may find
-the following more useful:
+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
@@ -136,11 +124,9 @@ in your $PATH. Make sure you run the right version!
 Step 7: testing Samba4
 ----------------------
 
-try these commands:
+try this command::
 
-     $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD
-    or
-     $ ./script/tests/test_posix.sh //localhost/test administrator SOMEPASSWORD
+  $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD
 
 
 NOTE about filesystem support
@@ -150,23 +136,23 @@ 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:
+include the option "user_xattr" in your /etc/fstab. For example::
 
-/dev/hda3              /home                   ext3    user_xattr     1 1
+   /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:
+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:
+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:
+simulate it by using the option::
 
    posix:eadb = /usr/local/samba/eadb.tdb
 
@@ -178,7 +164,7 @@ Testing your filesystem
 -----------------------
 
 To test your filesystem support, install the 'attr' package and run
-the following 4 commands as root:
+the following 4 commands as root::
 
   # touch test.txt
   # setfattr -n user.test -v test test.txt
@@ -186,11 +172,11 @@ the following 4 commands as root:
   # getfattr -d test.txt
   # getfattr -n security.test -d test.txt
 
-You should see output like this:
+You should see output like this::
 
   # file: test.txt
   user.test="test"
-
+  
   # file: test.txt
   security.test="test2"
 
@@ -201,4 +187,5 @@ with the right options.
 If you get any "Operation not permitted" errors then it probably means
 you didn't try the test as root.
 
-
+..
+       vim: ft=rest