merge from 2.2
[Samba/gbeck.git] / docs / htmldocs / UNIX_INSTALL.html
blob34f4ed9283abff27ce9d0765259ed51f036edc1a
1 <HTML
2 ><HEAD
3 ><TITLE
4 >How to Install and Test SAMBA</TITLE
5 ><META
6 NAME="GENERATOR"
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.57"></HEAD
8 ><BODY
9 CLASS="ARTICLE"
10 BGCOLOR="#FFFFFF"
11 TEXT="#000000"
12 LINK="#0000FF"
13 VLINK="#840084"
14 ALINK="#0000FF"
15 ><DIV
16 CLASS="ARTICLE"
17 ><DIV
18 CLASS="TITLEPAGE"
19 ><H1
20 CLASS="TITLE"
21 ><A
22 NAME="AEN1"
23 >How to Install and Test SAMBA</A
24 ></H1
25 ><HR></DIV
26 ><DIV
27 CLASS="SECT1"
28 ><H1
29 CLASS="SECT1"
30 ><A
31 NAME="AEN3"
32 >Step 0: Read the man pages</A
33 ></H1
34 ><P
35 >The man pages distributed with SAMBA contain
36 lots of useful info that will help to get you started.
37 If you don't know how to read man pages then try
38 something like:</P
39 ><P
40 ><TT
41 CLASS="PROMPT"
42 >$ </TT
43 ><TT
44 CLASS="USERINPUT"
45 ><B
46 >nroff -man smbd.8 | more
47 </B
48 ></TT
49 ></P
50 ><P
51 >Other sources of information are pointed to
52 by the Samba web site,<A
53 HREF="http://www.samba.org/"
54 TARGET="_top"
55 > http://www.samba.org</A
56 ></P
57 ></DIV
58 ><DIV
59 CLASS="SECT1"
60 ><HR><H1
61 CLASS="SECT1"
62 ><A
63 NAME="AEN11"
64 >Step 1: Building the Binaries</A
65 ></H1
66 ><P
67 >To do this, first run the program <B
68 CLASS="COMMAND"
69 >./configure
70 </B
71 > in the source directory. This should automatically
72 configure Samba for your operating system. If you have unusual
73 needs then you may wish to run</P
74 ><P
75 ><TT
76 CLASS="PROMPT"
77 >root# </TT
78 ><TT
79 CLASS="USERINPUT"
80 ><B
81 >./configure --help
82 </B
83 ></TT
84 ></P
85 ><P
86 >first to see what special options you can enable.
87 Then exectuting</P
88 ><P
89 ><TT
90 CLASS="PROMPT"
91 >root# </TT
92 ><TT
93 CLASS="USERINPUT"
94 ><B
95 >make</B
96 ></TT
97 ></P
98 ><P
99 >will create the binaries. Once it's successfully
100 compiled you can use </P
102 ><TT
103 CLASS="PROMPT"
104 >root# </TT
105 ><TT
106 CLASS="USERINPUT"
108 >make install</B
109 ></TT
110 ></P
112 >to install the binaries and manual pages. You can
113 separately install the binaries and/or man pages using</P
115 ><TT
116 CLASS="PROMPT"
117 >root# </TT
118 ><TT
119 CLASS="USERINPUT"
121 >make installbin
123 ></TT
124 ></P
126 >and</P
128 ><TT
129 CLASS="PROMPT"
130 >root# </TT
131 ><TT
132 CLASS="USERINPUT"
134 >make installman
136 ></TT
137 ></P
139 >Note that if you are upgrading for a previous version
140 of Samba you might like to know that the old versions of
141 the binaries will be renamed with a ".old" extension. You
142 can go back to the previous version with</P
144 ><TT
145 CLASS="PROMPT"
146 >root# </TT
147 ><TT
148 CLASS="USERINPUT"
150 >make revert
152 ></TT
153 ></P
155 >if you find this version a disaster!</P
156 ></DIV
157 ><DIV
158 CLASS="SECT1"
159 ><HR><H1
160 CLASS="SECT1"
162 NAME="AEN39"
163 >Step 2: The all important step</A
164 ></H1
166 >At this stage you must fetch yourself a
167 coffee or other drink you find stimulating. Getting the rest
168 of the install right can sometimes be tricky, so you will
169 probably need it.</P
171 >If you have installed samba before then you can skip
172 this step.</P
173 ></DIV
174 ><DIV
175 CLASS="SECT1"
176 ><HR><H1
177 CLASS="SECT1"
179 NAME="AEN43"
180 >Step 3: Create the smb configuration file.</A
181 ></H1
183 >There are sample configuration files in the examples
184 subdirectory in the distribution. I suggest you read them
185 carefully so you can see how the options go together in
186 practice. See the man page for all the options.</P
188 >The simplest useful configuration file would be
189 something like this:</P
191 ><PRE
192 CLASS="PROGRAMLISTING"
193 > [global]
194 workgroup = MYGROUP
196 [homes]
197 guest ok = no
198 read only = no
199 </PRE
200 ></P
202 >which would allow connections by anyone with an
203 account on the server, using either their login name or
204 "homes" as the service name. (Note that I also set the
205 workgroup that Samba is part of. See BROWSING.txt for defails)</P
207 >Note that <B
208 CLASS="COMMAND"
209 >make install</B
210 > will not install
211 a <TT
212 CLASS="FILENAME"
213 >smb.conf</TT
214 > file. You need to create it
215 yourself. </P
217 >Make sure you put the smb.conf file in the same place
218 you specified in the<TT
219 CLASS="FILENAME"
220 >Makefile</TT
221 > (the default is to
222 look for it in <TT
223 CLASS="FILENAME"
224 >/usr/local/samba/lib/</TT
225 >).</P
227 >For more information about security settings for the
228 [homes] share please refer to the document UNIX_SECURITY.txt.</P
229 ></DIV
230 ><DIV
231 CLASS="SECT1"
232 ><HR><H1
233 CLASS="SECT1"
235 NAME="AEN57"
236 >Step 4: Test your config file with
238 CLASS="COMMAND"
239 >testparm</B
240 ></A
241 ></H1
243 >It's important that you test the validity of your
245 CLASS="FILENAME"
246 >smb.conf</TT
247 > file using the testparm program.
248 If testparm runs OK then it will list the loaded services. If
249 not it will give an error message.</P
251 >Make sure it runs OK and that the services look
252 resonable before proceeding. </P
253 ></DIV
254 ><DIV
255 CLASS="SECT1"
256 ><HR><H1
257 CLASS="SECT1"
259 NAME="AEN63"
260 >Step 5: Starting the smbd and nmbd</A
261 ></H1
263 >You must choose to start smbd and nmbd either
264 as daemons or from <B
265 CLASS="COMMAND"
266 >inetd</B
267 >. Don't try
268 to do both! Either you can put them in <TT
269 CLASS="FILENAME"
270 > inetd.conf</TT
271 > and have them started on demand
272 by <B
273 CLASS="COMMAND"
274 >inetd</B
275 >, or you can start them as
276 daemons either from the command line or in <TT
277 CLASS="FILENAME"
278 > /etc/rc.local</TT
279 >. See the man pages for details
280 on the command line options. Take particular care to read
281 the bit about what user you need to be in order to start
282 Samba. In many cases you must be root.</P
284 >The main advantage of starting <B
285 CLASS="COMMAND"
286 >smbd</B
288 and <B
289 CLASS="COMMAND"
290 >nmbd</B
291 > as a daemon is that they will
292 respond slightly more quickly to an initial connection
293 request. This is, however, unlikely to be a problem.</P
294 ><DIV
295 CLASS="SECT2"
296 ><HR><H2
297 CLASS="SECT2"
299 NAME="AEN73"
300 >Step 5a: Starting from inetd.conf</A
301 ></H2
303 >NOTE; The following will be different if
304 you use NIS or NIS+ to distributed services maps.</P
306 >Look at your <TT
307 CLASS="FILENAME"
308 >/etc/services</TT
310 What is defined at port 139/tcp. If nothing is defined
311 then add a line like this:</P
313 ><TT
314 CLASS="USERINPUT"
316 >netbios-ssn 139/tcp</B
317 ></TT
318 ></P
320 >similarly for 137/udp you should have an entry like:</P
322 ><TT
323 CLASS="USERINPUT"
325 >netbios-ns 137/udp</B
326 ></TT
327 ></P
329 >Next edit your <TT
330 CLASS="FILENAME"
331 >/etc/inetd.conf</TT
333 and add two lines something like this:</P
335 ><PRE
336 CLASS="PROGRAMLISTING"
337 > netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd
338 netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd
339 </PRE
340 ></P
342 >The exact syntax of <TT
343 CLASS="FILENAME"
344 >/etc/inetd.conf</TT
346 varies between unixes. Look at the other entries in inetd.conf
347 for a guide.</P
349 >NOTE: Some unixes already have entries like netbios_ns
350 (note the underscore) in <TT
351 CLASS="FILENAME"
352 >/etc/services</TT
354 You must either edit <TT
355 CLASS="FILENAME"
356 >/etc/services</TT
357 > or
359 CLASS="FILENAME"
360 >/etc/inetd.conf</TT
361 > to make them consistant.</P
363 >NOTE: On many systems you may need to use the
364 "interfaces" option in smb.conf to specify the IP address
365 and netmask of your interfaces. Run <B
366 CLASS="COMMAND"
367 >ifconfig</B
369 as root if you don't know what the broadcast is for your
370 net. <B
371 CLASS="COMMAND"
372 >nmbd</B
373 > tries to determine it at run
374 time, but fails on somunixes. See the section on "testing nmbd"
375 for a method of finding if you need to do this.</P
377 >!!!WARNING!!! Many unixes only accept around 5
378 parameters on the command line in <TT
379 CLASS="FILENAME"
380 >inetd.conf</TT
382 This means you shouldn't use spaces between the options and
383 arguments, or you should use a script, and start the script
384 from <B
385 CLASS="COMMAND"
386 >inetd</B
387 >.</P
389 >Restart <B
390 CLASS="COMMAND"
391 >inetd</B
392 >, perhaps just send
393 it a HUP. If you have installed an earlier version of <B
394 CLASS="COMMAND"
395 > nmbd</B
396 > then you may need to kill nmbd as well.</P
397 ></DIV
398 ><DIV
399 CLASS="SECT2"
400 ><HR><H2
401 CLASS="SECT2"
403 NAME="AEN102"
404 >Step 5b. Alternative: starting it as a daemon</A
405 ></H2
407 >To start the server as a daemon you should create
408 a script something like this one, perhaps calling
409 it <TT
410 CLASS="FILENAME"
411 >startsmb</TT
412 >.</P
414 ><PRE
415 CLASS="PROGRAMLISTING"
416 > #!/bin/sh
417 /usr/local/samba/bin/smbd -D
418 /usr/local/samba/bin/nmbd -D
419 </PRE
420 ></P
422 >then make it executable with <B
423 CLASS="COMMAND"
424 >chmod
425 +x startsmb</B
426 ></P
428 >You can then run <B
429 CLASS="COMMAND"
430 >startsmb</B
431 > by
432 hand or execute it from <TT
433 CLASS="FILENAME"
434 >/etc/rc.local</TT
438 >To kill it send a kill signal to the processes
440 CLASS="COMMAND"
441 >nmbd</B
442 > and <B
443 CLASS="COMMAND"
444 >smbd</B
445 >.</P
447 >NOTE: If you use the SVR4 style init system then
448 you may like to look at the <TT
449 CLASS="FILENAME"
450 >examples/svr4-startup</TT
452 script to make Samba fit into that system.</P
453 ></DIV
454 ></DIV
455 ><DIV
456 CLASS="SECT1"
457 ><HR><H1
458 CLASS="SECT1"
460 NAME="AEN118"
461 >Step 6: Try listing the shares available on your
462 server</A
463 ></H1
465 ><TT
466 CLASS="PROMPT"
467 >$ </TT
468 ><TT
469 CLASS="USERINPUT"
471 >smbclient -L
473 CLASS="REPLACEABLE"
475 >yourhostname</I
476 ></TT
477 ></B
478 ></TT
479 ></P
481 >Your should get back a list of shares available on
482 your server. If you don't then something is incorrectly setup.
483 Note that this method can also be used to see what shares
484 are available on other LanManager clients (such as WfWg).</P
486 >If you choose user level security then you may find
487 that Samba requests a password before it will list the shares.
488 See the <B
489 CLASS="COMMAND"
490 >smbclient</B
491 > man page for details. (you
492 can force it to list the shares without a password by
493 adding the option -U% to the command line. This will not work
494 with non-Samba servers)</P
495 ></DIV
496 ><DIV
497 CLASS="SECT1"
498 ><HR><H1
499 CLASS="SECT1"
501 NAME="AEN127"
502 >Step 7: Try connecting with the unix client</A
503 ></H1
505 ><TT
506 CLASS="PROMPT"
507 >$ </TT
508 ><TT
509 CLASS="USERINPUT"
511 >smbclient <TT
512 CLASS="REPLACEABLE"
514 > //yourhostname/aservice</I
515 ></TT
516 ></B
517 ></TT
518 ></P
520 >Typically the <TT
521 CLASS="REPLACEABLE"
523 >yourhostname</I
524 ></TT
526 would be the name of the host where you installed <B
527 CLASS="COMMAND"
528 > smbd</B
529 >. The <TT
530 CLASS="REPLACEABLE"
532 >aservice</I
533 ></TT
534 > is
535 any service you have defined in the <TT
536 CLASS="FILENAME"
537 >smb.conf</TT
539 file. Try your user name if you just have a [homes] section
540 in <TT
541 CLASS="FILENAME"
542 >smb.conf</TT
543 >.</P
545 >For example if your unix host is bambi and your login
546 name is fred you would type:</P
548 ><TT
549 CLASS="PROMPT"
550 >$ </TT
551 ><TT
552 CLASS="USERINPUT"
554 >smbclient //bambi/fred
556 ></TT
557 ></P
558 ></DIV
559 ><DIV
560 CLASS="SECT1"
561 ><HR><H1
562 CLASS="SECT1"
564 NAME="AEN143"
565 >Step 8: Try connecting from a DOS, WfWg, Win9x, WinNT,
566 Win2k, OS/2, etc... client</A
567 ></H1
569 >Try mounting disks. eg:</P
571 ><TT
572 CLASS="PROMPT"
573 >C:\WINDOWS\&#62; </TT
574 ><TT
575 CLASS="USERINPUT"
577 >net use d: \\servername\service
579 ></TT
580 ></P
582 >Try printing. eg:</P
584 ><TT
585 CLASS="PROMPT"
586 >C:\WINDOWS\&#62; </TT
587 ><TT
588 CLASS="USERINPUT"
590 >net use lpt1:
591 \\servername\spoolservice</B
592 ></TT
593 ></P
595 ><TT
596 CLASS="PROMPT"
597 >C:\WINDOWS\&#62; </TT
598 ><TT
599 CLASS="USERINPUT"
601 >print filename
603 ></TT
604 ></P
606 >Celebrate, or send me a bug report!</P
607 ></DIV
608 ><DIV
609 CLASS="SECT1"
610 ><HR><H1
611 CLASS="SECT1"
613 NAME="AEN157"
614 >What If Things Don't Work?</A
615 ></H1
617 >If nothing works and you start to think "who wrote
618 this pile of trash" then I suggest you do step 2 again (and
619 again) till you calm down.</P
621 >Then you might read the file DIAGNOSIS.txt and the
622 FAQ. If you are still stuck then try the mailing list or
623 newsgroup (look in the README for details). Samba has been
624 successfully installed at thousands of sites worldwide, so maybe
625 someone else has hit your problem and has overcome it. You could
626 also use the WWW site to scan back issues of the samba-digest.</P
628 >When you fix the problem PLEASE send me some updates to the
629 documentation (or source code) so that the next person will find it
630 easier. </P
631 ><DIV
632 CLASS="SECT2"
633 ><HR><H2
634 CLASS="SECT2"
636 NAME="AEN162"
637 >Diagnosing Problems</A
638 ></H2
640 >If you have instalation problems then go to
642 CLASS="FILENAME"
643 >DIAGNOSIS.txt</TT
644 > to try to find the
645 problem.</P
646 ></DIV
647 ><DIV
648 CLASS="SECT2"
649 ><HR><H2
650 CLASS="SECT2"
652 NAME="AEN166"
653 >Scope IDs</A
654 ></H2
656 >By default Samba uses a blank scope ID. This means
657 all your windows boxes must also have a blank scope ID.
658 If you really want to use a non-blank scope ID then you will
659 need to use the -i &lt;scope&gt; option to nmbd, smbd, and
660 smbclient. All your PCs will need to have the same setting for
661 this to work. I do not recommend scope IDs.</P
662 ></DIV
663 ><DIV
664 CLASS="SECT2"
665 ><HR><H2
666 CLASS="SECT2"
668 NAME="AEN169"
669 >Choosing the Protocol Level</A
670 ></H2
672 >The SMB protocol has many dialects. Currently
673 Samba supports 5, called CORE, COREPLUS, LANMAN1,
674 LANMAN2 and NT1.</P
676 >You can choose what maximum protocol to support
677 in the <TT
678 CLASS="FILENAME"
679 >smb.conf</TT
680 > file. The default is
681 NT1 and that is the best for the vast majority of sites.</P
683 >In older versions of Samba you may have found it
684 necessary to use COREPLUS. The limitations that led to
685 this have mostly been fixed. It is now less likely that you
686 will want to use less than LANMAN1. The only remaining advantage
687 of COREPLUS is that for some obscure reason WfWg preserves
688 the case of passwords in this protocol, whereas under LANMAN1,
689 LANMAN2 or NT1 it uppercases all passwords before sending them,
690 forcing you to use the "password level=" option in some cases.</P
692 >The main advantage of LANMAN2 and NT1 is support for
693 long filenames with some clients (eg: smbclient, Windows NT
694 or Win95). </P
696 >See the smb.conf(5) manual page for more details.</P
698 >Note: To support print queue reporting you may find
699 that you have to use TCP/IP as the default protocol under
700 WfWg. For some reason if you leave Netbeui as the default
701 it may break the print queue reporting on some systems.
702 It is presumably a WfWg bug.</P
703 ></DIV
704 ><DIV
705 CLASS="SECT2"
706 ><HR><H2
707 CLASS="SECT2"
709 NAME="AEN178"
710 >Printing from UNIX to a Client PC</A
711 ></H2
713 >To use a printer that is available via a smb-based
714 server from a unix host you will need to compile the
715 smbclient program. You then need to install the script
716 "smbprint". Read the instruction in smbprint for more details.
719 >There is also a SYSV style script that does much
720 the same thing called smbprint.sysv. It contains instructions.</P
721 ></DIV
722 ><DIV
723 CLASS="SECT2"
724 ><HR><H2
725 CLASS="SECT2"
727 NAME="AEN182"
728 >Locking</A
729 ></H2
731 >One area which sometimes causes trouble is locking.</P
733 >There are two types of locking which need to be
734 performed by a SMB server. The first is "record locking"
735 which allows a client to lock a range of bytes in a open file.
736 The second is the "deny modes" that are specified when a file
737 is open.</P
739 >Samba supports "record locking" using the fcntl() unix system
740 call. This is often implemented using rpc calls to a rpc.lockd process
741 running on the system that owns the filesystem. Unfortunately many
742 rpc.lockd implementations are very buggy, particularly when made to
743 talk to versions from other vendors. It is not uncommon for the
744 rpc.lockd to crash.</P
746 >There is also a problem translating the 32 bit lock
747 requests generated by PC clients to 31 bit requests supported
748 by most unixes. Unfortunately many PC applications (typically
749 OLE2 applications) use byte ranges with the top bit set
750 as semaphore sets. Samba attempts translation to support
751 these types of applications, and the translation has proved
752 to be quite successful.</P
754 >Strictly a SMB server should check for locks before
755 every read and write call on a file. Unfortunately with the
756 way fcntl() works this can be slow and may overstress the
757 rpc.lockd. It is also almost always unnecessary as clients
758 are supposed to independently make locking calls before reads
759 and writes anyway if locking is important to them. By default
760 Samba only makes locking calls when explicitly asked
761 to by a client, but if you set "strict locking = yes" then it will
762 make lock checking calls on every read and write. </P
764 >You can also disable by range locking completely
765 using "locking = no". This is useful for those shares that
766 don't support locking or don't need it (such as cdroms). In
767 this case Samba fakes the return codes of locking calls to
768 tell clients that everything is OK.</P
770 >The second class of locking is the "deny modes". These
771 are set by an application when it opens a file to determine
772 what types of access should be allowed simultaneously with
773 its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE
774 or DENY_ALL. There are also special compatability modes called
775 DENY_FCB and DENY_DOS.</P
777 >You can disable share modes using "share modes = no".
778 This may be useful on a heavily loaded server as the share
779 modes code is very slow. See also the FAST_SHARE_MODES
780 option in the Makefile for a way to do full share modes
781 very fast using shared memory (if your OS supports it).</P
782 ></DIV
783 ><DIV
784 CLASS="SECT2"
785 ><HR><H2
786 CLASS="SECT2"
788 NAME="AEN192"
789 >Mapping Usernames</A
790 ></H2
792 >If you have different usernames on the PCs and
793 the unix server then take a look at the "username map" option.
794 See the smb.conf man page for details.</P
795 ></DIV
796 ><DIV
797 CLASS="SECT2"
798 ><HR><H2
799 CLASS="SECT2"
801 NAME="AEN195"
802 >Other Character Sets</A
803 ></H2
805 >If you have problems using filenames with accented
806 characters in them (like the German, French or Scandinavian
807 character sets) then I recommmend you look at the "valid chars"
808 option in smb.conf and also take a look at the validchars
809 package in the examples directory.</P
810 ></DIV
811 ></DIV
812 ></DIV
813 ></BODY
814 ></HTML