This paragraph is irrelevent and misleading (needs fix for 2.2 as well)
[kai/samba.git] / docs / docbook / projdoc / UNIX_INSTALL.sgml
1 <chapter id="install">
2
3 <title>How to Install and Test SAMBA</title>
4
5 <sect1>
6         <title>Step 0: Read the man pages</title>
7         
8         <para>The man pages distributed with SAMBA contain 
9         lots of useful info that will help to get you started. 
10         If you don't know how to read man pages then try 
11         something like:</para>
12
13         <para><prompt>$ </prompt><userinput>nroff -man smbd.8 | more
14         </userinput></para>
15         
16         <para>Other sources of information are pointed to 
17         by the Samba web site,<ulink url="http://www.samba.org/">
18         http://www.samba.org</ulink></para>
19 </sect1>
20
21 <sect1>
22         <title>Step 1: Building the Binaries</title>
23         
24         <para>To do this, first run the program <command>./configure
25         </command> in the source directory. This should automatically 
26         configure Samba for your operating system. If you have unusual 
27         needs then you may wish to run</para>
28         
29         <para><prompt>root# </prompt><userinput>./configure --help
30         </userinput></para>
31         
32         <para>first to see what special options you can enable.
33         Then executing</para>
34         
35         <para><prompt>root# </prompt><userinput>make</userinput></para>
36         
37         <para>will create the binaries. Once it's successfully 
38         compiled you can use </para>
39         
40         <para><prompt>root# </prompt><userinput>make install</userinput></para>
41         
42         <para>to install the binaries and manual pages. You can 
43         separately install the binaries and/or man pages using</para>
44         
45         <para><prompt>root# </prompt><userinput>make installbin
46         </userinput></para>
47         
48         <para>and</para>
49         
50         <para><prompt>root# </prompt><userinput>make installman
51         </userinput></para>
52
53         <para>Note that if you are upgrading for a previous version 
54         of Samba you might like to know that the old versions of 
55         the binaries will be renamed with a ".old" extension. You 
56         can go back to the previous version with</para>
57         
58         <para><prompt>root# </prompt><userinput>make revert
59         </userinput></para>
60         
61         <para>if you find this version a disaster!</para>
62 </sect1>
63
64 <sect1>
65         <title>Step 2: The all important step</title>
66         
67         <para>At this stage you must fetch yourself a 
68         coffee or other drink you find stimulating. Getting the rest 
69         of the install right can sometimes be tricky, so you will 
70         probably need it.</para>
71
72         <para>If you have installed samba before then you can skip 
73         this step.</para>
74 </sect1>
75
76 <sect1>
77         <title>Step 3: Create the smb configuration file. </title>
78
79         <para>There are sample configuration files in the examples 
80         subdirectory in the distribution. I suggest you read them 
81         carefully so you can see how the options go together in 
82         practice. See the man page for all the options.</para>
83
84         <para>The simplest useful configuration file would be 
85         something like this:</para>
86
87         <para><programlisting>
88         [global]
89            workgroup = MYGROUP
90
91            [homes]
92               guest ok = no
93               read only = no
94         </programlisting</para>
95         
96         <para>which would allow connections by anyone with an 
97         account on the server, using either their login name or 
98         "homes" as the service name. (Note that I also set the 
99         workgroup that Samba is part of. See BROWSING.txt for details)</para>
100         
101         <para>Note that <command>make install</command> will not install 
102         a <filename>smb.conf</filename> file. You need to create it 
103         yourself. </para>
104         
105         <para>Make sure you put the smb.conf file in the same place 
106         you specified in the<filename>Makefile</filename> (the default is to 
107         look for it in <filename>/usr/local/samba/lib/</filename>).</para>
108
109         <para>For more information about security settings for the 
110         [homes] share please refer to the document UNIX_SECURITY.txt.</para>
111 </sect1>
112
113 <sect1>
114         <title>Step 4: Test your config file with 
115         <command>testparm</command></title>
116
117         <para>It's important that you test the validity of your
118         <filename>smb.conf</filename> file using the testparm program. 
119         If testparm runs OK then it will list the loaded services. If 
120         not it will give an error message.</para>
121
122         <para>Make sure it runs OK and that the services look 
123         reasonable before proceeding. </para>
124
125 </sect1>
126
127 <sect1>
128         <title>Step 5: Starting the smbd and nmbd</title>
129
130         <para>You must choose to start smbd and nmbd either
131         as daemons or from <command>inetd</command>. Don't try
132         to do both!  Either you can put them in <filename>
133         inetd.conf</filename> and have them started on demand
134         by <command>inetd</command>, or you can start them as
135         daemons either from the command line or in <filename>
136         /etc/rc.local</filename>. See the man pages for details
137         on the command line options. Take particular care to read
138         the bit about what user you need to be in order to start
139         Samba.  In many cases you must be root.</para>
140
141         <para>The main advantage of starting <command>smbd</command>
142         and <command>nmbd</command> using the recommended daemon method
143         is that they will respond slightly more quickly to an initial connection
144         request.</para>
145
146         <sect2>
147                 <title>Step 5a: Starting from inetd.conf</title>
148
149                 <para>NOTE; The following will be different if 
150                 you use NIS or NIS+ to distributed services maps.</para>
151                 
152                 <para>Look at your <filename>/etc/services</filename>. 
153                 What is defined at port 139/tcp. If nothing is defined 
154                 then add a line like this:</para>
155
156                 <para><userinput>netbios-ssn     139/tcp</userinput></para>
157
158                 <para>similarly for 137/udp you should have an entry like:</para>
159
160                 <para><userinput>netbios-ns     137/udp</userinput></para>
161
162                 <para>Next edit your <filename>/etc/inetd.conf</filename> 
163                 and add two lines something like this:</para>
164
165                 <para><programlisting>
166                 netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd 
167                 netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd 
168                 </programlisting></para>
169
170                 <para>The exact syntax of <filename>/etc/inetd.conf</filename> 
171                 varies between unixes. Look at the other entries in inetd.conf 
172                 for a guide.</para>
173
174                 <para>NOTE: Some unixes already have entries like netbios_ns 
175                 (note the underscore) in <filename>/etc/services</filename>. 
176                 You must either edit <filename>/etc/services</filename> or
177                 <filename>/etc/inetd.conf</filename> to make them consistent.</para>
178
179                 <para>NOTE: On many systems you may need to use the 
180                 "interfaces" option in smb.conf to specify the IP address 
181                 and netmask of your interfaces. Run <command>ifconfig</command> 
182                 as root if you don't know what the broadcast is for your
183                 net. <command>nmbd</command> tries to determine it at run 
184                 time, but fails on some unixes. See the section on "testing nmbd" 
185                 for a method of finding if you need to do this.</para>
186
187                 <para>!!!WARNING!!! Many unixes only accept around 5 
188                 parameters on the command line in <filename>inetd.conf</filename>. 
189                 This means you shouldn't use spaces between the options and 
190                 arguments, or you should use a script, and start the script 
191                 from <command>inetd</command>.</para>
192
193                 <para>Restart <command>inetd</command>, perhaps just send 
194                 it a HUP. If you have installed an earlier version of <command>
195                 nmbd</command> then you may need to kill nmbd as well.</para>
196         </sect2>
197         
198         <sect2>
199                 <title>Step 5b. Alternative: starting it as a daemon</title>
200
201                 <para>To start the server as a daemon you should create 
202                 a script something like this one, perhaps calling 
203                 it <filename>startsmb</filename>.</para>
204
205                 <para><programlisting>
206                 #!/bin/sh
207                 /usr/local/samba/bin/smbd -D 
208                 /usr/local/samba/bin/nmbd -D 
209                 </programlisting></para>
210
211                 <para>then make it executable with <command>chmod 
212                 +x startsmb</command></para>
213
214                 <para>You can then run <command>startsmb</command> by 
215                 hand or execute it from <filename>/etc/rc.local</filename>
216                 </para>
217
218                 <para>To kill it send a kill signal to the processes 
219                 <command>nmbd</command> and <command>smbd</command>.</para>
220
221                 <para>NOTE: If you use the SVR4 style init system then 
222                 you may like to look at the <filename>examples/svr4-startup</filename>
223                 script to make Samba fit into that system.</para>
224         </sect2>
225 </sect1>
226
227 <sect1>
228         <title>Step 6: Try listing the shares available on your 
229         server</title>
230
231         <para><prompt>$ </prompt><userinput>smbclient -L 
232         <replaceable>yourhostname</replaceable></userinput></para>
233
234         <para>Your should get back a list of shares available on 
235         your server. If you don't then something is incorrectly setup. 
236         Note that this method can also be used to see what shares 
237         are available on other LanManager clients (such as WfWg).</para>
238
239         <para>If you choose user level security then you may find 
240         that Samba requests a password before it will list the shares. 
241         See the <command>smbclient</command> man page for details. (you 
242         can force it to list the shares without a password by
243         adding the option -U% to the command line. This will not work 
244         with non-Samba servers)</para>
245 </sect1>
246
247 <sect1>
248         <title>Step 7: Try connecting with the unix client</title>
249         
250         <para><prompt>$ </prompt><userinput>smbclient <replaceable>
251         //yourhostname/aservice</replaceable></userinput></para>
252         
253         <para>Typically the <replaceable>yourhostname</replaceable> 
254         would be the name of the host where you installed <command>
255         smbd</command>. The <replaceable>aservice</replaceable> is 
256         any service you have defined in the <filename>smb.conf</filename> 
257         file. Try your user name if you just have a [homes] section
258         in <filename>smb.conf</filename>.</para>
259
260         <para>For example if your unix host is bambi and your login 
261         name is fred you would type:</para>
262
263         <para><prompt>$ </prompt><userinput>smbclient //bambi/fred
264         </userinput></para>
265 </sect1>
266
267 <sect1>
268         <title>Step 8: Try connecting from a DOS, WfWg, Win9x, WinNT, 
269         Win2k, OS/2, etc... client</title>
270         
271         <para>Try mounting disks. eg:</para>
272
273         <para><prompt>C:\WINDOWS\> </prompt><userinput>net use d: \\servername\service
274         </userinput></para>
275
276         <para>Try printing. eg:</para>
277
278         <para><prompt>C:\WINDOWS\> </prompt><userinput>net use lpt1:
279         \\servername\spoolservice</userinput></para>
280
281         <para><prompt>C:\WINDOWS\> </prompt><userinput>print filename
282         </userinput></para>
283
284         <para>Celebrate, or send me a bug report!</para>
285 </sect1>
286
287 <sect1>
288         <title>What If Things Don't Work?</title>
289         
290         <para>If nothing works and you start to think "who wrote 
291         this pile of trash" then I suggest you do step 2 again (and 
292         again) till you calm down.</para>
293
294         <para>Then you might read the file DIAGNOSIS.txt and the 
295         FAQ. If you are still stuck then try the mailing list or 
296         newsgroup (look in the README for details). Samba has been 
297         successfully installed at thousands of sites worldwide, so maybe 
298         someone else has hit your problem and has overcome it. You could 
299         also use the WWW site to scan back issues of the samba-digest.</para>
300
301         <para>When you fix the problem PLEASE send me some updates to the
302         documentation (or source code) so that the next person will find it
303         easier. </para>
304
305         <sect2>
306                 <title>Diagnosing Problems</title>
307
308                 <para>If you have installation problems then go to 
309                 <filename>DIAGNOSIS.txt</filename> to try to find the 
310                 problem.</para>
311         </sect2>
312         
313         <sect2>
314                 <title>Scope IDs</title>
315
316                 <para>By default Samba uses a blank scope ID. This means 
317                 all your windows boxes must also have a blank scope ID. 
318                 If you really want to use a non-blank scope ID then you will 
319                 need to use the -i &lt;scope&gt; option to nmbd, smbd, and 
320                 smbclient. All your PCs will need to have the same setting for 
321                 this to work. I do not recommend scope IDs.</para>
322         </sect2>
323
324
325         <sect2>
326                 <title>Choosing the Protocol Level</title>
327
328                 <para>The SMB protocol has many dialects. Currently 
329                 Samba supports 5, called CORE, COREPLUS, LANMAN1, 
330                 LANMAN2 and NT1.</para>
331
332                 <para>You can choose what maximum protocol to support 
333                 in the <filename>smb.conf</filename> file. The default is 
334                 NT1 and that is the best for the vast majority of sites.</para>
335
336                 <para>In older versions of Samba you may have found it 
337                 necessary to use COREPLUS. The limitations that led to 
338                 this have mostly been fixed. It is now less likely that you 
339                 will want to use less than LANMAN1. The only remaining advantage 
340                 of COREPLUS is that for some obscure reason WfWg preserves 
341                 the case of passwords in this protocol, whereas under LANMAN1, 
342                 LANMAN2 or NT1 it uppercases all passwords before sending them,
343                 forcing you to use the "password level=" option in some cases.</para>
344
345                 <para>The main advantage of LANMAN2 and NT1 is support for 
346                 long filenames with some clients (eg: smbclient, Windows NT 
347                 or Win95). </para>
348
349                 <para>See the smb.conf(5) manual page for more details.</para>
350
351                 <para>Note: To support print queue reporting you may find 
352                 that you have to use TCP/IP as the default protocol under 
353                 WfWg. For some reason if you leave Netbeui as the default 
354                 it may break the print queue reporting on some systems. 
355                 It is presumably a WfWg bug.</para>
356         </sect2>
357         
358         <sect2>
359                 <title>Printing from UNIX to a Client PC</title>
360
361                 <para>To use a printer that is available via a smb-based 
362                 server from a unix host you will need to compile the 
363                 smbclient program. You then need to install the script 
364                 "smbprint". Read the instruction in smbprint for more details.
365                 </para>
366
367                 <para>There is also a SYSV style script that does much 
368                 the same thing called smbprint.sysv. It contains instructions.</para>
369         </sect2>
370
371         <sect2>
372                 <title>Locking</title>
373
374                 <para>One area which sometimes causes trouble is locking.</para>
375
376                 <para>There are two types of locking which need to be 
377                 performed by a SMB server. The first is "record locking" 
378                 which allows a client to lock a range of bytes in a open file. 
379                 The second is the "deny modes" that are specified when a file 
380                 is open.</para>
381
382                 <para>Record locking semantics under Unix is very
383                 different from record locking under Windows. Versions
384                 of Samba before 2.2 have tried to use the native
385                 fcntl() unix system call to implement proper record
386                 locking between different Samba clients. This can not
387                 be fully correct due to several reasons. The simplest
388                 is the fact that a Windows client is allowed to lock a
389                 byte range up to 2^32 or 2^64, depending on the client
390                 OS. The unix locking only supports byte ranges up to
391                 2^31. So it is not possible to correctly satisfy a
392                 lock request above 2^31. There are many more
393                 differences, too many to be listed here.</para>
394
395                 <para>Samba 2.2 and above implements record locking
396                 completely independent of the underlying unix
397                 system. If a byte range lock that the client requests
398                 happens to fall into the range 0-2^31, Samba hands
399                 this request down to the Unix system. All other locks
400                 can not be seen by unix anyway.</para>
401
402                 <para>Strictly a SMB server should check for locks before 
403                 every read and write call on a file. Unfortunately with the 
404                 way fcntl() works this can be slow and may overstress the 
405                 rpc.lockd. It is also almost always unnecessary as clients 
406                 are supposed to independently make locking calls before reads 
407                 and writes anyway if locking is important to them. By default 
408                 Samba only makes locking calls when explicitly asked
409                 to by a client, but if you set "strict locking = yes" then it will
410                 make lock checking calls on every read and write. </para>
411
412                 <para>You can also disable by range locking completely 
413                 using "locking = no". This is useful for those shares that 
414                 don't support locking or don't need it (such as cdroms). In 
415                 this case Samba fakes the return codes of locking calls to 
416                 tell clients that everything is OK.</para>
417
418                 <para>The second class of locking is the "deny modes". These 
419                 are set by an application when it opens a file to determine 
420                 what types of access should be allowed simultaneously with 
421                 its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE 
422                 or DENY_ALL. There are also special compatibility modes called 
423                 DENY_FCB and  DENY_DOS.</para>
424         </sect2>
425         
426         <sect2>
427                 <title>Mapping Usernames</title>
428         
429                 <para>If you have different usernames on the PCs and 
430                 the unix server then take a look at the "username map" option. 
431                 See the smb.conf man page for details.</para>
432         </sect2>
433
434         <sect2>
435                 <title>Other Character Sets</title>
436
437                 <para>If you have problems using filenames with accented 
438                 characters in them (like the German, French or Scandinavian 
439                 character sets) then I recommend you look at the "valid chars" 
440                 option in smb.conf and also take a look at the validchars 
441                 package in the examples directory.</para>
442         </sect2>
443         
444 </sect1>        
445 </chapter>