merge from 2.2
[samba.git] / docs / docbook / projdoc / UNIX_INSTALL.sgml
1 <chapter>
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 exectuting</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 defails)</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         resonable 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> as a daemon is that they will 
143         respond slightly more quickly to an initial connection
144         request. This is, however, unlikely to be a problem.</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 consistant.</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 somunixes. 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 instalation 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>Samba supports "record locking" using the fcntl() unix system
383                 call. This is often implemented using rpc calls to a rpc.lockd process
384                 running on the system that owns the filesystem. Unfortunately many
385                 rpc.lockd implementations are very buggy, particularly when made to
386                 talk to versions from other vendors. It is not uncommon for the
387                 rpc.lockd to crash.</para>
388
389                 <para>There is also a problem translating the 32 bit lock 
390                 requests generated by PC clients to 31 bit requests supported 
391                 by most unixes. Unfortunately many PC applications (typically 
392                 OLE2 applications) use byte ranges with the top bit set 
393                 as semaphore sets. Samba attempts translation to support 
394                 these types of applications, and the translation has proved 
395                 to be quite successful.</para>
396                 
397                 <para>Strictly a SMB server should check for locks before 
398                 every read and write call on a file. Unfortunately with the 
399                 way fcntl() works this can be slow and may overstress the 
400                 rpc.lockd. It is also almost always unnecessary as clients 
401                 are supposed to independently make locking calls before reads 
402                 and writes anyway if locking is important to them. By default 
403                 Samba only makes locking calls when explicitly asked
404                 to by a client, but if you set "strict locking = yes" then it will
405                 make lock checking calls on every read and write. </para>
406
407                 <para>You can also disable by range locking completely 
408                 using "locking = no". This is useful for those shares that 
409                 don't support locking or don't need it (such as cdroms). In 
410                 this case Samba fakes the return codes of locking calls to 
411                 tell clients that everything is OK.</para>
412
413                 <para>The second class of locking is the "deny modes". These 
414                 are set by an application when it opens a file to determine 
415                 what types of access should be allowed simultaneously with 
416                 its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE 
417                 or DENY_ALL. There are also special compatability modes called 
418                 DENY_FCB and  DENY_DOS.</para>
419
420                 <para>You can disable share modes using "share modes = no". 
421                 This may be useful on a heavily loaded server as the share 
422                 modes code is very slow. See also the FAST_SHARE_MODES 
423                 option in the Makefile for a way to do full share modes 
424                 very fast using shared memory (if your OS supports it).</para>
425         </sect2>
426         
427         <sect2>
428                 <title>Mapping Usernames</title>
429         
430                 <para>If you have different usernames on the PCs and 
431                 the unix server then take a look at the "username map" option. 
432                 See the smb.conf man page for details.</para>
433         </sect2>
434
435         <sect2>
436                 <title>Other Character Sets</title>
437
438                 <para>If you have problems using filenames with accented 
439                 characters in them (like the German, French or Scandinavian 
440                 character sets) then I recommmend you look at the "valid chars" 
441                 option in smb.conf and also take a look at the validchars 
442                 package in the examples directory.</para>
443         </sect2>
444         
445 </sect1>        
446 </chapter>