Add some more common errors
[sfrench/samba-autobuild/.git] / docs / docbook / projdoc / UNIX_INSTALL.xml
1 <chapter id="install">
2 <chapterinfo>
3         &author.tridge;
4         &author.jelmer;
5         &author.jht;
6         <author><firstname>Karl</firstname><surname>Auer</surname></author>
7         <!-- Isn't some of this written by others as well? -->
8
9 </chapterinfo>
10
11 <title>How to Install and Test SAMBA</title>
12
13 <sect1>
14         <title>Obtaining and installing samba</title>
15
16         <para>
17         Binary packages of samba are included in almost any Linux or
18         Unix distribution. There are also some packages available at 
19         <ulink url="http://samba.org/">the samba homepage</ulink>.
20         </para>
21
22         <para>If you need to compile samba from source, check the 
23         <link linkend="compiling">appropriate appendix chapter</link>.</para>
24
25         <para>If you have already installed samba, or if your operating system
26         was pre-installed with samba, then you may not need to bother with this
27         chapter. On the other hand, you may want to read this chapter anyhow
28         for information about updating samba.</para>
29
30 </sect1>
31
32 <sect1>
33         <title>Configuring samba (smb.conf)</title>
34
35         <para>
36         Samba's configuration is stored in the &smb.conf; file, 
37         that usually resides in <filename>/etc/samba/smb.conf</filename> 
38         or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either 
39         edit this file yourself or do it using one of the many graphical 
40         tools that are available, such as the web-based interface swat, that 
41         is included with samba.
42         </para>
43         
44 <sect2>
45         <title>Example Configuration</title>
46         
47         <para>
48         There are sample configuration files in the examples subdirectory in the
49         distribution. I suggest you read them carefully so you can see how the options
50         go together in practice. See the man page for all the options.
51         </para>
52
53         <para>
54         The simplest useful configuration file would be something like this:
55         </para>
56
57         <para>
58         <programlisting>
59         [global]
60                 workgroup = MYGROUP
61
62         [homes]
63                 guest ok = no
64                 read only = no
65         </programlisting>
66         </para>
67         
68         <para>
69         This will allow connections by anyone with an account on the server, using either
70         their login name or "<parameter>homes</parameter>" as the service name.
71         (Note that the workgroup that Samba must also be set.)
72         </para>
73         
74         <para>
75         Make sure you put the <filename>smb.conf</filename> file in the same place 
76         you specified in the<filename>Makefile</filename> (the default is to 
77         look for it in <filename>/usr/local/samba/lib/</filename>).
78         </para>
79
80         <para>
81         For more information about security settings for the 
82         <parameter>[homes]</parameter> share please refer to the chapter 
83         <link linkend="securing-samba">Securing Samba</link>.
84         </para>
85
86 <sect3>
87         <title>Test your config file with <command>testparm</command></title>
88
89         <para>
90         It's important that you test the validity of your <filename>smb.conf</filename>
91         file using the &testparm; program. If testparm runs OK
92         then it will list the loaded services. If not it will give an error message.
93         </para>
94
95         <para>
96         Make sure it runs OK and that the services look reasonable before proceeding.
97         </para>
98
99         <para>
100         Always run testparm again when you change &smb.conf;!
101         </para>
102
103 </sect3>
104 </sect2>
105
106 <sect2>
107         <title>SWAT</title>
108
109         <para>
110         SWAT is a web-based interface that helps you configure samba. 
111         SWAT might not be available in the samba package on your platform, 
112         but in a separate package. Please read the swat manpage 
113         on compiling, installing and configuring swat from source.
114         </para>
115
116         <para>
117         To launch SWAT just run your favorite web browser and 
118         point it at <ulink url="http://localhost:901/">http://localhost:901/</ulink>. Replace
119         <replaceable>localhost</replaceable>
120         with the name of the computer you are running samba on if you 
121         are running samba on a different computer than your browser.
122         </para>
123
124         <para>
125         Note that you can attach to SWAT from any IP connected 
126         machine but connecting from a remote machine leaves your 
127         connection open to password sniffing as passwords will be sent 
128         in the clear over the wire. 
129         </para>
130 </sect2>
131 </sect1>
132
133 <sect1>
134         <title>Try listing the shares available on your 
135         server</title>
136
137         <para><prompt>$ </prompt><userinput>smbclient -L 
138         <replaceable>yourhostname</replaceable></userinput></para>
139
140         <para>You should get back a list of shares available on 
141         your server. If you don't then something is incorrectly setup. 
142         Note that this method can also be used to see what shares 
143         are available on other LanManager clients (such as WfWg).</para>
144
145         <para>If you choose user level security then you may find 
146         that Samba requests a password before it will list the shares. 
147         See the <command>smbclient</command> man page for details. (you 
148         can force it to list the shares without a password by
149         adding the option -U% to the command line. This will not work 
150         with non-Samba servers)</para>
151 </sect1>
152
153 <sect1>
154         <title>Try connecting with the unix client</title>
155         
156         <para><prompt>$ </prompt><userinput>smbclient <replaceable>
157         //yourhostname/aservice</replaceable></userinput></para>
158         
159         <para>Typically the <replaceable>yourhostname</replaceable> 
160         would be the name of the host where you installed &smbd;. 
161         The <replaceable>aservice</replaceable> is 
162         any service you have defined in the &smb.conf;
163         file. Try your user name if you just have a <parameter>[homes]</parameter>
164         section
165         in &smb.conf;.</para>
166
167         <para>For example if your unix host is <replaceable>bambi</replaceable>
168         and your login name is <replaceable>fred</replaceable> you would type:</para>
169
170         <para><prompt>$ </prompt><userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable>
171         </userinput></para>
172 </sect1>
173
174 <sect1>
175         <title>Try connecting from a DOS, WfWg, Win9x, WinNT, 
176         Win2k, OS/2, etc... client</title>
177         
178         <para>Try mounting disks. eg:</para>
179
180         <para><prompt>C:\WINDOWS\> </prompt><userinput>net use d: \\servername\service
181         </userinput></para>
182
183         <para>Try printing. eg:</para>
184
185         <para><prompt>C:\WINDOWS\> </prompt><userinput>net use lpt1:
186         \\servername\spoolservice</userinput></para>
187
188         <para><prompt>C:\WINDOWS\> </prompt><userinput>print filename
189         </userinput></para>
190 </sect1>
191
192 <sect1>
193         <title>What If Things Don't Work?</title>
194         
195         <para>Then you might read the file chapter 
196         <link linkend="diagnosis">Diagnosis</link> and the 
197         FAQ. If you are still stuck then try to follow 
198         the <link linkend="problems">Analysing and Solving Problems chapter</link>
199         Samba has been successfully installed at thousands of sites worldwide,
200         so maybe someone else has hit your problem and has overcome it. </para>
201
202 </sect1>
203
204 <sect1>
205 <title>Common Errors</title>
206
207 <para>
208 The following questions and issues get raised on the samba mailing list over and over again.
209 </para>
210
211 <sect2>
212 <title>Why are so many smbd processes eating memory?</title>
213
214 <para>
215 <quote>
216 Site that is running Samba on an AIX box. They are sharing out about 2 terabytes using samba.
217 Samba was installed using smitty and the binaries. We seem to be experiencing a memory problem
218 with this box.  When I do a <command>svmon -Pu</command> the monitoring program shows that &smbd; has several
219 processes of smbd running:
220 </quote>
221 </para>
222
223 <para>
224         <quote>
225 Is samba suppose to start this many different smbd processes?  Or does it run as one smbd process?  Also
226 is it normal for it to be taking up this much memory?
227 </quote>
228 </para>
229
230 <para>
231 <screen>
232 Inuse * 4096 = amount of memory being used by this process
233
234      Pid Command        Inuse      Pin     Pgsp  Virtual   64-bit    Mthrd
235    20950 smbd           33098     1906      181     5017        N        N
236    22262 smbd            9104     1906      5410
237    21060 smbd            9048     1906      181     5479        N        N
238    25972 smbd            8678     1906      181     5109        N        N
239    24524 smbd            8674     1906      181     5105        N        N
240    19262 smbd            8582     1906      181     5013        N        N
241    20722 smbd            8572     1906      181     5003        N        N
242    21454 smbd            8572     1906      181     5003        N        N
243    28946 smbd            8567     1906      181     4996        N        N
244    24076 smbd            8566     1906      181     4996        N        N
245    20138 smbd            8566     1906      181     4996        N        N
246    17608 smbd            8565     1906      181     4996        N        N
247    21820 smbd            8565     1906      181     4996        N        N
248    26940 smbd            8565     1906      181     4996        N        N
249    19884 smbd            8565     1906      181     4996        N        N
250     9912 smbd            8565     1906      181     4996        N        N
251    25800 smbd            8564     1906      181     4995        N        N
252    20452 smbd            8564     1906      181     4995        N        N
253    18592 smbd            8562     1906      181     4993        N        N
254    28216 smbd            8521     1906      181     4954        N        N
255    19110 smbd            8404     1906      181     4862        N        N
256
257    Total memory used:  841,592,832 bytes
258 </screen>
259 </para>
260
261
262 <para>
263 Samba consists on three core programs:
264 &nmbd;, &smbd;, &winbindd;. &nmbd; is the name server message daemon,
265 &smbd; is the server message daemon, &winbindd; is the daemon that
266 handles communication with Domain Controllers.
267 </para>
268
269 <para>
270 If your system is NOT running as a WINS server, then there will be one (1) single instance of
271  &nmbd; running on your system. If it is running as a WINS server then there will be
272 two (2) instances - one to handle the WINS requests.
273 </para>
274
275 <para>
276 &smbd; handles ALL connection requests and then spawns a new process for each client
277 connection made. That is why you are seeing so many of them, one (1) per client connection.
278 </para>
279
280 <para>
281 &winbindd; will run as one or two daemons, depending on whether or not it is being
282 run in "split mode" (in which case there will be two instances).
283 </para>
284
285 </sect2>
286
287         <sect2>
288         <title>I'm getting "open_oplock_ipc: Failed to get local UDP socket for address 100007f. Error was Cannot assign requested" in the logs</title>
289     <para>Your loopback device isn't working correctly. Make sure it's running.  </para>
290         </sect2>
291
292 </sect1>
293
294 </chapter>