Adding more docs.
[ira/wip.git] / docs / docbook / projdoc / Compiling.sgml
1 <chapter id="compiling">
2 <chapterinfo>
3         <author>
4                 <affiliation>
5                         <orgname>Samba Team</orgname>
6                 </affiliation>
7         </author>
8         &author.jelmer;
9         
10         <pubdate> (22 May 2001) </pubdate>
11         <pubdate> 18 March 2003 </pubdate>
12 </chapterinfo>
13
14 <title>How to compile SAMBA</title>
15
16 <para>
17 You can obtain the samba source from the <ulink url="http://samba.org/">samba website</ulink>. To obtain a development version, 
18 you can download samba from CVS or using rsync.
19 </para>
20
21 <sect1>
22 <title>Access Samba source code via CVS</title>
23
24 <sect2>
25 <title>Introduction</title>
26
27 <para>
28 Samba is developed in an open environment.  Developers use CVS
29 (Concurrent Versioning System) to "checkin" (also known as 
30 "commit") new source code.  Samba's various CVS branches can
31 be accessed via anonymous CVS using the instructions
32 detailed in this chapter.
33 </para>
34
35 <para>
36 This chapter is a modified version of the instructions found at
37 <ulink url="http://samba.org/samba/cvs.html">http://samba.org/samba/cvs.html</ulink>
38 </para>
39
40 </sect2>
41
42 <sect2>
43 <title>CVS Access to samba.org</title>
44
45 <para>
46 The machine samba.org runs a publicly accessible CVS 
47 repository for access to the source code of several packages, 
48 including samba, rsync and jitterbug. There are two main ways of 
49 accessing the CVS server on this host.
50 </para>
51
52 <sect3>
53 <title>Access via CVSweb</title>
54
55 <para>
56 You can access the source code via your 
57 favourite WWW browser. This allows you to access the contents of 
58 individual files in the repository and also to look at the revision 
59 history and commit logs of individual files. You can also ask for a diff 
60 listing between any two versions on the repository.
61 </para>
62
63 <para>
64 Use the URL : <ulink
65 url="http://samba.org/cgi-bin/cvsweb">http://samba.org/cgi-bin/cvsweb</ulink>
66 </para>
67 </sect3>
68
69 <sect3>
70 <title>Access via cvs</title>
71
72 <para>
73 You can also access the source code via a 
74 normal cvs client.  This gives you much more control over you can 
75 do with the repository and allows you to checkout whole source trees 
76 and keep them up to date via normal cvs commands. This is the 
77 preferred method of access if you are a developer and not
78 just a casual browser.
79 </para>
80
81 <para>
82 To download the latest cvs source code, point your
83 browser at the URL : <ulink url="http://www.cyclic.com/">http://www.cyclic.com/</ulink>.
84 and click on the 'How to get cvs' link. CVS is free software under 
85 the GNU GPL (as is Samba).  Note that there are several graphical CVS clients
86 which provide a graphical interface to the sometimes mundane CVS commands.
87 Links to theses clients are also available from http://www.cyclic.com.
88 </para>
89
90 <para>
91 To gain access via anonymous cvs use the following steps. 
92 For this example it is assumed that you want a copy of the 
93 samba source code. For the other source code repositories 
94 on this system just substitute the correct package name
95 </para>
96
97 <orderedlist>
98 <listitem>
99         <para>
100         Install a recent copy of cvs. All you really need is a 
101         copy of the cvs client binary. 
102         </para>
103 </listitem>
104
105
106 <listitem>
107         <para>
108         Run the command 
109         </para>
110
111         <para>
112         <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot login</userinput>
113         </para>
114         
115         <para>
116         When it asks you for a password type <userinput>cvs</userinput>.
117         </para>
118 </listitem>
119
120
121 <listitem>
122         <para>
123         Run the command 
124         </para>
125         
126         <para>
127         <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot co samba</userinput>
128         </para>
129         
130         <para>
131         This will create a directory called samba containing the 
132         latest samba source code (i.e. the HEAD tagged cvs branch). This 
133         currently corresponds to the 3.0 development tree. 
134         </para>
135         
136         <para>
137         CVS branches other HEAD can be obtained by using the <parameter>-r</parameter>
138         and defining a tag name.  A list of branch tag names can be found on the
139         "Development" page of the samba web site.  A common request is to obtain the
140         latest 2.2 release code.  This could be done by using the following userinput.
141         </para>
142         
143         <para>
144         <userinput>cvs -d :pserver:cvs@samba.org:/cvsroot co -r SAMBA_2_2 samba</userinput>
145         </para>
146 </listitem>
147
148 <listitem>
149         <para>
150         Whenever you want to merge in the latest code changes use 
151         the following command from within the samba directory: 
152         </para>
153         
154         <para>
155         <userinput>cvs update -d -P</userinput>
156         </para>
157 </listitem>
158 </orderedlist>
159         
160 </sect3>
161 </sect2>
162
163 </sect1>
164
165 <sect1>
166         <title>Accessing the samba sources via rsync and ftp</title>
167
168         <para>
169         pserver.samba.org also exports unpacked copies of most parts of the CVS tree at <ulink url="ftp://pserver.samba.org/pub/unpacked">ftp://pserver.samba.org/pub/unpacked</ulink> and also via anonymous rsync at rsync://pserver.samba.org/ftp/unpacked/. I recommend using rsync rather than ftp.
170         See <ulink url="http://rsync.samba.org/">the rsync homepage</ulink> for more info on rsync.                       
171         </para>
172
173         <para>
174         The disadvantage of the unpacked trees
175         is that they do not support automatic
176         merging of local changes like CVS does.
177         rsync access is most convenient for an 
178         initial install.                       
179         </para>
180 </sect1>
181
182 <sect1>
183 <title>Verifying Samba's PGP signature</title>
184
185 <para>
186 In these days of insecurity, it's strongly recommended that you verify the PGP signature for any
187 source file before installing it. According to Jerry Carter of the Samba Team, only about 22% of
188 all Samba downloads have had a corresponding PGP signature download (a very low percentage, which
189 should be considered a bad thing). Even if you're not downloading from a mirror site, verifying PGP
190 signatures should be a standard reflex.
191 </para>
192
193
194 <para>
195 With that said, go ahead and download the following files:
196 </para>
197
198 <para><programlisting>
199      $ wget http://us1.samba.org/samba/ftp/samba-2.2.8a.tar.asc
200      $ wget http://us1.samba.org/samba/ftp/samba-pubkey.asc
201 </programlisting></para>
202
203 <para>
204 The first file is the PGP signature for the Samba source file; the other is the Samba public
205 PGP key itself. Import the public PGP key with:
206 </para>
207
208 <programlisting>
209      $ gpg --import samba-pubkey.asc
210 </programlisting>
211
212 <para>
213 And verify the Samba source code integrity with:
214 </para>
215
216 <programlisting>
217      $ gzip -d samba-2.2.8a.tar.gz
218      $ gpg --verify samba-2.2.8a.tar.asc
219 </programlisting>
220
221 <para>
222 If you receive a message like, "Good signature from Samba Distribution Verification Key..."
223 then all is well. The warnings about trust relationships can be ignored. An example of what
224 you would not want to see would be:
225 </para>
226
227 <programlisting>
228      gpg: BAD signature from "Samba Distribution Verification Key"
229 </programlisting>
230
231 </sect1>
232
233 <sect1>
234         <title>Building the Binaries</title>
235         
236         <para>To do this, first run the program <userinput>./configure
237         </userinput> in the source directory. This should automatically 
238         configure Samba for your operating system. If you have unusual 
239         needs then you may wish to run</para>
240         
241         <para><prompt>root# </prompt><userinput>./configure --help
242         </userinput></para>
243         
244         <para>first to see what special options you can enable.
245         Then executing</para>
246         
247         <para><prompt>root# </prompt><userinput>make</userinput></para>
248         
249         <para>will create the binaries. Once it's successfully 
250         compiled you can use </para>
251         
252         <para><prompt>root# </prompt><userinput>make install</userinput></para>
253         
254         <para>to install the binaries and manual pages. You can 
255         separately install the binaries and/or man pages using</para>
256         
257         <para><prompt>root# </prompt><userinput>make installbin
258         </userinput></para>
259         
260         <para>and</para>
261         
262         <para><prompt>root# </prompt><userinput>make installman
263         </userinput></para>
264
265         <para>Note that if you are upgrading for a previous version 
266         of Samba you might like to know that the old versions of 
267         the binaries will be renamed with a ".old" extension. You 
268         can go back to the previous version with</para>
269         
270         <para><prompt>root# </prompt><userinput>make revert
271         </userinput></para>
272         
273         <para>if you find this version a disaster!</para>
274
275         <sect2>
276         <title>Compiling samba with Active Directory support</title>
277         
278         <para>In order to compile samba with ADS support, you need to have installed
279         on your system: 
280         <simplelist>
281         <member>the MIT kerberos development libraries (either install from the sources or use a package). The heimdal libraries will not work.</member>
282         <member>the OpenLDAP development libraries.</member>
283 </simplelist></para>
284
285         <para>If your kerberos libraries are in a non-standard location then
286           remember to add the configure option --with-krb5=DIR.</para>
287
288     <para>After you run configure make sure that <filename>include/config.h</filename> it generates contains lines like this:</para>
289
290                   <para><programlisting>
291 #define HAVE_KRB5 1
292 #define HAVE_LDAP 1
293                   </programlisting></para>
294
295           <para>If it doesn't then configure did not find your krb5 libraries or
296             your ldap libraries. Look in config.log to figure out why and fix
297                   it.</para>
298
299         <sect3>
300         <title>Installing the required packages for Debian</title>
301
302         <para>On Debian you need to install the following packages:</para>
303         <para>
304         <simplelist>
305         <member>libkrb5-dev</member>
306         <member>krb5-user</member>
307         </simplelist>
308         </para>
309         </sect3>
310
311         <sect3>
312         <title>Installing the required packages for RedHat</title>
313
314         <para>On RedHat this means you should have at least: </para>
315         <para>
316         <simplelist>
317         <member>krb5-workstation (for kinit)</member>
318         <member>krb5-libs (for linking with)</member>
319         <member>krb5-devel (because you are compiling from source)</member>
320         </simplelist>
321         </para>
322
323         <para>in addition to the standard development environment.</para>
324
325         <para>Note that these are not standard on a RedHat install, and you may need
326         to get them off CD2.</para>
327
328         </sect3>
329         
330         </sect2>
331                           
332 </sect1>
333
334 <sect1>
335         <title>Starting the smbd and nmbd</title>
336
337         <para>You must choose to start smbd and nmbd either
338         as daemons or from <application>inetd</application>Don't try
339         to do both!  Either you can put them in <filename>
340         inetd.conf</filename> and have them started on demand
341         by <application>inetd</application>, or you can start them as
342         daemons either from the command line or in <filename>
343         /etc/rc.local</filename>. See the man pages for details
344         on the command line options. Take particular care to read
345         the bit about what user you need to be in order to start
346         Samba.  In many cases you must be root.</para>
347
348         <para>The main advantage of starting <application>smbd</application>
349         and <application>nmbd</application> using the recommended daemon method
350         is that they will respond slightly more quickly to an initial connection
351         request.</para>
352
353         <sect2>
354                 <title>Starting from inetd.conf</title>
355
356                 <para>NOTE; The following will be different if 
357                 you use NIS, NIS+ or LDAP to distribute services maps.</para>
358                 
359                 <para>Look at your <filename>/etc/services</filename>. 
360                 What is defined at port 139/tcp. If nothing is defined 
361                 then add a line like this:</para>
362
363                 <para><userinput>netbios-ssn     139/tcp</userinput></para>
364
365                 <para>similarly for 137/udp you should have an entry like:</para>
366
367                 <para><userinput>netbios-ns     137/udp</userinput></para>
368
369                 <para>Next edit your <filename>/etc/inetd.conf</filename> 
370                 and add two lines something like this:</para>
371
372                 <para><programlisting>
373                 netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd 
374                 netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd 
375                 </programlisting></para>
376
377                 <para>The exact syntax of <filename>/etc/inetd.conf</filename> 
378                 varies between unixes. Look at the other entries in inetd.conf 
379                 for a guide.</para>
380
381                 <note><para>Some unixes already have entries like netbios_ns 
382                 (note the underscore) in <filename>/etc/services</filename>. 
383                 You must either edit <filename>/etc/services</filename> or
384                 <filename>/etc/inetd.conf</filename> to make them consistent.</para></note>
385
386                 <note><para>On many systems you may need to use the 
387                 <command>interfaces</command> option in &smb.conf; to specify the IP address 
388                 and netmask of your interfaces. Run <application>ifconfig</application> 
389                 as root if you don't know what the broadcast is for your
390                 net. &nmbd; tries to determine it at run 
391                 time, but fails on some unixes. 
392                 </para></note>
393
394                 <warning><para>Many unixes only accept around 5 
395                 parameters on the command line in <filename>inetd.conf</filename>. 
396                 This means you shouldn't use spaces between the options and 
397                 arguments, or you should use a script, and start the script 
398                 from <command>inetd</command>.</para></warning>
399
400                 <para>Restart <command>inetd</command>, perhaps just send 
401                 it a HUP. If you have installed an earlier version of <application>
402                 nmbd</application> then you may need to kill nmbd as well.</para>
403         </sect2>
404         
405         <sect2>
406                 <title>Alternative: starting it as a daemon</title>
407
408                 <para>To start the server as a daemon you should create 
409                 a script something like this one, perhaps calling 
410                 it <filename>startsmb</filename>.</para>
411
412                 <para><programlisting>
413                 #!/bin/sh
414                 /usr/local/samba/bin/smbd -D 
415                 /usr/local/samba/bin/nmbd -D 
416                 </programlisting></para>
417
418                 <para>then make it executable with <command>chmod 
419                 +x startsmb</command></para>
420
421                 <para>You can then run <command>startsmb</command> by 
422                 hand or execute it from <filename>/etc/rc.local</filename>
423                 </para>
424
425                 <para>To kill it send a kill signal to the processes 
426                 <command>nmbd</command> and <command>smbd</command>.</para>
427
428                 <note><para>If you use the SVR4 style init system then 
429                 you may like to look at the <filename>examples/svr4-startup</filename>
430                 script to make Samba fit into that system.</para></note>
431         </sect2>
432 </sect1>
433 </chapter>