diff options
Diffstat (limited to 'docs/howto/UNIX_INSTALL.xml')
| -rw-r--r-- | docs/howto/UNIX_INSTALL.xml | 379 |
1 files changed, 379 insertions, 0 deletions
diff --git a/docs/howto/UNIX_INSTALL.xml b/docs/howto/UNIX_INSTALL.xml new file mode 100644 index 0000000000..a4ba1c0aa7 --- /dev/null +++ b/docs/howto/UNIX_INSTALL.xml @@ -0,0 +1,379 @@ +<chapter id="install"> +<chapterinfo> + &author.tridge; + &author.jelmer; + &author.jht; + &author.kauer; + &author.danshearer; + <!-- Isn't some of this written by others as well? --> + +</chapterinfo> + +<title>How to Install and Test SAMBA</title> + +<sect1> + <title>Obtaining and Installing Samba</title> + + <para> + Binary packages of Samba are included in almost any Linux or + UNIX distribution. There are also some packages available at + <ulink url="http://samba.org/">the Samba home-page</ulink>. Refer to + the manual of your operating system for details on installing packages + for your specific operating system. + </para> + + <para>If you need to compile Samba from source, check + <link linkend="compiling">How to compile Samba</link> chapter.</para> + +</sect1> + +<sect1> + <title>Configuring Samba (smb.conf)</title> + + <para> + Samba's configuration is stored in the &smb.conf; file, which + usually resides in <filename>/etc/samba/smb.conf</filename> + or <filename>/usr/local/samba/lib/smb.conf</filename>. You can either + edit this file yourself or do it using one of the many graphical + tools that are available, such as the Web-based interface SWAT, that + is included with Samba. + </para> + + <sect2> + <title>Configuration file syntax</title> + + <para>The &smb.conf; file uses the same syntax as the various old + .ini files in Windows 3.1: Each file consists of various sections, + which are started by putting the section name between brackets ([]) + on a new line. Each contains zero or more key/value-pairs separated by an + equality sign (=). The file is just a plain-text file, so you can + open and edit it with your favorite editing tool.</para> + + <para>Each section in the &smb.conf; file represents a share + on the Samba server. The section <quote>global</quote> is special, since it + contains settings that apply to the whole Samba server and not + to one share in particular.</para> + +<para><link linkend="smbconfminimal">Following example</link> contains a very minimal &smb.conf;. + <indexterm><primary>minimal configuration</primary></indexterm> +</para> + + <smbconfexample id="smbconfminimal"> + <title>A minimal smb.conf</title> + + <smbconfsection>[global]</smbconfsection> + <smbconfoption><name>workgroup</name><value>WKG</value></smbconfoption> + <smbconfoption><name>netbios name</name><value>MYNAME</value></smbconfoption> + <smbconfsection>[share1]</smbconfsection> + <smbconfoption><name>path</name><value>/tmp</value></smbconfoption> + + <smbconfsection>[share2]</smbconfsection> + <smbconfoption><name>path</name><value>/my_shared_folder</value></smbconfoption> + <smbconfoption><name>comment</name><value>Some random files</value></smbconfoption> + </smbconfexample> + +</sect2> + +<sect2> + <title>Starting Samba</title> + + <para> + Samba essentially consists of two or three daemons. A daemon is a UNIX application that runs in the background and provides services. + An example of a service is the Apache Web server for which the daemon is called <command>httpd</command>. In the case of Samba there + are three daemons, two of which are needed as a minimum. + </para> + + <para> + The Samba server is made up of the following daemons: + </para> + + <variablelist> + <varlistentry><term>nmbd</term> + <listitem><para> + <indexterm><primary>smbd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>smbd</secondary></indexterm> + This daemon handles all name registration and resolution requests. It is the primary vehicle involved + in network browsing. It handles all UDP based protocols. The <command>nmbd</command> daemon should + be the first command started as part of the Samba start-up process. + </para></listitem> + </varlistentry> + + <varlistentry><term>smbd</term> + <listitem><para> + <indexterm><primary>nmbd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>nmbd</secondary></indexterm> + This daemon handles all TCP/IP based connection services for file and print based operations. It also + manages local authentication. It should be started immediately following the start-up of <command>nmbd</command>. + </para></listitem> + </varlistentry> + + <varlistentry><term>winbindd</term> + <listitem><para> + <indexterm><primary>winbindd</primary></indexterm> + <indexterm><primary>starting samba</primary><secondary>winbindd</secondary></indexterm> + This daemon should be started when Samba is a member of a Windows NT4 or ADS Domain. IT is also needed when + Samba has trust relationships with another Domain. The <command>winbindd</command> daemon will check the + &smb.conf; file for the presence of the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> + parameters. If they are not found <command>winbindd</command> will bail-out and refuse to start. + </para></listitem> + </varlistentry> + </variablelist> + + <para> + When Samba has been packages by an operating system vendor the start-up process is typically a custom feature of its + integration into the platform as a whole. Please refer to your operating system platform administration manuals for + specific information pertaining to correct management of Samba start-up. + </para> + +</sect2> + +<sect2> + <title>Example Configuration</title> + + <para> + There are sample configuration files in the examples subdirectory in the + distribution. It is suggested you read them carefully so you can see how the options + go together in practice. See the man page for all the options. + It might be worthwhile to start out with the smb.conf.default + configuration file and adapt it to your needs. It contains plenty of + comments. + </para> + + <para> + The simplest useful configuration file would contain something like shown in + <link linkend="simple-example">the next example</link>. + </para> + + <para> + <indexterm><primary>simple configuration</primary></indexterm> + <smbconfexample id="simple-example"> + <title>Another simple smb.conf File</title> +<smbconfsection>[global]</smbconfsection> +<smbconfoption><name>workgroup</name><value>&example.workgroup;</value></smbconfoption> + +<smbconfsection>[homes]</smbconfsection> +<smbconfoption><name>guest ok</name><value>no</value></smbconfoption> +<smbconfoption><name>read only</name><value>no</value></smbconfoption> + </smbconfexample> + </para> + + <para> + This will allow connections by anyone with an account on the server, using either + their login name or <smbconfsection>homes</smbconfsection> as the service name. + (Note: The workgroup that Samba should appear in must also be set. The default + workgroup name is WORKGROUP.) + </para> + + <para> + Make sure you put the &smb.conf; file in the correct place. + </para> + + <para> + For more information about security settings for the + <smbconfsection>[homes]</smbconfsection> share please refer to + <link linkend="securing-samba">Securing Samba</link> chapter. + </para> + +<sect3> + <title>Test Your Config File with <command>testparm</command></title> + + <para> + It's important to validate the contents of the &smb.conf; file using the &testparm; program. + If testparm runs correctly, it will list the loaded services. If not, it will give an error message. + Make sure it runs correctly and that the services look reasonable before proceeding. Enter the command: + </para> + + <screen> + &rootprompt; testparm /etc/samba/smb.conf + </screen> + + <para>Testparm will parse your configuration file and report + any unknown parameters or incorrect syntax. </para> + + + + <para> + Always run testparm again whenever the &smb.conf; file is changed! + </para> + +</sect3> +</sect2> + +<sect2> + <title>SWAT</title> + + <para> + <indexterm><primary>swat</primary></indexterm> + SWAT is a Web-based interface that can be used to facilitate the configuration of Samba. + SWAT might not be available in the Samba package that shipped with your platform, + but in a separate package. Please read the SWAT man page + on compiling, installing and configuring SWAT from source. + </para> + + <para> + To launch SWAT, just run your favorite Web browser and point it to + <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>. + Replace <replaceable>localhost</replaceable> with the name of the computer on which + Samba is running if that is a different computer than your browser. + </para> + + <para> + SWAT can be used from a browser on any IP-connected machine, but be aware that connecting from a remote + machine leaves your connection open to password sniffing as passwords will be sent over the wire in the clear. + </para> + + <para>More information about SWAT can be found in <link linkend="SWAT">corresponding chapter</link>.</para> + +</sect2> + +</sect1> + +<sect1> + <title>List Shares Available on the Server</title> + + <para> + To list shares that are available from the configured Samba server execute the + following command: + </para> + +<para><screen> +&prompt;<userinput>smbclient -L <replaceable>yourhostname</replaceable></userinput> +</screen></para> + + <para>You should see a list of shares available on your server. If you do not, then + something is incorrectly configured. This method can also be used to see what shares + are available on other SMB servers, such as Windows 2000.</para> + + <para>If you choose user-level security 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 + <option>-N</option> to the command line. </para> +</sect1> + +<sect1> + <title>Connect with a UNIX Client</title> + + <para> + Enter the following command: +<screen> +&prompt;<userinput>smbclient <replaceable> //yourhostname/aservice</replaceable></userinput> +</screen></para> + + <para>Typically <replaceable>yourhostname</replaceable> is the name of the host on which &smbd; + has been installed. The <replaceable>aservice</replaceable> is any service that has been defined in the &smb.conf; + file. Try your user name if you just have a <smbconfsection>[homes]</smbconfsection> section in the &smb.conf; file.</para> + + <para>Example: If the UNIX host is called <replaceable>bambi</replaceable> and a valid login name + is <replaceable>fred</replaceable>, you would type:</para> + +<para><screen> +&prompt;<userinput>smbclient //<replaceable>bambi</replaceable>/<replaceable>fred</replaceable></userinput> +</screen></para> +</sect1> + +<sect1> + <title>Connect from a Remote SMB Client</title> + + <para>Now that Samba is working correctly locally, you can try to + access it from other clients. Within a few minutes, the Samba host + should be listed in the Network Neighborhood on all Windows + clients of its subnet. Try browsing the server from another client + or 'mounting' it.</para> + + <para>Mounting disks from a DOS, Windows or OS/2 client can be done by running a command such as:</para> + + <para><screen> +&dosprompt;<userinput>net use d: \\servername\service</userinput> +</screen></para> + + <para>Try printing, e.g.</para> + + <para> +<screen> +&dosprompt;<userinput>net use lpt1: \\servername\spoolservice</userinput> +</screen></para> + +<para> +<screen>&dosprompt;<userinput>print filename</userinput> +</screen></para> +</sect1> + +<sect1> + <title>What If Things Don't Work?</title> + + <para>You might want to read <link linkend="diagnosis">The Samba Checklist</link>. + If you are still stuck, refer to <link linkend="problems">Analyzing and Solving Samba Problems</link> chapter. + Samba has been successfully installed at thousands of sites worldwide. + It is unlikely that your particular problem is unique, so it might be + productive to perform an Internet search to see if someone else has encountered + your problem and has found a way to overcome it.</para> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +The following questions and issues are raised repeatedly on the Samba mailing list. +</para> + +<sect2> + <title>Large Number of smbd Processes</title> + +<para> +Samba consists of three core programs: &nmbd;, &smbd;, and &winbindd;. &nmbd; is the name server message daemon, +&smbd; is the server message daemon, and &winbindd; is the daemon that handles communication with Domain Controllers. +</para> + +<para> +If Samba is <emphasis>not</emphasis> running as a WINS server, then there will be one single instance of + &nmbd; running on your system. If it is running as a WINS server then there will be +two instances &smbmdash; one to handle the WINS requests. +</para> + +<para> +&smbd; handles all connection requests. It spawns a new process for each client +connection made. That is why you may see so many of them, one per client connection. +</para> + +<para> +&winbindd; will run as one or two daemons, depending on whether or not it is being +run in <emphasis>split mode</emphasis> (in which case there will be two instances). +</para> + +</sect2> + + <sect2> + <title>Error Message: open_oplock_ipc</title> + + <para>An error message is observed in the log files when &smbd; is started: <quote>open_oplock_ipc: Failed to get local UDP socket + for address 100007f. Error was Cannot assign requested.</quote></para> + + <para>Your loopback device isn't working correctly. Make sure it is configured correctly. The loopback + device is an internal (virtual) network device with the IP address <emphasis>127.0.0.1</emphasis>. + Read your OS documentation for details on how to configure the loopback on your system.</para> + + </sect2> + + <sect2> + <title><quote><errorname>The network name cannot be found</errorname></quote></title> + + <para> + This error can be caused by one of these mis-configurations: + </para> + + <itemizedlist> + <listitem><para>You specified an non-existing path + for the share in &smb.conf;.</para></listitem> + + <listitem><para>The user you are trying to access the share with does not + have sufficient permissions to access the path for + the share. Both read (r) and access (x) should be possible.</para></listitem> + + <listitem><para>The share you are trying to access does not exist.</para></listitem> + </itemizedlist> + + </sect2> +</sect1> + +</chapter> |