summaryrefslogtreecommitdiff
path: root/docs/docbook/projdoc
diff options
context:
space:
mode:
authorGerald Carter <jerry@samba.org>2001-02-26 13:32:51 +0000
committerGerald Carter <jerry@samba.org>2001-02-26 13:32:51 +0000
commit1c523188a5cc6b70497e41ca3ce7a25a58dfa706 (patch)
treee2f34464ebd7863514934d7c345be398dfb44d4f /docs/docbook/projdoc
parent46b5e6bdae0fcffc2a11a340f5416a8e5b78944b (diff)
downloadsamba-1c523188a5cc6b70497e41ca3ce7a25a58dfa706.tar.gz
samba-1c523188a5cc6b70497e41ca3ce7a25a58dfa706.tar.bz2
samba-1c523188a5cc6b70497e41ca3ce7a25a58dfa706.zip
beginning on consolidating individual text files.
Chapter 1 contains UNIX_INSTALL.txt (This used to be commit 45d406ba274ac830dd52544645090b5e4dbf5768)
Diffstat (limited to 'docs/docbook/projdoc')
-rw-r--r--docs/docbook/projdoc/chapter1.sgml446
-rw-r--r--docs/docbook/projdoc/samba-doc.sgml22
2 files changed, 468 insertions, 0 deletions
diff --git a/docs/docbook/projdoc/chapter1.sgml b/docs/docbook/projdoc/chapter1.sgml
new file mode 100644
index 0000000000..71589b5d60
--- /dev/null
+++ b/docs/docbook/projdoc/chapter1.sgml
@@ -0,0 +1,446 @@
+<chapter>
+
+<title>How to Install and Test SAMBA</title>
+
+<sect1>
+ <title>Step 0: Read the man pages</title>
+
+ <para>The man pages distributed with SAMBA contain
+ lots of useful info that will help to get you started.
+ If you don't know how to read man pages then try
+ something like:</para>
+
+ <para><prompt>$ </prompt><userinput>nroff -man smbd.8 | more
+ </userinput></para>
+
+ <para>Other sources of information are pointed to
+ by the Samba web site,<ulink url="http://www.samba.org/">
+ http://www.samba.org</ulink></para>
+</sect1>
+
+<sect1>
+ <title>Building the Binaries</title>
+
+ <para>To do this, first run the program <command>./configure
+ </command> in the source directory. This should automatically
+ configure Samba for your operating system. If you have unusual
+ needs then you may wish to run</para>
+
+ <para><prompt>root# </prompt><userinput>./configure --help
+ </userinput></para>
+
+ <para>first to see what special options you can enable.
+ Then exectuting</para>
+
+ <para><prompt>root# </prompt><userinput>make</userinput></para>
+
+ <para>will create the binaries. Once it's successfully
+ compiled you can use </para>
+
+ <para><prompt>root# </prompt><userinput>make install</userinput></para>
+
+ <para>to install the binaries and manual pages. You can
+ separately install the binaries and/or man pages using</para>
+
+ <para><prompt>root# </prompt><userinput>make installbin
+ </userinput></para>
+
+ <para>and</para>
+
+ <para><prompt>root# </prompt><userinput>make installman
+ </userinput></para>
+
+ <para>Note that if you are upgrading for a previous version
+ of Samba you might like to know that the old versions of
+ the binaries will be renamed with a ".old" extension. You
+ can go back to the previous version with</para>
+
+ <para><prompt>root# </prompt><userinput>make revert
+ </userinput></para>
+
+ <para>if you find this version a disaster!</para>
+</sect1>
+
+<sect1>
+ <title>Step 2: The all important step</title>
+
+ <para>At this stage you must fetch yourself a
+ coffee or other drink you find stimulating. Getting the rest
+ of the install right can sometimes be tricky, so you will
+ probably need it.</para>
+
+ <para>If you have installed samba before then you can skip
+ this step.</para>
+</sect1>
+
+<sect1>
+ <title>Step 3: Create the smb configuration file. </title>
+
+ <para>There are sample configuration files in the examples
+ subdirectory in the distribution. I suggest you read them
+ carefully so you can see how the options go together in
+ practice. See the man page for all the options.</para>
+
+ <para>The simplest useful configuration file would be
+ something like this:</para>
+
+ <para><programlisting>
+ [global]
+ workgroup = MYGROUP
+
+ [homes]
+ guest ok = no
+ read only = no
+ </programlisting</para>
+
+ <para>which would allow connections by anyone with an
+ account on the server, using either their login name or
+ "homes" as the service name. (Note that I also set the
+ workgroup that Samba is part of. See BROWSING.txt for defails)</para>
+
+ <para>Note that <command>make install</command> will not install
+ a <filename>smb.conf</filename> file. You need to create it
+ yourself. </para>
+
+ <para>Make sure you put the smb.conf file in the same place
+ you specified in the<filename>Makefile</filename> (the default is to
+ look for it in <filename>/usr/local/samba/lib/</filename>).</para>
+
+ <para>For more information about security settings for the
+ [homes] share please refer to the document UNIX_SECURITY.txt.</para>
+</sect1>
+
+<sect1>
+ <title>Step 4: Test your config file with
+ <command>testparm</command></title>
+
+ <para>It's important that you test the validity of your
+ <filename>smb.conf</filename> file using the testparm program.
+ If testparm runs OK then it will list the loaded services. If
+ not it will give an error message.</para>
+
+ <para>Make sure it runs OK and that the services look
+ resonable before proceeding. </para>
+
+</sect1>
+
+<sect1>
+ <title>Step 5: Starting the smbd and nmbd</title>
+
+ <para>You must choose to start smbd and nmbd either
+ as daemons or from <command>inetd</command>. Don't try
+ to do both! Either you can put them in <filename>
+ inetd.conf</filename> and have them started on demand
+ by <command>inetd</command>, or you can start them as
+ daemons either from the command line or in <filename>
+ /etc/rc.local</filename>. See the man pages for details
+ on the command line options. Take particular care to read
+ the bit about what user you need to be in order to start
+ Samba. In many cases you must be root.</para>
+
+ <para>The main advantage of starting <command>smbd</command>
+ and <command>nmbd</command> as a daemon is that they will
+ respond slightly more quickly to an initial connection
+ request. This is, however, unlikely to be a problem.</para>
+
+ <sect2>
+ <title>Step 5a: Starting from inetd.conf</title>
+
+ <para>NOTE; The following will be different if
+ you use NIS or NIS+ to distributed services maps.</para>
+
+ <para>Look at your <filename>/etc/services</filename>.
+ What is defined at port 139/tcp. If nothing is defined
+ then add a line like this:</para>
+
+ <para><userinput>netbios-ssn 139/tcp</userinput></para>
+
+ <para>similarly for 137/udp you should have an entry like:</para>
+
+ <para><userinput>netbios-ns 137/udp</userinput></para>
+
+ <para>Next edit your <filename>/etc/inetd.conf</filename>
+ and add two lines something like this:</para>
+
+ <para><programlisting>
+ netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd
+ netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd
+ </programlisting></para>
+
+ <para>The exact syntax of <filename>/etc/inetd.conf</filename>
+ varies between unixes. Look at the other entries in inetd.conf
+ for a guide.</para>
+
+ <para>NOTE: Some unixes already have entries like netbios_ns
+ (note the underscore) in <filename>/etc/services</filename>.
+ You must either edit <filename>/etc/services</filename> or
+ <filename>/etc/inetd.conf</filename> to make them consistant.</para>
+
+ <para>NOTE: On many systems you may need to use the
+ "interfaces" option in smb.conf to specify the IP address
+ and netmask of your interfaces. Run <command>ifconfig</command>
+ as root if you don't know what the broadcast is for your
+ net. <command>nmbd</command> tries to determine it at run
+ time, but fails on somunixes. See the section on "testing nmbd"
+ for a method of finding if you need to do this.</para>
+
+ <para>!!!WARNING!!! Many unixes only accept around 5
+ parameters on the command line in <filename>inetd.conf</filename>.
+ This means you shouldn't use spaces between the options and
+ arguments, or you should use a script, and start the script
+ from <command>inetd</command>.</para>
+
+ <para>Restart <command>inetd</command>, perhaps just send
+ it a HUP. If you have installed an earlier version of <command>
+ nmbd</command> then you may need to kill nmbd as well.</para>
+ </sect2>
+
+ <sect2>
+ <title>Step 5b. Alternative: starting it as a daemon</title>
+
+ <para>To start the server as a daemon you should create
+ a script something like this one, perhaps calling
+ it <filename>startsmb</filename>.</para>
+
+ <para><programlisting>
+ #!/bin/sh
+ /usr/local/samba/bin/smbd -D
+ /usr/local/samba/bin/nmbd -D
+ </programlisting></para>
+
+ <para>then make it executable with <command>chmod
+ +x startsmb</command></para>
+
+ <para>You can then run <command>startsmb</command> by
+ hand or execute it from <filename>/etc/rc.local</filename>
+ </para>
+
+ <para>To kill it send a kill signal to the processes
+ <command>nmbd</command> and <command>smbd</command>.</para>
+
+ <para>NOTE: If you use the SVR4 style init system then
+ you may like to look at the <filename>examples/svr4-startup</filename>
+ script to make Samba fit into that system.</para>
+ </sect2>
+</sect1>
+
+<sect1>
+ <title>Step 6: Try listing the shares available on your
+ server</title>
+
+ <para><prompt>$ </prompt><userinput>smbclient -L
+ <replaceable>yourhostname</replaceable></userinput></para>
+
+ <para>Your should get back a list of shares available on
+ your server. If you don't then something is incorrectly setup.
+ Note that this method can also be used to see what shares
+ are available on other LanManager clients (such as WfWg).</para>
+
+ <para>If you choose user level security then you may find
+ that Samba requests a password before it will list the shares.
+ See the <command>smbclient</command> man page for details. (you
+ can force it to list the shares without a password by
+ adding the option -U% to the command line. This will not work
+ with non-Samba servers)</para>
+</sect1>
+
+<sect1>
+ <title>Step 7: Try connecting with the unix client</title>
+
+ <para><prompt>$ </prompt><userinput>smbclient <replaceable>
+ //yourhostname/aservice</replaceable></userinput></para>
+
+ <para>Typically the <replaceable>yourhostname</replaceable>
+ would be the name of the host where you installed <command>
+ smbd</command>. The <replaceable>aservice</replaceable> is
+ any service you have defined in the <filename>smb.conf</filename>
+ file. Try your user name if you just have a [homes] section
+ in <filename>smb.conf</filename>.</para>
+
+ <para>For example if your unix host is bambi and your login
+ name is fred you would type:</para>
+
+ <para><prompt>$ </prompt><userinput>smbclient //bambi/fred
+ </userinput></para>
+</sect1>
+
+<sect1>
+ <title>Step 8: Try connecting from a DOS, WfWg, Win9x, WinNT,
+ Win2k, OS/2, etc... client</title>
+
+ <para>Try mounting disks. eg:</para>
+
+ <para><prompt>C:\WINDOWS\> </prompt><userinput>net use d: \\servername\service
+ </userinput></para>
+
+ <para>Try printing. eg:</para>
+
+ <para><prompt>C:\WINDOWS\> </prompt><userinput>net use lpt1:
+ \\servername\spoolservice</userinput></para>
+
+ <para><prompt>C:\WINDOWS\> </prompt><userinput>print filename
+ </userinput></para>
+
+ <para>Celebrate, or send me a bug report!</para>
+</sect1>
+
+<sect1>
+ <title>What If Things Don't Work?</title>
+
+ <para>If nothing works and you start to think "who wrote
+ this pile of trash" then I suggest you do step 2 again (and
+ again) till you calm down.</para>
+
+ <para>Then you might read the file DIAGNOSIS.txt and the
+ FAQ. If you are still stuck then try the mailing list or
+ newsgroup (look in the README for details). Samba has been
+ successfully installed at thousands of sites worldwide, so maybe
+ someone else has hit your problem and has overcome it. You could
+ also use the WWW site to scan back issues of the samba-digest.</para>
+
+ <para>When you fix the problem PLEASE send me some updates to the
+ documentation (or source code) so that the next person will find it
+ easier. </para>
+
+ <sect2>
+ <title>DIAGNOSING PROBLEMS</title>
+
+ <para>If you have instalation problems then go to
+ <filename>DIAGNOSIS.txt</filename> to try to find the
+ problem.</para>
+ </sect2>
+
+ <sect2>
+ <title>SCOPE IDs</title>
+
+ <para>By default Samba uses a blank scope ID. This means
+ all your windows boxes must also have a blank scope ID.
+ If you really want to use a non-blank scope ID then you will
+ need to use the -i &lt;scope&gt; option to nmbd, smbd, and
+ smbclient. All your PCs will need to have the same setting for
+ this to work. I do not recommend scope IDs.</para>
+ </sect2>
+
+
+ <sect2>
+ <title>CHOOSING THE PROTOCOL LEVEL</title>
+
+ <para>The SMB protocol has many dialects. Currently
+ Samba supports 5, called CORE, COREPLUS, LANMAN1,
+ LANMAN2 and NT1.</para>
+
+ <para>You can choose what maximum protocol to support
+ in the <filename>smb.conf</filename> file. The default is
+ NT1 and that is the best for the vast majority of sites.</para>
+
+ <para>In older versions of Samba you may have found it
+ necessary to use COREPLUS. The limitations that led to
+ this have mostly been fixed. It is now less likely that you
+ will want to use less than LANMAN1. The only remaining advantage
+ of COREPLUS is that for some obscure reason WfWg preserves
+ the case of passwords in this protocol, whereas under LANMAN1,
+ LANMAN2 or NT1 it uppercases all passwords before sending them,
+ forcing you to use the "password level=" option in some cases.</para>
+
+ <para>The main advantage of LANMAN2 and NT1 is support for
+ long filenames with some clients (eg: smbclient, Windows NT
+ or Win95). </para>
+
+ <para>See the smb.conf(5) manual page for more details.</para>
+
+ <para>Note: To support print queue reporting you may find
+ that you have to use TCP/IP as the default protocol under
+ WfWg. For some reason if you leave Netbeui as the default
+ it may break the print queue reporting on some systems.
+ It is presumably a WfWg bug.</para>
+ </sect2>
+
+ <sect2>
+ <title>PRINTING FROM UNIX TO A CLIENT PC</title>
+
+ <para>To use a printer that is available via a smb-based
+ server from a unix host you will need to compile the
+ smbclient program. You then need to install the script
+ "smbprint". Read the instruction in smbprint for more details.
+ </para>
+
+ <para>There is also a SYSV style script that does much
+ the same thing called smbprint.sysv. It contains instructions.</para>
+ </sect2>
+
+ <sect2>
+ <title>LOCKING</title>
+
+ <para>One area which sometimes causes trouble is locking.</para>
+
+ <para>There are two types of locking which need to be
+ performed by a SMB server. The first is "record locking"
+ which allows a client to lock a range of bytes in a open file.
+ The second is the "deny modes" that are specified when a file
+ is open.</para>
+
+ <para>Samba supports "record locking" using the fcntl() unix system
+ call. This is often implemented using rpc calls to a rpc.lockd process
+ running on the system that owns the filesystem. Unfortunately many
+ rpc.lockd implementations are very buggy, particularly when made to
+ talk to versions from other vendors. It is not uncommon for the
+ rpc.lockd to crash.</para>
+
+ <para>There is also a problem translating the 32 bit lock
+ requests generated by PC clients to 31 bit requests supported
+ by most unixes. Unfortunately many PC applications (typically
+ OLE2 applications) use byte ranges with the top bit set
+ as semaphore sets. Samba attempts translation to support
+ these types of applications, and the translation has proved
+ to be quite successful.</para>
+
+ <para>Strictly a SMB server should check for locks before
+ every read and write call on a file. Unfortunately with the
+ way fcntl() works this can be slow and may overstress the
+ rpc.lockd. It is also almost always unnecessary as clients
+ are supposed to independently make locking calls before reads
+ and writes anyway if locking is important to them. By default
+ Samba only makes locking calls when explicitly asked
+ to by a client, but if you set "strict locking = yes" then it will
+ make lock checking calls on every read and write. </para>
+
+ <para>You can also disable by range locking completely
+ using "locking = no". This is useful for those shares that
+ don't support locking or don't need it (such as cdroms). In
+ this case Samba fakes the return codes of locking calls to
+ tell clients that everything is OK.</para>
+
+ <para>The second class of locking is the "deny modes". These
+ are set by an application when it opens a file to determine
+ what types of access should be allowed simultaneously with
+ its open. A client may ask for DENY_NONE, DENY_READ, DENY_WRITE
+ or DENY_ALL. There are also special compatability modes called
+ DENY_FCB and DENY_DOS.</para>
+
+ <para>You can disable share modes using "share modes = no".
+ This may be useful on a heavily loaded server as the share
+ modes code is very slow. See also the FAST_SHARE_MODES
+ option in the Makefile for a way to do full share modes
+ very fast using shared memory (if your OS supports it).</para>
+ </sect2>
+
+ <sect2>
+ <title>MAPPING USERNAMES</title>
+
+ <para>If you have different usernames on the PCs and
+ the unix server then take a look at the "username map" option.
+ See the smb.conf man page for details.</para>
+ </sect2>
+
+ <sect2>
+ <title>OTHER CHARACTER SETS</title>
+
+ <para>If you have problems using filenames with accented
+ characters in them (like the German, French or Scandinavian
+ character sets) then I recommmend you look at the "valid chars"
+ option in smb.conf and also take a look at the validchars
+ package in the examples directory.</para>
+ </sect2>
+
+</sect1>
+</chapter>
diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml
new file mode 100644
index 0000000000..08499115be
--- /dev/null
+++ b/docs/docbook/projdoc/samba-doc.sgml
@@ -0,0 +1,22 @@
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+<!ENTITY Chapter1 SYSTEM "chapter1.sgml">
+]>
+
+<book id="Samba-Project-Documentation">
+
+<title>SAMBA Project Documentation</title>
+
+<bookinfo>
+ <author>
+ <surname>SAMBA Team</surname>
+ </author>
+ <address><email>samba&commat;samba.org</email></address>
+ <pubdate>$rcsId</pubdate>
+</bookinfo>
+
+<toc></toc>
+
+
+&Chapter1;
+
+</book>