r6361: Update howto and provisioning script with the moves made in r6207.
[jelmer/samba4-debian.git] / 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
33 Step 2: compile Samba4
34 ----------------------
35
36 Run this:
37
38   $ cd samba4/source
39   $ ./autogen.sh
40   $ ./configure.developer -C
41   $ make
42
43 If you have gcc 3.4 or newer, then run "make pch" before "make" to
44 greatly speed up the compile process (about 5x faster).
45
46
47 Step 3: install Samba4
48 ----------------------
49
50 Run this as a user who have permission to write to the install
51 directory (defaults to /usr/local/samba). Use --prefix option to
52 configure above to change this.
53  
54   # make install
55
56
57 Step 4: provision Samba4
58 ------------------------
59
60 The "provision" step sets up a basic user database. 
61
62   $ cd source
63   $ ./setup/provision.pl --realm=YOUR.REALM --domain=YOURDOM --adminpass=SOMEPASSWORD
64
65 This will create a number of new 'ldb' database files in a directory
66 newdb.XXX. You need to move these to the "private" subdirectory of
67 your install. For example:
68
69   # mv newdb.123/*.ldb /usr/local/samba/private/
70
71
72 Step 5: Create a simple smb.conf
73 --------------------------------
74
75 You need to create a smb.conf file in the lib/ directory of your
76 install. The default is /usr/local/samba/lib/smb.conf. A minimal
77 smb.conf would be:
78
79   workgroup = YOURDOM
80
81   [test]
82         path = /data/test
83         read only = no
84
85 The workgroup must exactly match the --domain argument you gave to provision.pl
86
87
88 Step 6: starting Samba4
89 -----------------------
90
91 The simplest is to just run "smbd", but as a developer you may find
92 the following more useful:
93
94    # smbd -i -M single -d3
95
96 that means "start smbd without messages in stdout, and running a
97 single process, with level 3 debugging". That mode of operation makes
98 debugging smbd with gdb particularly easy.
99
100 Note that now it is no longer necessary to have an instance of nmbd
101 from Samba 3 running.  If you are running any smbd or nmbd processes
102 they need to be stopped before starting smbd from Samba 4.
103
104 Make sure you put the bin and sbin directories from your new install
105 in your $PATH. Make sure you run the right version!
106
107
108 Step 7: testing Samba4
109 ----------------------
110
111 try these commands:
112
113      $ smbclient //localhost/test -Uadministrator%SOMEPASSWORD
114     or
115      $ ./script/tests/test_posix.sh //localhost/test administrator SOMEPASSWORD
116
117
118 NOTE about filesystem support
119 -----------------------------
120
121 To use the advanced features of Samba4 you need a filesystem that
122 supports both the "user" and "system" xattr namespaces.
123
124 If you run Linux with a 2.6 kernel and ext3 this means you need to
125 include the option "user_xattr" in your /etc/fstab. For example:
126
127 /dev/hda3               /home                   ext3    user_xattr     1 1
128
129 You also need to compile your kernel with the XATTR and SECURITY
130 options for your filesystem. For ext3 that means you need:
131
132    CONFIG_EXT3_FS_XATTR=y
133    CONFIG_EXT3_FS_SECURITY=y
134
135 If you are running a Linux 2.6 kernel with CONFIG_IKCONFIG_PROC
136 defined you can check this with the following command:
137
138    $ zgrep CONFIG_EXT3_FS /proc/config.gz
139
140 If you don't have a filesystem with xattr support, then you can
141 simulate it by using the option:
142
143    posix:eadb = /usr/local/samba/eadb.tdb
144
145 that will place all extra file attributes (NT ACLs, DOS EAs, streams
146 etc), in that tdb. It is not efficient, and doesn't scale well, but at
147 least it gives you a choice when you don't have a modern filesystem.
148
149 Testing your filesystem
150 -----------------------
151
152 To test your filesystem support, install the 'attr' package and run
153 the following 4 commands as root:
154
155   # touch test.txt
156   # setfattr -n user.test -v test test.txt
157   # setfattr -n security.test -v test2 test.txt
158   # getfattr -d test.txt
159   # getfattr -n security.test -d test.txt
160
161 You should see output like this:
162
163   # file: test.txt
164   user.test="test"
165
166   # file: test.txt
167   security.test="test2"
168
169 If you get any "Operation not supported" errors then it means your
170 kernel is not configured correctly, or your filesystem is not mounted
171 with the right options.
172
173 If you get any "Operation not permitted" errors then it probably means
174 you didn't try the test as root.