docs/docbook/projdoc/Compiling.xml

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