cc728b904a27dc423fc4d58c93491294f7848d01
[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 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