docs/docbook/projdoc/Compiling.xml

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