The Samba configuration file, called smb.conf by default, uses the same format as Windows .ini files. If you have ever worked with a .ini file, you will find smb.conf easy to create and modify. Even if you haven't, you will find the format to be simple and easy to learn. Here is an example of a Samba configuration file:
[global] workgroup = METRAN encrypt passwords = yes wins support = yes log level = 1 max log size = 1000 read only = no [homes] browsable = no map archive = yes [printers] path = /var/tmp printable = yes min print space = 2000 [test] browsable = yes read only = yes path = /usr/local/samba/tmp
This configuration file is based on the one we created in Chapter 2 and sets up a workgroup in which Samba authenticates users using encrypted passwords and the default user-level security method. Samba is providing WINS name server support. We've configured very basic event logging to use a log file not to exceed 1MB in size. The [homes] share has been added to allow Samba to create a disk share for the home directory of each user who has a standard Unix account on the server. In addition, each printer registered on the server will be publicly available, as will a single read-only share that maps to the /usr/local/samba/tmp directory.
Let's take another look at this configuration file, this time from a higher level:
[global] ... [homes] ... [printers] ... [test] ...
The names inside the square brackets delineate unique sections of the smb.conf file; each section names the share (or service) to which the section refers. For example, the [test] and [homes] sections are unique disk shares; they contain options that map to specific directories on the Samba server. The [printers] share contains options that map to various printers on the server. All the sections defined in the smb.conf file, with the exception of the [global] section, will be available as a disk or printer share to clients connecting to the Samba server.
option = value
volume = The Big Bad Hard Drive Number 3543
netbios aliases = sales, accounting, payroll netbios aliases = sales accounting payroll
You can continue a line in the Samba configuration file using the backslash, like this:
comment = The first share that has the primary copies \ of the new Teamworks software product.
# This is the printers section. We have given a minimum print ; space of 2000 to prevent some errors that we've seen when ; the spooler runs out of space. [printers] public = yes min print space = 2000
WARNING
path = /d # server's data partition
TIP
Having Samba check the configuration file automatically can be convenient, but it also means that if you edit smb.conf directly, you might be immediately changing your network's configuration every time you save the file. If you're making anything more than a minor change, it may be wiser to copy smb.conf to a temporary file, edit that, run testparm filename to check it, and then copy the temporary file back to smb.conf. That way, you can be sure to put all your changes into effect at once, and only after you are confident that you have created the exact configuration you wish to implement.
If you don't want to wait for the configuration file to be reloaded automatically, you can force a reload either by sending a hangup signal to the smbd and nmbd processes or simply by restarting the daemons. Actually, it can be a good idea to restart the daemons because it forces the clients to disconnect and reconnect, ensuring that the new configuration is applied to all clients. We showed you how to restart the daemons in Chapter 2, and sending them a hangup (HUP) signal is very similar. On Linux, it can be done with the command:
# killall -HUP smbd nmbd
In this case, not all changes will be immediately recognized by clients. For example, changes to a share that is currently in use will not be registered until the client disconnects and reconnects to that share. In addition, server-specific parameters such as the workgroup or NetBIOS name of the server will not go into effect immediately either. (This behavior was implemented intentionally because it keeps active clients from being suddenly disconnected or encountering unexpected access problems while a session is open.)
[pub] path = /home/ftp/pub/%a
The %a stands for the client system's architecture and will be replaced as shown in Table 6-1.
Client operating system ("architecture") |
Replacement string |
---|---|
Windows for Workgroups |
WfWg |
Windows 95 and Windows 98 |
Win95 |
Windows NT |
WinNT |
Windows 2000 and Windows XP |
Win2K |
Samba |
Samba |
Any OS not listed earlier |
UNKNOWN |
/home/ftp/pub/WfwG /home/ftp/pub/Win95 /home/ftp/pub/WinNT /home/ftp/pub/Win2K /home/ftp/pub/Samba /home/ftp/pub/UNKNOWN
Using variables in this manner comes in handy if you wish to have different users run custom configurations based on their own unique characteristics or conditions. Samba has 20 variables, as shown in Table 6-2.
Variable |
Definition |
---|---|
Client variables |
|
Client's architecture (see Table 6-1) |
|
Client's IP address (e.g., 172.16.1.2) |
|
Client's NetBIOS name |
|
Client's DNS name |
|
User variables |
|
Current Unix username |
|
Requested client username (not always used by Samba) |
|
Home directory of %u |
|
Primary group of %u |
|
Primary group of %U |
|
Share variables |
|
Current share's name |
|
Current share's root directory |
|
Automounter's path to the share's root directory, if different from %P |
|
Server variables |
|
Current server process ID |
|
Samba server's DNS hostname |
|
Samba server's NetBIOS name |
|
Home directory server, from the automount map |
|
Samba version |
|
Miscellaneous variables |
|
The SMB protocol level that was negotiated |
|
The current date and time |
|
The value of environment variable var |
Here's another example of using variables: let's say there are five clients on your network, but one client, maya, requires a slightly different [homes] configuration. With Samba, it's simple to handle this:
[homes] ... include = /usr/local/samba/lib/smb.conf.%m ...
You can use the variables in Table 6-2 to give custom values to a variety of Samba options. We will highlight several of these options as we move through the next few chapters.
The [global] section appears in virtually every Samba configuration file, even though it is not mandatory. There are two purposes for the [global] section. Server-wide settings are defined here, and any options that apply to shares will be used as a default in all share definitions, unless overridden within the share definition.
To illustrate this, let's again look at the example at the beginning of the chapter:
[global] workgroup = METRAN encrypt passwords = yes wins support = yes log level = 1 max log size = 1000 read only = no [homes] browsable = no map archive = yes [printers] path = /var/tmp printable = yes min print space = 2000 [test] browsable = yes read only = yes path = /usr/local/samba/tmp
If a client attempts to connect to a share that doesn't appear in the smb.conf file, Samba will search for a [homes] share in the configuration file. If a [homes] share exists, the unresolved share name is assumed to be a Unix username. If that username appears in the password database on the Samba server, Samba assumes the client is a Unix user trying to connect to her home directory on the server.
The process of using the [homes] section to create users (and dealing with their passwords) is discussed in more detail in Chapter 9.
The third special section is called [printers] and is similar to [homes]. If a client attempts to connect to a share that isn't in the smb.conf file and its name can't be found in the password file, Samba will check to see if it is a printer share. Samba does this by reading the printer capabilities file (usually /etc/printcap) to see if the share name appears there.[1] If it does, Samba creates a share named after the printer.
This means that as with [homes], you don't have to maintain a share for each system printer in the smb.conf file. Instead, Samba honors the Unix printer registry if you ask it to, and it provides the registered printers to the client systems. However, there is a potential difficulty: if you have an account named fred and a printer named fred, Samba will always find the user account first, even if the client really needed to connect to the printer.
The process of setting up the [printers] share is discussed in more detail in Chapter 10.
In addition, configuration options can take three kinds of values. They are as follows:
This is a string of case-sensitive characters, such as a filename or a username.
You can instruct Samba to include or replace configuration options as it is processing them. The options to do this are summarized in Table 6-3.
Option |
Parameters |
Function |
Default |
Scope |
---|---|---|---|---|
config file |
string (name of file) |
Sets the location of a configuration file to use instead of the current one |
None |
Global |
include |
string (name of file) |
Specifies an additional set of configuration options to be included in the configuration file |
None |
Global |
copy |
string (name of share) |
Allows you to clone the configuration options of another share in the current share |
None |
Share |
The global config file option specifies a replacement configuration file that will be loaded when the option is encountered. If the target file exists, the remainder of the current configuration file, as well as the options encountered so far, will be discarded, and Samba will configure itself entirely with the options in the new file. Variables can be used with the config file option, which is useful in the event that you want to use a special configuration file based on the NetBIOS machine name or user of the client that is connecting.
[global] config file = /usr/local/samba/lib/smb.conf.%m
This option, discussed in greater detail earlier, copies the target file into the current configuration file at the point specified, as shown in Figure 6-1. This option also can be used with variables. You can use this option as follows:
[global] include = /usr/local/samba/lib/smb.conf.%m
If the configuration file specified does not exist, the option is ignored. Options in the include file override any option specified previously, but not options that are specified later. In Figure 6-1, all three options will override their previous values.
The copy configuration option allows you to clone the configuration options of the share name that you specify in the current share. The target share must appear earlier in the configuration file than the share that is performing the copy. For example:
[template] writable = yes browsable = yes valid users = andy, dave, jay [data] path = /usr/local/samba copy = template
Note that any options in the share that invoked the copy directive will override those in the cloned share; it does not matter whether they appear before or after the copy directive.
[global] # Server configuration parameters netbios name = toltec server string = Samba %v on %L workgroup = METRAN encrypt passwords = yes
TIP
If you like, you can go ahead and try this configuration file. Create a file named smb.conf under the /usr/local/samba/lib directory with the text listed earlier. Then restart the Samba server and use a Windows client to verify the results. Be sure that your Windows clients are in the METRAN workgroup as well. After double-clicking the Network Neighborhood on a Windows client, you should see a window similar to Figure 6-2. (In this figure, Mixtec is another Samba server, and Zapotec is a Windows client.)
You can verify the server string by listing the details of the Network Neighborhood window (select Details in the View menu). You should see a window similar to Figure 6-3.
Table 6-4 summarizes the server configuration options introduced previously. All three of these options are global in scope, so they must appear in the [global] section of the configuration file.
Option |
Parameters |
Function |
Default |
Scope |
---|---|---|---|---|
netbios name |
string |
NetBIOS name of the Samba server |
Server's unqualified DNS hostname |
Global |
workgroup |
string |
NetBIOS group to which the server belongs |
Defined at compile time |
Global |
server string |
string |
Descriptive string for the Samba server |
Samba %v |
Global |
The netbios name option allows you to set the NetBIOS name of the server. For example:
netbios name = YORKVM1
The default value for this configuration option is the server's hostname—that is, the first part of its fully qualified domain name. For example, a system with the DNS name ruby.ora.com would be given the NetBIOS name RUBY by default. While you can use this option to restate the system's NetBIOS name in the configuration file (as we did previously), it is more commonly used to assign the Samba server a NetBIOS name other than its current DNS name. Remember that the name given must follow the rules for valid NetBIOS machine names as outlined in Chapter 1.
Changing the NetBIOS name of the server is not recommended unless you have a good reason. One such reason might be if the hostname of the system is not unique because the LAN is divided over two or more DNS domains. For example, YORKVM1 is a good NetBIOS candidate for vm1.york.example.com to differentiate it from vm1.falkirk.example.com, which has the same hostname but resides in a different DNS domain.
Another use of this option is for relocating SMB services from a dead or retired system. For example, if SALES is the SMB server for the department and it suddenly dies, you could immediately reset netbios name = SALES on a backup Samba server that's taking over for it. Users won't have to change their drive mappings to a different server; new connections to SALES will simply go to the new server.
The workgroup parameter sets the current workgroup (or domain) in which the Samba server will advertise itself. Clients that wish to access shares on the Samba server should be in the same NetBIOS group. Remember that workgroups are really just NetBIOS group names and must follow the standard NetBIOS naming conventions outlined in Chapter 1.
The default option for this parameter is set at compile time to WORKGROUP. Because this is the default workgroup name of every unconfigured Windows and Samba system, we recommend that you always set your workgroup name in the Samba configuration file. When choosing your workgroup name, try to avoid making it the same name as a server or user. This will avoid possible problems with WINS name resolution.
The server string parameter defines a comment string that will appear next to the server name in both the Network Neighborhood (when shown with the Details view) and the comment entry of the Microsoft Windows printer manager.[2]
You can use variables to provide information in the description. For example, our entry earlier was:
[global] server string = Samba %v on (%h)
The default for this option simply presents the current version of Samba and is equivalent to:
server string = Samba %v
We mentioned in the previous section that there were no disk shares on the toltec server. Let's continue building the configuration file and create an empty disk share called [data]. Here are the additions that will do it:
[data] path = /export/samba/data comment = Data Drive volume = Sample-Data-Drive writable = yes
# mkdir /export/samba/data # chmod 777 /export/samba/data
Now, if we connect to the toltec server again by double-clicking its icon in the Windows Network Neighborhood, we will see a single share entitled data, as shown in Figure 6-4. This share has read/write access, so files can be copied to or from it.
The basic Samba configuration options for disk shares previously introduced are listed in Table 6-5.
Option |
Parameters |
Function |
Default |
Scope |
---|---|---|---|---|
path (directory) |
string (directory name) |
Sets the Unix directory that will be provided for a disk share or used for spooling by a printer share. |
/tmp |
Share |
comment |
string |
Sets the comment that appears with the share. |
None |
Share |
volume |
string |
Sets the MS-DOS volume name for the share. |
Share name |
Share |
read only |
boolean |
If yes, allows read-only access to a share. |
yes |
Share |
writable (write ok or writeable) |
boolean |
If no, allows read-only access to a share. If yes, both reading and writing are allowed. |
no |
Share |
This option, which has the synonym directory, indicates the pathname for the root of the shared directory or printer. You can choose any directory on the Samba server, so long as the owner of the Samba process that is connecting has read and write access to that directory. If the path is for a printing share, it should point to a temporary directory where files can be written on the server before being spooled to the target printer ( /tmp and /var/spool are popular choices). If this path is for a disk share, the contents of the folder representing the share name on the client will match the contents of the directory on the Samba server.
The comment option allows you to enter a comment that will be sent to the client when it attempts to browse the share. The user can see the comment by using the Details view on the share folder or with the net view command at an MS-DOS prompt. For example, here is how you might insert a comment for a share:
[network] comment = Network Drive path = /export/samba/network