summaryrefslogtreecommitdiff
path: root/docs/docbook/projdoc/UNIX_INSTALL.xml
diff options
context:
space:
mode:
authorGerald Carter <jerry@samba.org>2003-09-24 15:05:22 +0000
committerGerald Carter <jerry@samba.org>2003-09-24 15:05:22 +0000
commit293421f3c64a2adff7dc15f7ad3adb6120c9fd16 (patch)
treeb18b6e0cda6e04dac9f47ab9fdb661f1dfa65b7b /docs/docbook/projdoc/UNIX_INSTALL.xml
parent43004ba8830874a8ab02bc755b1e99160af982b5 (diff)
downloadsamba-293421f3c64a2adff7dc15f7ad3adb6120c9fd16.tar.gz
samba-293421f3c64a2adff7dc15f7ad3adb6120c9fd16.tar.bz2
samba-293421f3c64a2adff7dc15f7ad3adb6120c9fd16.zip
syncing up docs, examples, & packaging from 3.0
(This used to be commit dd1348c566b4700ea01bd89639e2d3330c878167)
Diffstat (limited to 'docs/docbook/projdoc/UNIX_INSTALL.xml')
-rw-r--r--docs/docbook/projdoc/UNIX_INSTALL.xml250
1 files changed, 154 insertions, 96 deletions
diff --git a/docs/docbook/projdoc/UNIX_INSTALL.xml b/docs/docbook/projdoc/UNIX_INSTALL.xml
index 6a38e60c0e..65a26702c4 100644
--- a/docs/docbook/projdoc/UNIX_INSTALL.xml
+++ b/docs/docbook/projdoc/UNIX_INSTALL.xml
@@ -3,7 +3,8 @@
&author.tridge;
&author.jelmer;
&author.jht;
- <author><firstname>Karl</firstname><surname>Auer</surname></author>
+ &author.kauer;
+ &author.danshearer;
<!-- Isn't some of this written by others as well? -->
</chapterinfo>
@@ -11,52 +12,89 @@
<title>How to Install and Test SAMBA</title>
<sect1>
- <title>Obtaining and installing samba</title>
+ <title>Obtaining and Installing Samba</title>
<para>
- Binary packages of samba are included in almost any Linux or
+ 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 homepage</ulink>.
+ <ulink url="http://samba.org/">the Samba homepage</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">the chapter about compiling samba from scratch</link>.</para>
-
- <para>If you have already installed samba, or if your operating system
- was pre-installed with samba, then you may not need to bother with this
- chapter. On the other hand, you may want to read this chapter anyhow
- for information about updating samba.</para>
+ <para>If you need to compile Samba from source, check
+ <link linkend="compiling"></link>.</para>
</sect1>
<sect1>
- <title>Configuring samba (smb.conf)</title>
+ <title>Configuring Samba (smb.conf)</title>
<para>
- Samba's configuration is stored in the &smb.conf; file,
- that usually resides in <filename>/etc/samba/smb.conf</filename>
+ 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.
+ 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 seperated 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"/> 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>Example Configuration</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.
+ 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 be something like this:
+ The simplest useful configuration file would contain something like shown in
+ <link linkend="simple-example"></link>.
</para>
<para>
- <smbconfexample>
- <title>Simplest possible smb.conf file</title>
+ <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>
@@ -68,36 +106,41 @@
<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 that the workgroup that Samba must also be set.)
+ 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
- (usually in <filename>/etc/samba</filename>).
+ 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>.
+ <link linkend="securing-samba"></link>.
</para>
<sect3>
- <title>Test your config file with <command>testparm</command></title>
+ <title>Test Your Config File with <command>testparm</command></title>
<para>
- 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.
+ 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>
- <para>
- Make sure it runs OK and that the services look reasonable before proceeding.
- </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 when you change &smb.conf;!
+ Always run testparm again whenever the &smb.conf; file is changed!
</para>
</sect3>
@@ -107,68 +150,68 @@
<title>SWAT</title>
<para>
- SWAT is a web-based interface that helps you configure samba.
- SWAT might not be available in the samba package on your platform,
- but in a separate package. Please read the swat manpage
- on compiling, installing and configuring swat from source.
+ <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 manpage
+ on compiling, installing and configuring SWAT from source.
</para>
<para>
- To launch SWAT just run your favorite web browser and
- point it at <ulink url="http://localhost:901/" noescape="1">http://localhost:901/</ulink>. Replace
- <replaceable>localhost</replaceable>
- with the name of the computer you are running samba on if you
- are running samba on a different computer than your browser.
+ 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>
- Note that you can attach to SWAT from any IP connected
- machine but connecting from a remote machine leaves your
- connection open to password sniffing as passwords will be sent
- in the clear over the wire.
+ 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"/>.</para>
+
</sect2>
+
</sect1>
<sect1>
- <title>Try listing the shares available on your
- server</title>
+ <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 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>
+ <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>Try connecting with the unix client</title>
+ <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 the <replaceable>yourhostname</replaceable>
- would be the name of the host where you installed &smbd;.
- The <replaceable>aservice</replaceable> is
- any service you have defined in the &smb.conf;
- file. Try your user name if you just have a <smbconfsection>[homes]</smbconfsection>
- section
- in &smb.conf;.</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>For example if your unix host is <replaceable>bambi</replaceable>
- and your login name is <replaceable>fred</replaceable> you would type:</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>
@@ -176,15 +219,21 @@
</sect1>
<sect1>
- <title>Try connecting from another SMB client</title>
+ <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>Try mounting disks. from a DOS, Windows or OS/2 client, eg:</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. eg:</para>
+ <para>Try printing, e.g.</para>
<para>
<screen>
@@ -199,10 +248,12 @@
<sect1>
<title>What If Things Don't Work?</title>
- <para>Then you might read the file chapter <link linkend="diagnosis">diagnosis</link>
- and the FAQ. If you are still stuck then refer to <link linkend="problems">"Analysing and solving problems"</link>.
- Samba has been successfully installed at thousands of sites worldwide,
- so maybe someone else has hit your problem and has overcome it.</para>
+ <para>You might want to read <link linkend="diagnosis"></link>.
+ If you are still stuck, refer to <link linkend="problems"></link>.
+ 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>
@@ -210,55 +261,62 @@
<title>Common Errors</title>
<para>
-The following questions and issues get raised on the samba mailing list over and over again.
+The following questions and issues are raised repeatedly on the Samba mailing list.
</para>
<sect2>
- <title>Large number of smbd processes</title>
+ <title>Large Number of smbd Processes</title>
<para>
-Samba consists on three core programs:
-&nmbd;, &smbd;, &winbindd;. &nmbd; is the name server message daemon,
-&smbd; is the server message daemon, &winbindd; is the daemon that
-handles communication with Domain Controllers.
+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 your system is NOT running as a WINS server, then there will be one (1) single instance of
+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 (2) instances - one to handle the WINS requests.
+two instances &smbmdash; one to handle the WINS requests.
</para>
<para>
-&smbd; handles ALL connection requests and then spawns a new process for each client
-connection made. That is why you are seeing so many of them, one (1) per client connection.
+&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 "split mode" (in which case there will be two instances).
+run in <emphasis>split mode</emphasis> (in which case there will be two instances).
</para>
</sect2>
<sect2>
- <title>"open_oplock_ipc: Failed to get local UDP socket for address 100007f. Error was Cannot assign requested"</title>
- <para>Your loopback device isn't working correctly. Make sure it's configured properly. The loopback device is an internal (virtual) network device with
- the ip address 127.0.0.1. Read your OS documentation for details
- on how to configure the loopback on your system.</para>
+ <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>"<errorname>The network name cannot be found</errorname>"</title>
+ <title><quote><errorname>The network name cannot be found</errorname></quote></title>
<para>
- This error can be caused by one of these misconfigurations:
+ This error can be caused by one of these misconfigurations:
</para>
<itemizedlist>
- <listitem><para>You specified an nonexisting <smbconfoption><name>path</name></smbconfoption> for the share in &smb.conf; </para></listitem>
+ <listitem><para>You specified an nonexisting 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 <smbconfoption><name>path</name></smbconfoption> for the share. Both read (r) and access (x) should be possible.</para></listitem>
+ 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>