769e0b10cf7b95946821b8c16adfee50891243d2
[tprouty/samba.git] / docs / Samba3-HOWTO / TOSHARG-Install.xml
1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <chapter id="install">
4 <chapterinfo>
5         &author.tridge;
6         &author.jelmer;
7         &author.jht;
8         &author.kauer;
9         &author.danshearer;
10         <!-- Isn't some of this written by others as well? -->
11
12 </chapterinfo>
13
14 <title>How to Install and Test SAMBA</title>
15
16 <sect1>
17         <title>Obtaining and Installing Samba</title>
18
19         <para>
20         <indexterm><primary>packages</primary></indexterm>
21         Binary packages of Samba are included in almost any Linux or UNIX distribution. There are also some
22         packages available at <ulink url="http://samba.org/">the Samba home page</ulink>. Refer to the manual of your
23         operating system for details on installing packages for your specific operating system.
24         </para>
25
26         <para>
27         <indexterm><primary>compile</primary></indexterm>
28         If you need to compile Samba from source, check <link linkend="compiling">How to Compile Samba</link>.
29         </para>
30
31 </sect1>
32
33 <sect1>
34         <title>Configuring Samba (smb.conf)</title>
35
36         <para>
37         <indexterm><primary>/etc/samba/smb.conf</primary></indexterm>
38         <indexterm><primary>SWAT</primary></indexterm>
39         Samba's configuration is stored in the &smb.conf; file, which usually resides in
40         <filename>/etc/samba/smb.conf</filename> or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either
41         edit this file yourself or do it using one of the many graphical tools that are available, such as the
42         Web-based interface SWAT, that is included with Samba.
43         </para>
44
45         <sect2>
46         <title>Configuration File Syntax</title>
47
48         <para>
49         <indexterm><primary>section name</primary></indexterm>
50         The &smb.conf; file uses the same syntax as the various old <filename>.ini</filename> files in Windows
51         3.1: Each file consists of various sections, which are started by putting the section name between brackets
52         (<literal>[]</literal>) on a new line. Each contains zero or more key/value pairs separated by an equality
53         sign (<literal>=</literal>). The file is just a plaintext file, so you can open and edit it with your favorite
54         editing tool.
55         </para>
56
57         <para>
58         <indexterm><primary>meta-service</primary></indexterm>
59         <indexterm><primary>print</primary><secondary>queue</secondary></indexterm>
60         <indexterm><primary>share</primary></indexterm>
61         <indexterm><primary>spooler.</primary></indexterm>
62         <indexterm><primary>print</primary><secondary>spooler</secondary></indexterm>
63         <indexterm><primary>spool</primary><secondary>directory</secondary></indexterm>
64         Each section in the &smb.conf; file represents either a share or a meta-service on the Samba server. The
65         section <literal>[global]</literal> is special, since it contains settings that apply to the whole Samba
66         server.  Samba supports a number of meta-services, each of which serves its own purpose. For example, the
67         <literal>[homes]</literal> share is a meta-service that causes Samba to provide a personal home share for
68         each user. The <literal>[printers]</literal> share is a meta-service that establishes print queue support
69         and that specifies the location of the intermediate spool directory into which print jobs are received
70         from Windows clients prior to being dispatched to the UNIX/Linux print spooler.
71         </para>
72
73         <para>
74 <indexterm><primary>printers</primary></indexterm>
75 <indexterm><primary>meta-service</primary></indexterm>
76 <indexterm><primary>printcap</primary></indexterm>
77 <indexterm><primary>lpstat</primary></indexterm>
78 <indexterm><primary>CUPS API</primary></indexterm>
79 <indexterm><primary>browseable</primary></indexterm>
80         The <literal>printers</literal> meta-service will cause every printer that is either specified in a
81         <literal>printcap</literal> file, via the <command>lpstat</command>,  or via the CUPS API, to be
82         published as a shared print queue. The <literal>printers</literal> stanza in the &smb.conf; file can
83         be set as not browseable. If it is set to be browseable, then it will be visible as if it is a share.
84         That makes no sense given that this meta-service is responsible only for making UNIX system printers
85         available as Windows print queues. If a <literal>comment</literal> parameter is specified, the value
86         of it will be displayed as part of the printer name in Windows Explorer browse lists.
87         </para>
88
89         <para>
90         <indexterm><primary>stanza</primary></indexterm>
91         Each section of the &smb.conf; file that specifies a share, or a meta-service, is called a stanza.
92         The <literal>global</literal> stanza specifies settings that affect all the other stanzas in the
93         &smb.conf; file. Configuration parameters are documented in the &smb.conf; man page. Some parameters
94         can be used only in the <literal>global</literal> stanza, some only in share or meta-service stanzas,
95         and some can be used globally or just within a share or meta-service stanza.
96         </para>
97
98         <para>
99         <indexterm><primary>minimal</primary><secondary>configuration</secondary></indexterm>
100         <link linkend="smbconfminimal">A minimal smb.conf</link> contains a very minimal &smb.conf;.
101         <indexterm><primary>minimal configuration</primary></indexterm>
102         </para>
103
104         <example id="smbconfminimal">
105                 <title>A minimal smb.conf</title>
106                 <smbconfblock>
107
108                 <smbconfsection name="[global]"/>
109                 <smbconfoption name="workgroup">WKG</smbconfoption>
110                 <smbconfoption name="netbios name">MYNAME</smbconfoption>
111                 <smbconfsection name="[share1]"/>
112                 <smbconfoption name="path">/tmp</smbconfoption>
113
114                 <smbconfsection name="[share2]"/>
115                 <smbconfoption name="path">/my_shared_folder</smbconfoption>
116                 <smbconfoption name="comment">Some random files</smbconfoption>
117         </smbconfblock>
118         </example>
119
120 </sect2>
121
122 <sect2 id="tdbdocs">
123         <title>TDB Database File Information</title>
124
125         <para>
126         This section contains brief descriptions of the databases that are used by Samba-3.
127         </para>
128
129         <para>
130 <indexterm><primary>tdb file locations</primary></indexterm>
131         The directory in which Samba stores the tdb files is determined by compile-time directives. Samba-3 stores
132         tdb files in two locations. The best way to determine these locations is to execute the following
133         command:
134 <screen>
135 &rootprompt; smbd -b | grep PRIVATE_DIR
136    PRIVATE_DIR: /etc/samba/private
137 </screen>
138         This means that the confidential tdb files are stored in the <filename>/etc/samba/private</filename>
139         directory. Samba-3 also uses a number of tdb files that contain more mundane data. The location of
140         these files can be found by executing:
141 <screen>
142 &rootprompt; smbd -b | grep LOCKDIR
143    LOCKDIR: /var/lib/samba
144 </screen>
145         Therefore the remaining control files will, in the example shown, be stored in the
146         <filename>/var/lib/samba</filename> directory.
147         </para>
148
149         <para>
150 <indexterm><primary>tdb file descriptions</primary></indexterm>
151         The persistent tdb files are described in <link linkend="tdbpermfiledesc">the Persistent TDB File
152         Descriptions table</link>. All persistent tdb files should be regularly backed up. Use the
153         <command>tdbbackup</command> utility to backup the tdb files. All persistent tdb files must be
154         preserved during machine migrations, updates and upgrades.
155         </para>
156
157         <para>
158         The temporary tdb files do not need to be backed up, nor do they need to be preseved across machine
159         migrations, updates or upgrades. The temporary tdb files are described in <link linkend="tdbtempfiledesc">
160         the Temporary TDB File Descriptions</link>.
161         </para>
162
163         <table frame='all' id="tdbpermfiledesc"><title>Persistent TDB File Descriptions</title>
164         <tgroup cols='2'>
165                         <colspec align="left"/>
166                         <colspec align="justify" colwidth="1*"/>
167                         <colspec align="left"/>
168                 <thead>
169                 <row>
170                         <entry align="left">Name</entry>
171                         <entry align="justify">Description</entry>
172                 </row>
173                 </thead>
174                 <tbody>
175                 <row>
176                         <entry>account_policy</entry>
177                         <entry><para>User policy settings.</para></entry>
178                 </row>
179                 <row>
180                         <entry>group_mapping</entry>
181                         <entry><para>Mapping table from Windows groups/SID to UNIX groups.</para></entry>
182                 </row>
183                 <row>
184                         <entry>ntdrivers</entry>
185                         <entry><para>Stores per-printer driver information.</para></entry>
186                 </row>
187                 <row>
188                         <entry>ntforms</entry>
189                         <entry><para>Stores per-printer forms information.</para></entry>
190                 </row>
191                 <row>
192                         <entry>ntprinters</entry>
193                         <entry><para>Stores the per-printer devmode configuration settings.</para></entry>
194                 </row>
195                 <row>
196                         <entry>passdb</entry>
197                         <entry><para>
198                                 Exists only when the tdbsam passwd backend is used. This file stores the
199                                 SambaSAMAccount information. Note: This file requires that user POSIX account information is
200                                 availble from either the /etc/passwd file, or from an alternative system source.
201                         </para></entry>
202                 </row>
203                 <row>
204                         <entry>registry</entry>
205                         <entry><para>
206                                 Read-only Samba registry skeleton that provides support for exporting various database tables
207                                 via the winreg RPCs.
208                         </para></entry>
209                 </row>
210                 <row>
211                         <entry>secrets</entry>
212                         <entry><para>
213                                 This file stores the Workgroup/Domain/Machine SID, the LDAP directory update password, and
214                                 a further collection of critical environmental data that is necessary for Samba to operate
215                                 correctly. This file contains very sensitive information that must be protected. It is stored
216                                 in the PRIVARE_DIR directory.
217                         </para></entry>
218                 </row>
219                 <row>
220                         <entry>share_info</entry>
221                         <entry><para>Stores per-share ACL information.</para></entry>
222                 </row>
223                 <row>
224                         <entry>winbindd_idmap</entry>
225                         <entry><para>New ID map table from SIDS to UNIX UIDs/GIDs.</para></entry>
226                 </row>
227                 </tbody>
228         </tgroup>
229         </table>
230
231         <table frame='all' id="tdbtempfiledesc"><title>Temporary TDB File Descriptions</title>
232         <tgroup cols='3'>
233                         <colspec align="left"/>
234                         <colspec align="justify" colwidth="1*"/>
235                         <colspec align="left"/>
236                 <thead>
237                 <row>
238                         <entry align="left">Name</entry>
239                         <entry align="justify">Description</entry>
240                         <entry align="center">Backup</entry>
241                 </row>
242                 </thead>
243                 <tbody>
244                 <row>
245                         <entry>brlock</entry>
246                         <entry><para>Byte-range locking information.</para></entry>
247                         <entry>No</entry>
248                 </row>
249                 <row>
250                         <entry>connections</entry>
251                         <entry><para>A temporary cache for current connection information.</para></entry>
252                         <entry>no</entry>
253                 </row>
254                 <row>
255                         <entry>gencache</entry>
256                         <entry><para>Generic caching database for dead WINS servers and trusted domain data.</para></entry>
257                         <entry>no</entry>
258                 </row>
259                 <row>
260                         <entry>login_cache</entry>
261                         <entry><para>A temporary cache for login information.</para></entry>
262                         <entry>no</entry>
263                 </row>
264                 <row>
265                         <entry>messages</entry>
266                         <entry><para>Temporary storage of messages being processed by smbd.</para></entry>
267                         <entry>no</entry>
268                 </row>
269                 <row>
270                         <entry>netsamlogon_cache</entry>
271                         <entry><para>Packets received for which no process is listening.</para></entry>
272                         <entry>no</entry>
273                 </row>
274                 <row>
275                         <entry>printing/*.tdb</entry>
276                         <entry><para>Cached output from lpq command created on a per-print-service basis.</para></entry>
277                         <entry>no</entry>
278                 </row>
279                 <row>
280                         <entry>schannel_store</entry>
281                         <entry><para>
282                                 A confidential file, stored in the PRIVATE_DIR, containing crytographic connection
283                                 information so that clients that have temporarily disconnected can reconnect without
284                                 needing to renegotiate the connection setup process.
285                         </para></entry>
286                         <entry>no</entry>
287                 </row>
288                 <row>
289                         <entry>sessionid</entry>
290                         <entry><para>Temporary cache for miscellaneous session information.</para></entry>
291                         <entry>no</entry>
292                 </row>
293                 <row>
294                         <entry>unexpected</entry>
295                         <entry><para>Stores packets received for which no process is actively listening.</para></entry>
296                         <entry>no</entry>
297                 </row>
298                 <row>
299                         <entry>winbindd_cache</entry>
300                         <entry><para>Cache of Identity information received from an NT4 domain or from ADS.</para></entry>
301                         <entry>yes</entry>
302                 </row>
303                 </tbody>
304         </tgroup>
305         </table>
306
307 </sect2>
308
309 <sect2>
310         <title>Starting Samba</title>
311
312         <para>
313         <indexterm><primary>daemon</primary></indexterm>
314         Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services.
315         An example of a service is the Apache Web server for which the daemon is called <command>httpd</command>. In the case of Samba there
316         are three daemons, two of which are needed as a minimum.
317         </para>
318
319         <para>
320         The Samba server is made up of the following daemons:
321         </para>
322
323         <variablelist>
324                 <varlistentry><term>nmbd</term>
325                         <listitem><para>
326                         <indexterm><primary>smbd</primary></indexterm>
327                         <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm>
328                         This daemon handles all name registration and resolution requests. It is the primary vehicle involved
329                         in network browsing. It handles all UDP-based protocols. The <command>nmbd</command> daemon should
330                         be the first command started as part of the Samba startup process.
331                         </para></listitem>
332                 </varlistentry>
333
334                 <varlistentry><term>smbd</term>
335                         <listitem><para>
336                         <indexterm><primary>nmbd</primary></indexterm>
337                         <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm>
338                         This daemon handles all TCP/IP-based connection services for file- and print-based operations. It also
339                         manages local authentication. It should be started immediately following the startup of <command>nmbd</command>.
340                         </para></listitem>
341                 </varlistentry>
342
343                 <varlistentry><term>winbindd</term>
344                         <listitem><para>
345                         <indexterm><primary>winbindd</primary></indexterm>
346                         <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm>
347                         This daemon should be started when Samba is a member of a Windows NT4 or ADS domain. It is also needed when
348                         Samba has trust relationships with another domain. The <command>winbindd</command> daemon will check the
349                         &smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter>
350                         parameters. If they are are found, <command>winbindd</command> will use the values specified for
351                         for UID and GID allocation. If these parameters are not specified, <command>winbindd</command>
352                         will start but it will not be able to allocate UIDs or GIDs.
353                         </para></listitem>
354                 </varlistentry>
355         </variablelist>
356
357         <para>
358         <indexterm><primary>startup</primary><secondary>process</secondary></indexterm>
359         When Samba has been packaged by an operating system vendor, the startup process is typically a custom feature of its
360         integration into the platform as a whole. Please refer to your operating system platform administration manuals for
361         specific information pertaining to correct management of Samba startup.
362         </para>
363
364 </sect2>
365         
366 <sect2>
367         <title>Example Configuration</title>
368         
369         <para>
370         <indexterm><primary>examples</primary></indexterm>
371         <indexterm><primary>source code</primary></indexterm>
372         <indexterm><primary>distribution</primary></indexterm>
373         <indexterm><primary>tarball</primary></indexterm>
374         <indexterm><primary>package</primary></indexterm>
375         There are sample configuration files in the examples subdirectory in the source code distribution tarball
376         package. It is suggested you read them carefully so you can see how the options go together in practice. See
377         the man page for all the options.  It might be worthwhile to start out with the
378         <filename>smb.conf.default</filename> configuration file and adapt it to your needs. It contains plenty of comments.
379         </para>
380
381         <para>
382         <indexterm><primary>simplest</primary><secondary>configuration</secondary></indexterm>
383         The simplest useful configuration file would contain something like that shown in
384         <link linkend="simple-example">Another simple smb.conf File</link>.
385         <indexterm><primary>simple configuration</primary></indexterm>
386         </para>
387
388 <example id="simple-example">
389 <title>Another simple smb.conf File</title>
390 <smbconfblock>
391 <smbconfsection name="[global]"/>
392 <smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
393
394 <smbconfsection name="[homes]"/>
395 <smbconfoption name="guest ok">no</smbconfoption>
396 <smbconfoption name="read only">no</smbconfoption>
397 </smbconfblock>
398 </example>
399         
400         <para>
401         <indexterm><primary>connections</primary></indexterm>
402         <indexterm><primary>account</primary></indexterm>
403         <indexterm><primary>login name</primary></indexterm>
404         <indexterm><primary>service name</primary></indexterm>
405         This will allow connections by anyone with an account on the server, using either
406         their login name or <smbconfsection name="homes"/> as the service name.
407         (Note: The workgroup that Samba should appear in must also be set. The default
408         workgroup name is WORKGROUP.)
409         </para>
410         
411         <para>
412         <indexterm><primary>smbd</primary></indexterm>
413         Make sure you put the &smb.conf; file in the correct place. Note, the correct location of this file
414         depends on how the binary files were built. You can discover the correct location by executing from
415         the directory that contains the <command>smbd</command> command file:
416 <screen>
417 &rootprompt; smbd -b | grep smb.conf
418 </screen>
419         </para>
420
421         <para>
422         <indexterm><primary>security</primary><secondary>settings</secondary></indexterm>
423         For more information about security settings for the <smbconfsection name="[homes]"/> share, please refer to 
424         <link linkend="securing-samba">Securing Samba</link>.
425         </para>
426
427 <sect3>
428         <title>Test Your Config File with <command>testparm</command></title>
429
430         <para>
431         <indexterm><primary>validate</primary></indexterm>
432         <indexterm><primary>testparm</primary></indexterm>
433         <indexterm><primary>misconfigurations</primary></indexterm>
434         It's important to validate the contents of the &smb.conf; file using the &testparm; program.
435         If testparm runs correctly, it will list the loaded services. If not, it will give an error message.
436         Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command: 
437         <screen>
438         &rootprompt; testparm /etc/samba/smb.conf
439         </screen>
440         Testparm will parse your configuration file and report any unknown parameters or incorrect syntax.
441         It also performs a check for common misconfigurations and will issue a warning if one is found.
442         </para>
443
444         <para>
445         Always run testparm again whenever the &smb.conf; file is changed!
446         </para>
447
448         <para>
449         <indexterm><primary>smbd</primary></indexterm>
450         <indexterm><primary>nmbd</primary></indexterm>
451         <indexterm><primary>winbindd</primary></indexterm>
452         <indexterm><primary>configuration</primary><secondary>documentation</secondary></indexterm>
453         The &smb.conf; file is constantly checked by the Samba daemons <command>smbd</command> and every instance of
454         itself that it spawns, <command>nmbd</command> and <command>winbindd</command>. It is good practice to
455         keep this file as small as possible. Many administrators prefer to document Samba configuration settings
456         and thus the need to keep this file small goes against good documentation wisdom. One solution that may
457         be adopted is to do all documentation and configuration in a file that has another name, such as
458         <filename>smb.conf.master</filename>. The <command>testparm</command> utility can be used to generate a
459         fully optimized &smb.conf; file from this master configuration and documtenation file as shown here:
460 <screen>
461 &rootprompt; testparm -s smb.conf.master > smb.conf
462 </screen>
463         This administrative method makes it possible to maintain detailed configuration change records while at
464         the same time keeping the working &smb.conf; file size to the minimum necessary.
465         </para>
466
467 </sect3>
468 </sect2>
469
470 <sect2>
471         <title>SWAT</title>
472
473         <para>
474         <indexterm><primary>swat</primary></indexterm>
475         SWAT is a Web-based interface that can be used to facilitate the configuration of Samba.  SWAT might not
476         be available in the Samba package that shipped with your platform, but in a separate package. If it is
477         necesaary to built SWAT please read the SWAT man page regarding compilation, installation, and
478         configuration of SWAT from the source code.
479         </para>
480
481         <para>
482         To launch SWAT, just run your favorite Web browser and point it to
483         <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>.
484         Replace <replaceable>localhost</replaceable> with the name of the computer on which
485         Samba is running if that is a different computer than your browser.
486         </para>
487
488         <para>
489         SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote
490         machine leaves your connection open to password sniffing because passwords will be sent over the wire in the clear. 
491         </para>
492
493         <para>
494         More information about SWAT can be found in <link linkend="SWAT">The Samba Web Administration Tool</link>.
495         </para>
496
497 </sect2>
498
499 </sect1>
500
501 <sect1>
502         <title>List Shares Available on the Server</title>
503
504         <para>
505         To list shares that are available from the configured Samba server, execute the
506         following command:
507         </para>
508
509 <para><screen>
510 &prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput>
511 </screen></para>
512
513         <para>
514         You should see a list of shares available on your server. If you do not, then
515         something is incorrectly configured. This method can also be used to see what shares 
516         are available on other SMB servers, such as Windows 2000.
517         </para>
518
519         <para>
520         If you choose user-level security, you may find that Samba requests a password
521         before it will list the shares. See the <command>smbclient</command> man page for details.
522         You can force it to list the shares without a password by adding the option
523         <option>-N</option> to the command line. 
524         </para>
525 </sect1>
526
527 <sect1>
528         <title>Connect with a UNIX Client</title>
529         
530         <para>
531         Enter the following command:
532 <screen>
533 &prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput>
534 </screen></para>
535         
536         <para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd;
537         has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf;
538         file. Try your username if you just have a <smbconfsection name="[homes]"/> section in the &smb.conf; file.</para>
539
540         <para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name
541         is <replaceable>fred</replaceable>, you would type:</para>
542
543 <para><screen>
544 &prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput>
545 </screen></para>
546 </sect1>
547
548 <sect1>
549         <title>Connect from a Remote SMB Client</title>
550
551         <para>
552         Now that Samba is working correctly locally, you can try to access it from other clients. Within a few
553         minutes, the Samba host should be listed in the Network Neighborhood on all Windows clients of its subnet.
554         Try browsing the server from another client or "mounting" it.
555         </para>
556
557         <para>
558         Mounting disks from a DOS, Windows, or OS/2 client can be done by running a command such as:
559 <screen>
560 &dosprompt;<userinput>net use m: \\servername\service</userinput>
561 </screen>
562         Where the drive letter m: is any available drive letter. It is important to double-check that the
563         service (share) name that you used does actually exist.
564         </para>
565
566         <para>
567         Try printing, for example,
568 <screen>
569 &dosprompt;<userinput>net use lpt1:     \\servername\spoolservice</userinput>
570 </screen>
571         The <literal>spoolservice</literal> is the name of the printer (actually the print queue) on the target
572         server. This will permit all print jobs that are captured by the lpt1: port on the Windows client to
573         be sent to the printer that owns the spoolservice that has been specified.
574         </para>
575
576 <para>
577 <screen>&dosprompt;<userinput>print filename</userinput>
578 </screen></para>
579
580         <sect2>
581         <title>What If Things Don't Work?</title>
582         
583         <para>
584         You might want to read <link linkend="diagnosis">The Samba Checklist</link>.  If you are still
585         stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link>.  Samba has
586         been successfully installed at thousands of sites worldwide.  It is unlikely that your particular problem is
587         unique, so it might be productive to perform an Internet search to see if someone else has encountered your
588         problem and has found a way to overcome it.
589         </para>
590
591         <para>
592         If you are new to Samba, and particularly if you are new to Windows networking, or to UNIX/Linux,
593         the book <quote>Samba-3 by Example</quote> will help you to create a validated network environment.
594         Simply choose from the first five chapters the network design that most closely matches site needs,
595         then follow the simple step-by-step procedure to deploy it. Later, when you have a working network
596         you may well want to refer back to this book for further insight into opportunities for improvement.
597         </para>
598
599         </sect2>
600
601         <sect2>
602         <title>Still Stuck?</title>
603
604         <para>
605         The best advice under the stress of abject frustration is to cool down! That may be challenging
606         of itself, but while you are angry or annoyed your ability to seek out a solution is somewhat
607         undermined. A cool head clears the way to finding the answer you are looking for. Just remember,
608         every problem has a solution &smbmdash; there is a good chance that someone else has found it
609         even though you can't right now. That will change with time, patience and learning.
610         </para>
611
612         <para>
613         Now that you have cooled down a bit, please refer to <link linkend="diagnosis">the Samba Checklist</link>
614         for a process that can be followed to identify the cause of your problem.
615         </para>
616
617         </sect2>
618
619 </sect1>
620
621 <sect1>
622 <title>Common Errors</title>
623
624 <para>
625 The following questions and issues are raised repeatedly on the Samba mailing list.
626 </para>
627
628 <sect2>
629         <title>Large Number of smbd Processes</title>
630
631         <para>
632         Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon,
633         &smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with domain controllers.
634         </para>
635
636         <para>
637         If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of
638          &nmbd; running on your system. If it is running as a WINS server, then there will be
639         two instances &smbmdash; one to handle the WINS requests.
640         </para>
641
642         <para>
643         &smbd; handles all connection requests. It spawns a new process for each client
644         connection made. That is why you may see so many of them, one per client connection.
645         </para>
646
647         <para>
648         &winbindd; will run as one or two daemons, depending on whether or not it is being
649         run in <emphasis>split mode</emphasis> (in which case there will be two instances).
650         </para>
651
652         </sect2>
653
654         <sect2>
655                 <title>Error Message: open_oplock_ipc</title>
656
657         <para>
658         An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to
659         get local UDP socket for address 100007f. Error was Cannot assign requested.</quote>
660         </para>
661
662         <para>
663         Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback
664         device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>.
665         Read your OS documentation for details on how to configure the loopback on your system.
666         </para>
667
668         </sect2>
669
670         <sect2>
671                 <title><quote><errorname>The network name cannot be found</errorname></quote></title>
672
673                 <para>
674                 This error can be caused by one of these misconfigurations:
675                 </para>
676
677                 <itemizedlist>
678                         <listitem><para>You specified a nonexisting path
679                         for the share in &smb.conf;.</para></listitem>
680
681                         <listitem><para>The user you are trying to access the share with does not 
682                         have sufficient permissions to access the path for
683                         the share. Both read (r) and access (x) should be possible.</para></listitem>
684
685                         <listitem><para>The share you are trying to access does not exist.</para></listitem>
686         </itemizedlist>
687
688         </sect2>
689 </sect1>
690
691 </chapter>