A lot of syntax updates, consistency when using certain tags and converting ASCII...
[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 Site that is running Samba on an AIX box. They are sharing out about 2 terabytes using samba.
216 Samba was installed using smitty and the binaries. We seem to be experiencing a memory problem
217 with this box.  When I do a <command>svmon -Pu</command> the monitoring program shows that &smbd; has several
218 processes of smbd running:
219 </para>
220
221 <para>
222 Is samba suppose to start this many different smbd processes?  Or does it run as one smbd process?  Also
223 is it normal for it to be taking up this much memory?
224 </para>
225
226 <para>
227 <screen>
228 Inuse * 4096 = amount of memory being used by this process
229
230      Pid Command        Inuse      Pin     Pgsp  Virtual   64-bit    Mthrd
231    20950 smbd           33098     1906      181     5017        N        N
232    22262 smbd            9104     1906      5410
233    21060 smbd            9048     1906      181     5479        N        N
234    25972 smbd            8678     1906      181     5109        N        N
235    24524 smbd            8674     1906      181     5105        N        N
236    19262 smbd            8582     1906      181     5013        N        N
237    20722 smbd            8572     1906      181     5003        N        N
238    21454 smbd            8572     1906      181     5003        N        N
239    28946 smbd            8567     1906      181     4996        N        N
240    24076 smbd            8566     1906      181     4996        N        N
241    20138 smbd            8566     1906      181     4996        N        N
242    17608 smbd            8565     1906      181     4996        N        N
243    21820 smbd            8565     1906      181     4996        N        N
244    26940 smbd            8565     1906      181     4996        N        N
245    19884 smbd            8565     1906      181     4996        N        N
246     9912 smbd            8565     1906      181     4996        N        N
247    25800 smbd            8564     1906      181     4995        N        N
248    20452 smbd            8564     1906      181     4995        N        N
249    18592 smbd            8562     1906      181     4993        N        N
250    28216 smbd            8521     1906      181     4954        N        N
251    19110 smbd            8404     1906      181     4862        N        N
252
253    Total memory used:  841,592,832 bytes
254 </screen>
255 </para>
256
257
258 <para>
259 <emphasis>ANSWER:</emphasis> Samba consists on three core programs:
260 &nmbd;, &smbd;, &winbindd;. &nmbd; is the name server message daemon,
261 &smbd; is the server message daemon, &winbindd; is the daemon that
262 handles communication with Domain Controllers.
263 </para>
264
265 <para>
266 If your system is NOT running as a WINS server, then there will be one (1) single instance of
267  &nmbd; running on your system. If it is running as a WINS server then there will be
268 two (2) instances - one to handle the WINS requests.
269 </para>
270
271 <para>
272 &smbd; handles ALL connection requests and then spawns a new process for each client
273 connection made. That is why you are seeing so many of them, one (1) per client connection.
274 </para>
275
276 <para>
277 &winbindd; will run as one or two daemons, depending on whether or not it is being
278 run in "split mode" (in which case there will be two instances).
279 </para>
280
281 </sect2>
282 </sect1>
283
284 </chapter>