Renamed from INSTALL.txt. Preparing for new docs structure.

Dan
(This used to be commit 98729b09094bf20678a849efe02de64696f48bc8)

1 files changed, 342 insertions, 0 deletions

diff --git a/docs/textdocs/UNIX_INSTALL.txt b/docs/textdocs/UNIX_INSTALL.txt
new file mode 100644
index 0000000000..ee305dc2dc
--- /dev/null
+++ b/docs/textdocs/UNIX_INSTALL.txt
@@ -0,0 +1,342 @@
+Contributor:	Andrew Tridgell <samba-bugs@samba.anu.edu.au>
+Date:		Unknown
+Status:		Current
+
+Subject:	HOW TO INSTALL AND TEST SAMBA
+===============================================================================
+
+
+STEP 0. Read the man pages. They 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:
+
+	nroff -man smbd.8 | more
+
+Unfortunately, having said this, the man pages are sadly out of date and
+really need more effort to maintain them. Other sources of information 
+are pointed to by the Samba web site, http://samba.canberra.edu.au/pub/samba.
+
+STEP 1. Building the binaries
+
+To do this, first edit the file source/Makefile. You will find that
+the Makefile has an entry for most unixes and you need to uncomment
+the one that matches your operating system.
+
+You should also edit the section at the top of the Makefile which
+determines where things will be installed. You need to get this right
+before compilation as Samba needs to find some things at runtime
+(smbrun in particular). There are also settings for where you want
+your log files etc. Make sure you get these right, and that the
+directories exist.
+
+Then type "make". This will create the binaries.
+
+Once it's successfully compiled you can use "make install" to install
+the binaries and manual pages. You can separately install the binaries
+and/or man pages using "make installbin" and "make installman".
+
+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 "make revert" if you find this version a disaster!
+
+STEP 2. The all important step
+
+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.
+
+If you have installed samba before then you can skip this step.
+
+STEP 3. Create the smb configuration file. 
+
+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.
+
+The simplest useful configuration file would be something like this:
+
+   workgroup = MYGROUP
+
+   [homes]
+      guest ok = no
+      read only = no
+
+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)
+
+Note that "make install" will not install a smb.conf file. You need to
+create it yourself. You will also need to create the path you specify
+in the Makefile for the logs etc, such as /usr/local/samba.
+
+Make sure you put the smb.conf file in the same place you specified in
+the Makefile.
+
+STEP 4. Test your config file with testparm
+
+It's important that you test the validity of your smb.conf file using
+the testparm program. If testparm runs OK then it will list the loaded
+services. If not it will give an error message.
+
+Make sure it runs OK and that the services look resonable before
+proceeding. 
+
+STEP 5. Starting the smbd and nmbd. 
+
+You must choose to start smbd and nmbd either as daemons or from
+inetd. Don't try to do both!  Either you can put them in inetd.conf
+and have them started on demand by inetd, or you can start them as
+daemons either from the command line or in /etc/rc.local. See the man
+pages for details on the command line options.
+
+The main advantage of starting smbd and nmbd as a daemon is that they
+will respond slightly more quickly to an initial connection
+request. This is, however, unlilkely to be a problem.
+
+Step 5a. Starting from inetd.conf
+
+NOTE; The following will be different if you use NIS or NIS+ to
+distributed services maps.
+
+Look at your /etc/services. What is defined at port 139/tcp. If
+nothing is defined then add a line like this:
+
+netbios-ssn     139/tcp
+
+similarly for 137/udp you should have an entry like:
+
+netbios-ns	137/udp
+
+Next edit your /etc/inetd.conf and add two lines something like this:
+
+netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd 
+netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd 
+
+The exact syntax of /etc/inetd.conf varies between unixes. Look at the
+other entries in inetd.conf for a guide.
+
+NOTE: Some unixes already have entries like netbios_ns (note the
+underscore) in /etc/services. You must either edit /etc/services or
+/etc/inetd.conf to make them consistant.
+
+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
+ifconfig as root if you don't know what the broadcast is for your
+net. nmbd tries to determine it at run time, but fails on some
+unixes. See the section on "testing nmbd" for a method of finding if
+you need to do this.
+
+!!!WARNING!!! Many unixes only accept around 5 parameters on the
+command line in inetd. This means you shouldn't use spaces between the
+options and arguments, or you should use a script, and start the
+script from inetd.
+
+Restart inetd, perhaps just send it a HUP. If you have installed an
+earlier version of nmbd then you may need to kill nmbd as well.
+
+Step 5b. Alternative: starting it as a daemon
+
+To start the server as a daemon you should create a script something
+like this one, perhaps calling it "startsmb"
+
+#!/bin/sh
+/usr/local/samba/bin/smbd -D 
+/usr/local/samba/bin/nmbd -D 
+
+then make it executable with "chmod +x startsmb"
+
+You can then run startsmb by hand or execute it from /etc/rc.local
+
+To kill it send a kill signal to the processes nmbd and smbd.
+
+NOTE: If you use the SVR4 style init system then you may like to look
+at the examples/svr4-startup script to make Samba fit into that system.
+
+
+STEP 6. Try listing the shares available on your server
+
+smbclient -L yourhostname 
+
+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).
+
+If you choose user level security then you may find that Samba requests
+a password before it will list the shares. See the smbclient docs 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)
+
+STEP 7. try connecting with the unix client. eg:
+
+smbclient '\\yourhostname\aservice'
+
+Typically the "yourhostname" would be the name of the host where you
+installed smbd. The "aservice" is any service you have defined in the
+smb.conf file. Try your user name if you just have a [homes] section
+in smb.conf.
+
+For example if your unix host is bambi and your login name is fred you
+would type:
+
+smbclient '\\bambi\fred'
+
+NOTE: The number of slashes to use depends on the type of shell you
+use. You may need '\\\\bambi\\fred' with some shells.
+
+STEP 8. Try connecting from a dos/WfWg/Win95/NT/os-2 client. Try
+mounting disks. eg:
+
+net use d: \\servername\service
+
+Try printing. eg:
+
+net use lpt1: \\servername\spoolservice
+print filename
+
+Celebrate, or send me a bug report!
+
+WHAT IF IT DOESN'T WORK?
+========================
+
+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.
+
+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.
+
+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. 
+
+DIAGNOSING PROBLEMS
+===================
+
+If you have instalation problems then go to DIAGNOSIS.txt to try to
+find the problem.
+
+SCOPE IDs
+=========
+
+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 <scope> 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.
+
+
+CHOOSING THE PROTOCOL LEVEL
+===========================
+
+The SMB protocol has many dialects. Currently Samba supports 5, called
+CORE, COREPLUS, LANMAN1, LANMAN2 and NT1.
+
+You can choose what maximum protocol to support in the smb.conf
+file. The default is NT1 and that is the best for the vast majority of
+sites.
+
+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.
+
+The main advantage of LANMAN2 and NT1 is support for long filenames with some
+clients (eg: smbclient, Windows NT or Win95). 
+
+See the smb.conf manual page for more details.
+
+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.
+
+
+PRINTING FROM UNIX TO A CLIENT PC
+=================================
+
+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.
+
+There is also a SYSV style script that does much the same thing called
+smbprint.sysv. It contains instructions.
+
+
+LOCKING
+=======
+
+One area which sometimes causes trouble is locking.
+
+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.
+
+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.
+
+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.
+
+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. 
+
+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.
+
+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 it's 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.
+
+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).
+
+
+MAPPING USERNAMES
+=================
+
+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.
+
+
+OTHER CHARACTER SETS
+====================
+
+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.