Various updates to inline documentation in default smb.conf file

resolves: #483703

Guenther
cvs: ----------------------------------------------------------------------

samba.spec

@@ -1,4 +1,4 @@
-%define main_release 48
+%define main_release 49
 %define samba_version 3.4.3
 %define tdb_version 1.1.3
 %define talloc_version 1.3.0
@@ -654,6 +654,10 @@ exit 0
 %{_datadir}/pixmaps/samba/logo-small.png
 
 %changelog
+* Wed Nov 25 2009 Guenther Deschner <gdeschner@redhat.com> - 3.4.3-49
+- Various updates to inline documentation in default smb.conf file
+- resolves: #483703
+
 * Thu Oct 29 2009 Guenther Deschner <gdeschner@redhat.com> - 3.4.3-48
 - Update to 3.4.3
 

smb.conf.default

@@ -1,54 +1,62 @@
-# This is the main Samba configuration file. You should read the
+# This is the main Samba configuration file. For detailed information about the
-# smb.conf(5) manual page in order to understand the options listed
+# options listed here, refer to the smb.conf(5) manual page. Samba has a huge
-# here. Samba has a huge number of configurable options (perhaps too
+# number of configurable options, most of which are not shown in this example.
-# many!) most of which are not shown in this example
 #
-# For a step to step guide on installing, configuring and using samba, 
+# The Official Samba 3.2.x HOWTO and Reference Guide contains step-by-step
-# read the Samba-HOWTO-Collection. This may be obtained from:
+# guides for installing, configuring, and using Samba:
-#  http://www.samba.org/samba/docs/Samba-HOWTO-Collection.pdf
+# http://www.samba.org/samba/docs/Samba-HOWTO-Collection.pdf
 #
-# Many working examples of smb.conf files can be found in the 
+# The Samba-3 by Example guide has working examples for smb.conf. This guide is
-# Samba-Guide which is generated daily and can be downloaded from: 
+# generated daily: http://www.samba.org/samba/docs/Samba-Guide.pdf
-#  http://www.samba.org/samba/docs/Samba-Guide.pdf
 #
-# Any line which starts with a ; (semi-colon) or a # (hash) 
+# In this file, lines starting with a semicolon (;) or a hash (#) are
-# is a comment and is ignored. In this example we will use a #
+# comments and are ignored. This file uses hashes to denote commentary and
-# for commentry and a ; for parts of the config file that you
+# semicolons for parts of the file you may wish to configure.
-# may wish to enable
 #
-# NOTE: Whenever you modify this file you should run the command "testparm"
+# Note: Run the "testparm" command after modifying this file to check for basic
-# to check that you have not made any basic syntactic errors. 
+# syntax errors.
 #
 #---------------
-# SELINUX NOTES:
+# Security-Enhanced Linux (SELinux) Notes:
 #
-# If you want to use the useradd/groupadd family of binaries please run:
+# Turn the samba_domain_controller Boolean on to allow Samba to use the useradd
+# and groupadd family of binaries. Run the following command as the root user to
+# turn this Boolean on:
 # setsebool -P samba_domain_controller on
 #
-# If you want to share home directories via samba please run:
+# Turn the samba_enable_home_dirs Boolean on if you want to share home
+# directories via Samba. Run the following command as the root user to turn this
+# Boolean on:
 # setsebool -P samba_enable_home_dirs on
 #
-# If you create a new directory you want to share you should mark it as
+# If you create a new directory, such as a new top-level directory, label it
-# "samba-share_t" so that selinux will let you write into it.
+# with samba_share_t so that SELinux allows Samba to read and write to it. Do
-# Make sure not to do that on system directories as they may already have
+# not label system directories, such as /etc/ and /home/, with samba_share_t, as
-# been marked with othe SELinux labels.
+# such directories should already have an SELinux label.
 #
-# Use ls -ldZ /path to see which context a directory has
+# Run the "ls -ldZ /path/to/directory" command to view the current SELinux
+# label for a given directory.
 #
-# Set labels only on directories you created!
+# Set SELinux labels only on files and directories you have created. Use the
-# To set a label use the following: chcon -t samba_share_t /path
+# chcon command to temporarily change a label:
+# chcon -t samba_share_t /path/to/directory
 #
-# If you need to share a system created directory you can use one of the
+# Changes made via chcon are lost when the file system is relabeled or commands
-# following (read-only/read-write):
+# such as restorecon are run.
+#
+# Use the samba_export_all_ro or samba_export_all_rw Boolean to share system
+# directories. To share such directories and only allow read-only permissions:
 # setsebool -P samba_export_all_ro on
-# or
+# To share such directories and allow read and write permissions:
 # setsebool -P samba_export_all_rw on
 #
-# If you want to run scripts (preexec/root prexec/print command/...) please
+# To run scripts (preexec/root prexec/print command/...), copy them to the
-# put them into the /var/lib/samba/scripts directory so that smbd will be
+# /var/lib/samba/scripts/ directory so that SELinux will allow smbd to run them.
-# allowed to run them.
+# Note that if you move the scripts to /var/lib/samba/scripts/, they retain
-# Make sure you COPY them and not MOVE them so that the right SELinux context
+# their existing SELinux labels, which may be labels that SELinux does not allow
-# is applied, to check all is ok use restorecon -R -v /var/lib/samba/scripts
+# smbd to run. Copying the scripts will result in the correct SELinux labels.
+# Run the "restorecon -R -v /var/lib/samba/scripts" command as the root user to
+# apply the correct SELinux labels to these files.
 #
 #--------------
 #
@@ -56,20 +64,24 @@
 
 [global]
 
-# ----------------------- Netwrok Related Options -------------------------
+# ----------------------- Network-Related Options -------------------------
 #
-# workgroup = NT-Domain-Name or Workgroup-Name, eg: MIDEARTH
+# workgroup = the Windows NT domain name or workgroup name, for example, MYGROUP.
 #
-# server string is the equivalent of the NT Description field
+# server string = the equivalent of the Windows NT Description field.
 #
-# netbios name can be used to specify a server name not tied to the hostname
+# netbios name = used to specify a server name that is not tied to the hostname.
 #
-# Interfaces lets you configure Samba to use multiple interfaces
+# interfaces = used to configure Samba to listen on multiple network interfaces.
-# If you have multiple network interfaces then you can list the ones
+# If you have multiple interfaces, you can use the "interfaces =" option to
-# you want to listen on (never omit localhost)
+# configure which of those interfaces Samba listens on. Never omit the localhost
+# interface (lo).
 #
-# Hosts Allow/Hosts Deny lets you restrict who can connect, and you can
+# hosts allow = the hosts allowed to connect. This option can also be used on a
-# specifiy it as a per share option as well
+# per-share basis.
+
+# hosts deny = the hosts not allowed to connect. This option can also be used on
+# a per-share basis.
 #
 	workgroup = MYGROUP
 	server string = Samba Server Version %v
@@ -81,22 +93,27 @@
 
 # --------------------------- Logging Options -----------------------------
 #
-# Log File let you specify where to put logs and how to split them up.
+# log file = specify where log files are written to and how they are split.
+#
+# max log size = specify the maximum size log files are allowed to reach. Log
+# files are rotated when they reach the size specified with "max log size".
 #
-# Max Log Size let you specify the max size log files should reach
 
-	# logs split per machine
+	# log files split per-machine:
 	log file = /var/log/samba/log.%m
-	# max 50KB per log file, then rotate
+	# maximum size of 50KB per log file, then rotate:
 	max log size = 50
 
 # ----------------------- Standalone Server Options ------------------------
 #
-# Scurity can be set to user, share(deprecated) or server(deprecated)
+# security = the mode Samba runs in. This can be set to user, share
+# (deprecated), or server (deprecated).
+#
+# passdb backend = the backend used to store user information in. New
+# installations should use either tdbsam or ldapsam. No additional configuration
+# is required for tdbsam. The "smbpasswd" utility is available for backwards
+# compatibility.
 #
-# Backend to store user information in. New installations should 
-# use either tdbsam or ldapsam. smbpasswd is available for backwards 
-# compatibility. tdbsam requires no further configuration.
 
 	security = user
 	passdb backend = tdbsam
@@ -104,22 +121,23 @@
 
 # ----------------------- Domain Members Options ------------------------
 #
-# Security must be set to domain or ads
+# security = must be set to domain or ads.
 #
-# Use the realm option only with security = ads
+# passdb backend = the backend used to store user information in. New
-# Specifies the Active Directory realm the host is part of
+# installations should use either tdbsam or ldapsam. No additional configuration
+# is required for tdbsam. The "smbpasswd" utility is available for backwards
+# compatibility.
 #
-# Backend to store user information in. New installations should 
+# realm = only use the realm option when the "security = ads" option is set.
-# use either tdbsam or ldapsam. smbpasswd is available for backwards 
+# The realm option specifies the Active Directory realm the host is a part of.
-# compatibility. tdbsam requires no further configuration.
 #
-# Use password server option only with security = server or if you can't
+# password server = only use this option when the "security = server"
-# use the DNS to locate Domain Controllers
+# option is set, or if you cannot use DNS to locate a Domain Controller. The
-# The argument list may include:
+# argument list can include My_PDC_Name, [My_BDC_Name], and [My_Next_BDC_Name]:
-#   password server = My_PDC_Name [My_BDC_Name] [My_Next_BDC_Name]
+#
-# or to auto-locate the domain controller/s
+# password server = My_PDC_Name [My_BDC_Name] [My_Next_BDC_Name]
-#   password server = *
+#
-	
+# Use "password server = *" to automatically locate Domain Controllers.
 
 ;	security = domain
 ;	passdb backend = tdbsam
@@ -129,25 +147,25 @@
 
 # ----------------------- Domain Controller Options ------------------------
 #
-# Security must be set to user for domain controllers
+# security = must be set to user for domain controllers.
 #
-# Backend to store user information in. New installations should 
+# passdb backend = the backend used to store user information in. New
-# use either tdbsam or ldapsam. smbpasswd is available for backwards 
+# installations should use either tdbsam or ldapsam. No additional configuration
-# compatibility. tdbsam requires no further configuration.
+# is required for tdbsam. The "smbpasswd" utility is available for backwards
+# compatibility.
 #
-# Domain Master specifies Samba to be the Domain Master Browser. This
+# domain master = specifies Samba to be the Domain Master Browser, allowing
-# allows Samba to collate browse lists between subnets. Don't use this
+# Samba to collate browse lists between subnets. Do not use the "domain master"
-# if you already have a Windows NT domain controller doing this job
+# option if you already have a Windows NT domain controller performing this task.
 #
-# Domain Logons let Samba be a domain logon server for Windows workstations. 
+# domain logons = allows Samba to provide a network logon service for Windows
+# workstations.
 #
-# Logon Scrpit let yuou specify a script to be run at login time on the client
+# logon script = specifies a script to run at login time on the client. These
-# You need to provide it in a share called NETLOGON
+# scripts must be provided in a share named NETLOGON.
 #
-# Logon Path let you specify where user profiles are stored (UNC path)
+# logon path = specifies (with a UNC path) where user profiles are stored.
 #
-# Various scripts can be used on a domain controller or stand-alone
-# machine to add or delete corresponding unix accounts
 #
 ;	security = user
 ;	passdb backend = tdbsam
@@ -155,14 +173,18 @@
 ;	domain master = yes
 ;	domain logons = yes
 
-	# the login script name depends on the machine name
+	# the following login script name is determined by the machine name
+	# (%m):
 ;	logon script = %m.bat
-	# the login script name depends on the unix user used
+	# the following login script name is determined by the UNIX user used:
 ;	logon script = %u.bat
 ;	logon path = \\%L\Profiles\%u
-	# disables profiles support by specifing an empty path
+	# use an empty path to disable profile support:
 ;	logon path =
 
+	# various scripts can be used on a domain controller or a stand-alone
+	# machine to add or delete corresponding UNIX accounts:
+
 ;	add user script = /usr/sbin/useradd "%u" -n -g users
 ;	add group script = /usr/sbin/groupadd "%g"
 ;	add machine script = /usr/sbin/useradd -n -c "Workstation (%u)" -M -d /nohome -s /bin/false "%u"
@@ -173,32 +195,36 @@
 
 # ----------------------- Browser Control Options ----------------------------
 #
-# set local master to no if you don't want Samba to become a master
+# local master = when set to no, Samba does not become the master browser on
-# browser on your network. Otherwise the normal election rules apply
+# your network. When set to yes, normal election rules apply.
 #
-# OS Level determines the precedence of this server in master browser
+# os level = determines the precedence the server has in master browser
-# elections. The default value should be reasonable
+# elections. The default value should be reasonable.
+#
+# preferred master = when set to yes, Samba forces a local browser election at
+# start up (and gives itself a slightly higher chance of winning the election).
 #
-# Preferred Master causes Samba to force a local browser election on startup
-# and gives it a slightly higher chance of winning the election
 ;	local master = no
 ;	os level = 33
 ;	preferred master = yes
 
 #----------------------------- Name Resolution -------------------------------
-# Windows Internet Name Serving Support Section:
-# Note: Samba can be either a WINS Server, or a WINS Client, but NOT both
 #
-# - WINS Support: Tells the NMBD component of Samba to enable it's WINS Server
+# This section details the support for the Windows Internet Name Service (WINS).
 #
-# - WINS Server: Tells the NMBD components of Samba to be a WINS Client
+# Note: Samba can be either a WINS server or a WINS client, but not both.
 #
-# - WINS Proxy: Tells Samba to answer name resolution queries on
+# wins support = when set to yes, the NMBD component of Samba enables its WINS
-#   behalf of a non WINS capable client, for this to work there must be
+# server.
-#   at least one	WINS Server on the network. The default is NO.
 #
-# DNS Proxy - tells Samba whether or not to try to resolve NetBIOS names
+# wins server = tells the NMBD component of Samba to be a WINS client.
-# via DNS nslookups.
+#
+# wins proxy = when set to yes, Samba answers name resolution queries on behalf
+# of a non WINS capable client. For this to work, there must be at least one
+# WINS server on the network. The default is no.
+#
+# dns proxy = when set to yes, Samba attempts to resolve NetBIOS names via DNS
+# nslookups.
 
 ;	wins support = yes
 ;	wins server = w.x.y.z
@@ -208,33 +234,36 @@
 
 # --------------------------- Printing Options -----------------------------
 #
-# Load Printers let you load automatically the list of printers rather
+# The options in this section allow you to configure a non-default printing
-# than setting them up individually
+# system.
 #
-# Cups Options let you pass the cups libs custom options, setting it to raw
+# load printers = when set you yes, the list of printers is automatically
-# for example will let you use drivers on your Windows clients
+# loaded, rather than setting them up individually.
 #
-# Printcap Name let you specify an alternative printcap file
+# cups options = allows you to pass options to the CUPS library. Setting this
+# option to raw, for example, allows you to use drivers on your Windows clients.
+#
+# printcap name = used to specify an alternative printcap file.
 #
-# You can choose a non default printing system using the Printing option
 
 	load printers = yes
 	cups options = raw
 
 ;	printcap name = /etc/printcap
-	#obtain list of printers automatically on SystemV
+	# obtain a list of printers automatically on UNIX System V systems:
 ;	printcap name = lpstat
 ;	printing = cups
 
-# --------------------------- Filesystem Options ---------------------------
+# --------------------------- File System Options ---------------------------
 #
-# The following options can be uncommented if the filesystem supports
+# The options in this section can be un-commented if the file system supports
-# Extended Attributes and they are enabled (usually by the mount option
+# extended attributes, and those attributes are enabled (usually via the
-# user_xattr). Thess options will let the admin store the DOS attributes
+# "user_xattr" mount option). These options allow the administrator to specify
-# in an EA and make samba not mess with the permission bits.
+# that DOS attributes are stored in extended attributes and also make sure that
+# Samba does not change the permission bits.
 #
-# Note: these options can also be set just per share, setting them in global
+# Note: These options can be used on a per-share basis. Setting them globally
-# makes them the default for all shares
+# (in the [global] section) makes them the default for all shares.
 
 ;	map archive = no
 ;	map hidden = no
@@ -260,7 +289,7 @@
 	writable = no
 	printable = yes
 
-# Un-comment the following and create the netlogon directory for Domain Logons
+# Un-comment the following and create the netlogon directory for Domain Logons:
 ;	[netlogon]
 ;	comment = Network Logon Service
 ;	path = /var/lib/samba/netlogon
@@ -268,17 +297,15 @@
 ;	writable = no
 ;	share modes = no
 
-	
+# Un-comment the following to provide a specific roving profile share.
-# Un-comment the following to provide a specific roving profile share
+# The default is to use the user's home directory:
-# the default is to use the user's home directory
 ;	[Profiles]
 ;	path = /var/lib/samba/profiles
 ;	browseable = no
 ;	guest ok = yes
 
-	
+# A publicly accessible directory that is read only, except for users in the
-# A publicly accessible directory, but read only, except for people in
+# "staff" group (which have write permissions):
-# the "staff" group
 ;	[public]
 ;	comment = Public Stuff
 ;	path = /home/samba