howto.txt

   1 Samba4 developer howto
   2 ----------------------
   3
   4 tridge@samba.org, December 2004
   5
   6
   7 This is a very basic document on how to setup a simple Samba4
   8 server. This is aimed at developers who are already familiar with
   9 Samba3 and wish to participate in Samba4 development. This is not
  10 aimed at production use of Samba4.
  11
  12
  13 Step 1: download Samba4
  14 -----------------------
  15
  16 There are 2 methods of doing this:
  17
  18   method 1:  "rsync -avz samba.org::ftp/unpacked/samba4 ."
  19
  20   method 2:  "svn co svn://svnanon.samba.org/samba/branches/SAMBA_4_0 samba4"
  21
  22 both methods will create a directory called "samba4" in the current
  23 directory. If you don't have rsync or svn then install one of them.
  24
  25 Note that the above rsync command will give you a checked out svn
  26 repository. So if you also have svn you can update it to the latest
  27 version at some future date using:
  28
  29   $ cd samba4
  30   $ svn up
  31
  32 Step 1a: Use Lorikeet/Heimdal
  33 -----------------------------
  34
  35 If you want to use Kerberos in Samba4, you must use
  36 'Lorikeet/heimdal', and place a checkout into samba4/source/heimdal
  37
  38 There are 2 methods of doing this:
  39
  40   method 1:
  41     $ cd samba4/source
  42     $ rsync -avz samba.org::ftp/unpacked/lorikeet-heimdal heimdal
  43
  44   method 2:
  45
  46     $ cd samba4/source
  47     $ svn co svn://svnanon.samba.org/lorikeet/trunk/heimdal heimdal
  48
  49 both methods will create a directory called "heimdal" in the samba4/source
  50 directory.
  51
  52 (Long-term, we will either import Heimdal from 'lorikeet', or setup a
  53 reference between the repositories, so this and svn update works
  54 automaticly. In the short term, you must manually update this directory).
  55
  56 Step 2: compile Samba4
  57 ----------------------
  58
  59 Run this:
  60
  61   $ cd samba4/source
  62   $ ./autogen.sh
  63   $ ./configure.developer -C
  64
  65 If you did not include heimdal, run this:
  66   $ make
  67
  68 If you did include Heimdal, a different step is required:
  69   $ make HEIMDAL_EXTERNAL all
  70
  71 If you have gcc 3.4 or newer, then run "make pch" before "make" to
  72 greatly speed up the compile process (about 5x faster).
  73
  74
  75 Step 3: install Samba4
  76 ----------------------
  77
  78 Run this as a user who have permission to write to the install
  79 directory (defaults to /usr/local/samba). Use --prefix option to
  80 configure above to change this.
  81
  82   # make install
  83
  84
  85 Step 4: provision Samba4
  86 ------------------------
  87
  88 The "provision" step sets up a basic user database.
  89
  90   $ cd source
  91   $ ./setup/provision.pl --realm=YOUR.REALM --domain=YOURDOM --adminpass=SOMEPASSWORD
  92
  93 This will create a number of new 'ldb' database files in a directory
  94 newdb.XXX. You need to move these to the "private" subdirectory of
  95 your install. For example:
  96
  97   # mv newdb.123/*.ldb /usr/local/samba/private/
  98
  99
 100 Step 5: Create a simple smb.conf
 101 --------------------------------
 102
 103 You need to create a smb.conf file in the lib/ directory of your
 104 install. The default is /usr/local/samba/lib/smb.conf. A minimal
 105 smb.conf would be:
 106
 107   workgroup = YOURDOM
 108
 109   [test]
 110         path = /data/test
 111         read only = no
 112
 113 The workgroup must exactly match the --domain argument you gave to provision.pl
 114
 115
 116 Step 6: starting Samba4
 117 -----------------------
 118
 119 The simplest is to just run "smbd", but as a developer you may find
 120 the following more useful:
 121
 122    # smbd -i -M single -d3
 123
 124 that means "start smbd without messages in stdout, and running a
 125 single process, with level 3 debugging". That mode of operation makes
 126 debugging smbd with gdb particularly easy.
 127
 128 Note that now it is no longer necessary to have an instance of nmbd
 129 from Samba 3 running.  If you are running any smbd or nmbd processes
 130 they need to be stopped before starting smbd from Samba 4.
 131
 132 Make sure you put the bin and sbin directories from your new install
 133 in your $PATH. Make sure you run the right version!
 134
 135
 136 Step 7: testing Samba4
 137 ----------------------
 138
 139 try these commands:
 140
 141      $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD
 142     or
 143      $ ./script/tests/test_posix.sh //localhost/test administrator SOMEPASSWORD
 144
 145
 146 NOTE about filesystem support
 147 -----------------------------
 148
 149 To use the advanced features of Samba4 you need a filesystem that
 150 supports both the "user" and "system" xattr namespaces.
 151
 152 If you run Linux with a 2.6 kernel and ext3 this means you need to
 153 include the option "user_xattr" in your /etc/fstab. For example:
 154
 155 /dev/hda3               /home                   ext3    user_xattr     1 1
 156
 157 You also need to compile your kernel with the XATTR and SECURITY
 158 options for your filesystem. For ext3 that means you need:
 159
 160    CONFIG_EXT3_FS_XATTR=y
 161    CONFIG_EXT3_FS_SECURITY=y
 162
 163 If you are running a Linux 2.6 kernel with CONFIG_IKCONFIG_PROC
 164 defined you can check this with the following command:
 165
 166    $ zgrep CONFIG_EXT3_FS /proc/config.gz
 167
 168 If you don't have a filesystem with xattr support, then you can
 169 simulate it by using the option:
 170
 171    posix:eadb = /usr/local/samba/eadb.tdb
 172
 173 that will place all extra file attributes (NT ACLs, DOS EAs, streams
 174 etc), in that tdb. It is not efficient, and doesn't scale well, but at
 175 least it gives you a choice when you don't have a modern filesystem.
 176
 177 Testing your filesystem
 178 -----------------------
 179
 180 To test your filesystem support, install the 'attr' package and run
 181 the following 4 commands as root:
 182
 183   # touch test.txt
 184   # setfattr -n user.test -v test test.txt
 185   # setfattr -n security.test -v test2 test.txt
 186   # getfattr -d test.txt
 187   # getfattr -n security.test -d test.txt
 188
 189 You should see output like this:
 190
 191   # file: test.txt
 192   user.test="test"
 193
 194   # file: test.txt
 195   security.test="test2"
 196
 197 If you get any "Operation not supported" errors then it means your
 198 kernel is not configured correctly, or your filesystem is not mounted
 199 with the right options.
 200
 201 If you get any "Operation not permitted" errors then it probably means
 202 you didn't try the test as root.
 203
 204