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">
10 <!-- Isn't some of this written by others as well? -->
14 <title>How to Install and Test SAMBA</title>
17 <title>Obtaining and Installing Samba</title>
20 Binary packages of Samba are included in almost any Linux or
21 UNIX distribution. There are also some packages available at
22 <ulink url="http://samba.org/">the Samba home-page</ulink>. Refer to
23 the manual of your operating system for details on installing packages
24 for your specific operating system.
27 <para>If you need to compile Samba from source, check
28 <link linkend="compiling">How to compile Samba.</link>
34 <title>Configuring Samba (smb.conf)</title>
37 Samba's configuration is stored in the &smb.conf; file, which
38 usually resides in <filename>/etc/samba/smb.conf</filename>
39 or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either
40 edit this file yourself or do it using one of the many graphical
41 tools that are available, such as the Web-based interface SWAT, that
42 is included with Samba.
46 <title>Configuration file syntax</title>
48 <para>The &smb.conf; file uses the same syntax as the various old
49 .ini files in Windows 3.1: Each file consists of various sections,
50 which are started by putting the section name between brackets ([])
51 on a new line. Each contains zero or more key/value-pairs separated by an
52 equality sign (=). The file is just a plain-text file, so you can
53 open and edit it with your favorite editing tool.</para>
55 <para>Each section in the &smb.conf; file represents a share
56 on the Samba server. The section <quote>global</quote> is special, since it
57 contains settings that apply to the whole Samba server and not
58 to one share in particular.</para>
60 <para><link linkend="smbconfminimal">Following example</link> contains a very minimal &smb.conf;.
61 <indexterm><primary>minimal configuration</primary></indexterm>
64 <example id="smbconfminimal">
65 <title>A minimal smb.conf</title>
68 <smbconfsection name="[global]"/>
69 <smbconfoption name="workgroup">WKG</smbconfoption>
70 <smbconfoption name="netbios name">MYNAME</smbconfoption>
71 <smbconfsection name="[share1]"/>
72 <smbconfoption name="path">/tmp</smbconfoption>
74 <smbconfsection name="[share2]"/>
75 <smbconfoption name="path">/my_shared_folder</smbconfoption>
76 <smbconfoption name="comment">Some random files</smbconfoption>
83 <title>Starting Samba</title>
86 Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services.
87 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
88 are three daemons, two of which are needed as a minimum.
92 The Samba server is made up of the following daemons:
96 <varlistentry><term>nmbd</term>
98 <indexterm><primary>smbd</primary></indexterm>
99 <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm>
100 This daemon handles all name registration and resolution requests. It is the primary vehicle involved
101 in network browsing. It handles all UDP based protocols. The <command>nmbd</command> daemon should
102 be the first command started as part of the Samba start-up process.
106 <varlistentry><term>smbd</term>
108 <indexterm><primary>nmbd</primary></indexterm>
109 <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm>
110 This daemon handles all TCP/IP based connection services for file and print based operations. It also
111 manages local authentication. It should be started immediately following the start-up of <command>nmbd</command>.
115 <varlistentry><term>winbindd</term>
117 <indexterm><primary>winbindd</primary></indexterm>
118 <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm>
119 This daemon should be started when Samba is a member of a Windows NT4 or ADS Domain. It is also needed when
120 Samba has trust relationships with another Domain. The <command>winbindd</command> daemon will check the
121 &smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter>
122 parameters. If they are not found <command>winbindd</command> will bail-out and refuse to start.
128 When Samba has been packaged by an operating system vendor the start-up process is typically a custom feature of its
129 integration into the platform as a whole. Please refer to your operating system platform administration manuals for
130 specific information pertaining to correct management of Samba start-up.
136 <title>Example Configuration</title>
139 There are sample configuration files in the examples subdirectory in the
140 distribution. It is suggested you read them carefully so you can see how the options
141 go together in practice. See the man page for all the options.
142 It might be worthwhile to start out with the smb.conf.default
143 configuration file and adapt it to your needs. It contains plenty of
148 The simplest useful configuration file would contain something like shown in
149 <link linkend="simple-example">the next example</link>.
153 <indexterm><primary>simple configuration</primary></indexterm>
154 <example id="simple-example">
155 <title>Another simple smb.conf File</title>
157 <smbconfsection name="[global]"/>
158 <smbconfoption name="workgroup">&example.workgroup;</smbconfoption>
160 <smbconfsection name="[homes]"/>
161 <smbconfoption name="guest ok">no</smbconfoption>
162 <smbconfoption name="read only">no</smbconfoption>
168 This will allow connections by anyone with an account on the server, using either
169 their login name or <smbconfsection name="homes"/> as the service name.
170 (Note: The workgroup that Samba should appear in must also be set. The default
171 workgroup name is WORKGROUP.)
175 Make sure you put the &smb.conf; file in the correct place.
179 For more information about security settings for the
180 <smbconfsection name="[homes]"/> share please refer to
181 <link linkend="securing-samba">Securing Samba</link> chapter.
185 <title>Test Your Config File with <command>testparm</command></title>
188 It's important to validate the contents of the &smb.conf; file using the &testparm; program.
189 If testparm runs correctly, it will list the loaded services. If not, it will give an error message.
190 Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command:
194 &rootprompt; testparm /etc/samba/smb.conf
197 <para>Testparm will parse your configuration file and report
198 any unknown parameters or incorrect syntax. </para>
203 Always run testparm again whenever the &smb.conf; file is changed!
213 <indexterm><primary>swat</primary></indexterm>
214 SWAT is a Web-based interface that can be used to facilitate the configuration of Samba.
215 SWAT might not be available in the Samba package that shipped with your platform,
216 but in a separate package. Please read the SWAT man page
217 on compiling, installing and configuring SWAT from source.
221 To launch SWAT, just run your favorite Web browser and point it to
222 <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>.
223 Replace <replaceable>localhost</replaceable> with the name of the computer on which
224 Samba is running if that is a different computer than your browser.
228 SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote
229 machine leaves your connection open to password sniffing as passwords will be sent over the wire in the clear.
232 <para>More information about SWAT can be found in <link linkend="SWAT">corresponding chapter</link>.</para>
239 <title>List Shares Available on the Server</title>
242 To list shares that are available from the configured Samba server execute the
247 &prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput>
250 <para>You should see a list of shares available on your server. If you do not, then
251 something is incorrectly configured. This method can also be used to see what shares
252 are available on other SMB servers, such as Windows 2000.</para>
254 <para>If you choose user-level security you may find that Samba requests a password
255 before it will list the shares. See the <command>smbclient</command> man page for details.
256 You can force it to list the shares without a password by adding the option
257 <option>-N</option> to the command line. </para>
261 <title>Connect with a UNIX Client</title>
264 Enter the following command:
266 &prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput>
269 <para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd;
270 has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf;
271 file. Try your user name if you just have a <smbconfsection name="[homes]"/> section in the &smb.conf; file.</para>
273 <para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name
274 is <replaceable>fred</replaceable>, you would type:</para>
277 &prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput>
282 <title>Connect from a Remote SMB Client</title>
284 <para>Now that Samba is working correctly locally, you can try to
285 access it from other clients. Within a few minutes, the Samba host
286 should be listed in the Network Neighborhood on all Windows
287 clients of its subnet. Try browsing the server from another client
288 or 'mounting' it.</para>
290 <para>Mounting disks from a DOS, Windows or OS/2 client can be done by running a command such as:</para>
293 &dosprompt;<userinput>net use d: \\servername\service</userinput>
296 <para>Try printing, e.g.</para>
300 &dosprompt;<userinput>net use lpt1: \\servername\spoolservice</userinput>
304 <screen>&dosprompt;<userinput>print filename</userinput>
309 <title>What If Things Don't Work?</title>
311 <para>You might want to read <link linkend="diagnosis">The Samba Checklist</link>.
312 If you are still stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link> chapter.
313 Samba has been successfully installed at thousands of sites worldwide.
314 It is unlikely that your particular problem is unique, so it might be
315 productive to perform an Internet search to see if someone else has encountered
316 your problem and has found a way to overcome it.</para>
321 <title>Common Errors</title>
324 The following questions and issues are raised repeatedly on the Samba mailing list.
328 <title>Large Number of smbd Processes</title>
331 Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon,
332 &smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with Domain Controllers.
336 If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of
337 &nmbd; running on your system. If it is running as a WINS server then there will be
338 two instances &smbmdash; one to handle the WINS requests.
342 &smbd; handles all connection requests. It spawns a new process for each client
343 connection made. That is why you may see so many of them, one per client connection.
347 &winbindd; will run as one or two daemons, depending on whether or not it is being
348 run in <emphasis>split mode</emphasis> (in which case there will be two instances).
354 <title>Error Message: open_oplock_ipc</title>
356 <para>An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to get local UDP socket
357 for address 100007f. Error was Cannot assign requested.</quote></para>
359 <para>Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback
360 device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>.
361 Read your OS documentation for details on how to configure the loopback on your system.</para>
366 <title><quote><errorname>The network name cannot be found</errorname></quote></title>
369 This error can be caused by one of these mis-configurations:
373 <listitem><para>You specified an non-existing path
374 for the share in &smb.conf;.</para></listitem>
376 <listitem><para>The user you are trying to access the share with does not
377 have sufficient permissions to access the path for
378 the share. Both read (r) and access (x) should be possible.</para></listitem>
380 <listitem><para>The share you are trying to access does not exist.</para></listitem>