Chapter 6. The Samba Configuration File

Occasionally, +we need to find out what Samba is up to. This is especially true when +Samba is performing an unexpected action or is not performing at all. +To find out this information, we need to check +Samba's log files to see exactly why it did what it +did.

Samba log files +can be as brief or verbose as you like. Here is an example of what a +Samba log file looks like:

[2002/07/21 13:23:25, 3] smbd/service.c:close_cnum(514)
+  maya (172.16.1.6) closed connection to service IPC$
+[2002/07/21 13:23:25, 3] smbd/connection.c:yield_connection(40)
+  Yielding connection to IPC$
+[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
+  Transaction 923 of length 49
+[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
+  switch message SMBread (pid 467)
+[2002/07/21 13:23:25, 3] lib/doscalls.c:dos_ChDir(336)
+  dos_ChDir to /home/samba
+[2002/07/21 13:23:25, 3] smbd/reply.c:reply_read(2199)
+  read fnum=4207 num=2820 nread=2820
+[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
+  Transaction 924 of length 55
+[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
+  switch message SMBreadbraw (pid 467)
+[2002/07/21 13:23:25, 3] smbd/reply.c:reply_readbraw(2053)
+  readbraw fnum=4207 start=130820 max=1276 min=0 nread=1276
+[2002/07/21 13:23:25, 3] smbd/process.c:process_smb(615)
+  Transaction 925 of length 55
+[2002/07/21 13:23:25, 3] smbd/process.c:switch_message(448)
+  switch message SMBreadbraw (pid 467)

Much of this information is of use only to Samba programmers. +However, we will go over the meaning of some of these entries in more +detail in Chapter 12.

+ +

Samba contains six options that allow users to describe how and where +logging information should be written. Each of these are global +options and cannot appear inside a share definition. Here is an +example of some logging options that we are adding to our +configuration file:

+ +

[global]
+    log level = 2
+    log file = /var/log/samba.log.%m
+    max log size = 50
+    debug timestamp = yes

+ +

Here, we've added a custom log file that reports +information up to debug level 2. This is a relatively light debugging +level. The logging level ranges from 1 to 10, where level 1 provides +only a small amount of information and level 10 provides a plethora +of low-level information. Levels 2 or 3 will provide us with useful +debugging information without wasting disk space on our server. In +practice, you should avoid using log levels greater than 3 unless you +are working on the Samba source code.

+ +

The logging file is located in the /var/log +directory thanks to the log +file configuration option. However, we can use +variable substitution to create log files specifically for individual +users or clients, such as with the %m variable in +the following line:

+ +

log file = /usr/local/logs/samba.log.%m

+ +

Isolating the log messages can be invaluable in tracking down a +network error if you know the problem is coming from a specific +client system or user.

+ +

We've added a precaution to the log files: no one +log file can exceed 50 KB in size, as specified by the +max log size +option. If a log file exceeds this size, the contents are moved to a +file with the same name but with the suffix .old +appended. If the .old file already exists, it is +overwritten and its contents are lost. The original file is cleared, +waiting to receive new logging information. This prevents the hard +drive from being overwhelmed with Samba log files during the life of +the Samba daemons.

+ +

We have decided to write the timestamps of the messages in the logs +with the debug timestamp +option, which is the default behavior. This will place a timestamp in +each message written to the logging file. If we were not interested +in this information, we could specify no for this +option instead.

+ + +

Using syslog

If you wish to use the system logger +(syslog +) in addition to or in place of the standard Samba logging +file, Samba provides options for this as well. However, to use +syslog, the first thing you will have to do is make sure that Samba +was built with the configure +--with-syslog option. See Chapter 2 for more information on configuring and +compiling Samba. See Appendix E for more +information about the --with-syslog option.

+ +

Once that is done, you will need to configure your +/etc/syslog.conf to accept logging information from Samba. +If there is not already a daemon.* entry in the +/etc/syslog.conf file, add the following:

daemon.*        /var/log/daemon.log

This specifies that any logging information from system daemons will +be stored in the /var/log/daemon.log file. This +is where the Samba information will be stored as well. From there, +you can set a value for the syslog parameter in +your Samba configuration file to specify which logging messages are +to be sent to syslog. Only messages that have debug levels lower than +the value of the syslog parameter will be sent to +syslog. For example, setting the following:

syslog = 3

specifies that any logging messages with a level of 2 or below will +be sent to both syslog and the Samba logging files. (The mappings to +syslog priorities are described in the upcoming +section "syslog.") To continue the +example, let's assume that we have set the +log level option to 4. Logging +messages with levels of 2 and 1 will be sent to both syslog and the +Samba logging files, and messages with a level of 3 or 4 will be sent +to the Samba logging files, but not to syslog. If the +syslog value exceeds the log +level value, nothing will be sent to syslog.

If you want to specify that messages be sent only to syslog—and +not to the standard Samba logging files—you can place this +option in the configuration file:

syslog only = yes

If this is the case, any logging information above the number +specified in the syslog option will be discarded, +as with the log level option.

Logging Configuration Options

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Table 6-8 lists each logging configuration option +that Samba can use.

+ +

Table 6-8. Logging configuration options

+ Option +	+ Parameters +	+ Function +	+ Default +	+ Scope +
+ `log file` +	+ string (name of file) +	+ Name of the log file that Samba is to use. Works with all variables. +	+ Specified in Samba makefile +	+ Global +
+ `log level` + + `(debug level)` +	+ numeric (0-10) +	+ Amount of log/debug messages that are sent to the log file. 0 is +none; 3 is considerable. +	+ `1` +	+ Global +
+ `max log size` +	+ numeric (size in KB) +	+ Maximum size of log file. +	+ `5000` +	+ Global +
+ `debug timestamp` `(timestamp logs)` +	+ boolean +	+ If `no`, doesn't timestamp logs, +making them easier to read during heavy debugging. +	+ `yes` +	+ Global +
+ `syslog` +	+ numeric (0-10) +	+ Level of messages sent to syslog. Those levels +below `syslog` `level` will be sent +to the system logger. +	+ `1` +	+ Global +
+ `syslog only` +	+ boolean +	+ If `yes`, uses syslog entirely +and sends no output to the Samba log files. +	+ `no` +	+ Global +

log file

By default, Samba writes log information to text files in the +/usr/local/samba/var directory. The +log file option can be +used to set the name of the log file to another location. For +example, to put the Samba log information in +/usr/local/logs/samba.log, you could use the +following:

[global]
+    log file = /usr/local/logs/samba.log

You can use variable substitution to create log files specifically +for individual users or clients.

You can override the default log file location using the +-l command-line switch when either daemon is +started. However, this does not override the log +file option. If you do specify this parameter, +initial logging information will be sent to the file specified after +-l (or the default specified in the Samba +makefile) until the daemons have processed the +smb.conf file and know to redirect it to a new +log file.

log level

The log level option +sets the amount of data to be logged. Normally this is set to 0 or 1. +However, if you have a specific problem, you might want to set it at +3, which provides the most useful debugging information you would +need to track down a problem. Levels above 3 provide information +that's primarily for the developers to use for +chasing internal bugs, and it slows down the server considerably. +Therefore, we recommend that for normal day-to-day operation, you +avoid setting this option to anything above 3.

max log size

The max log +size option sets the maximum size, in kilobytes, +of the debugging log file that Samba keeps. When the log file exceeds +this size, the current log file is renamed to add a +.old extension (erasing any previous file with +that name) and a new debugging log file is started with the original +name. For example:

[global]
+    log file = /usr/local/logs/samba.log.%m
+    max log size = 1000

Here, if the size of any log file exceeds 1MB, Samba renames the log +file samba.log. +machine-name.old, +and a new log file is generated. If there is already a file with the +.old extension, Samba deletes it. We highly +recommend setting this option in your configuration files because +debug logging (even at lower levels) can quietly eat away at your +available disk space. Using this option protects unwary +administrators from suddenly discovering that most of the space on a +disk or partition has been swallowed up by a single Samba log file.

debug timestamp or timestamp logs

If you happen to be debugging a network problem and you find that the +timestamp information within the Samba log lines gets in the way, you +can turn it off by giving either the +timestamp logs or the +synonymous debug +timestamp option a value of no. +For example, a regular Samba log file presents its output in the +following form:

12/31/01 12:03:34 toltec (172.16.1.1) connect to server network as user jay

With a no value for this option, the output would +appear without the timestamp:

toltec (172.16.1.1) connect to server network as user jay

syslog

The syslog option causes Samba log +messages to be sent to the Unix system logger. The type of log +information to be sent is specified as a numeric value. Like the +log level option, it can be a +number from 0 to 10. Logging information with a level less than the +number specified will be sent to the system logger. Debug logs +greater than or equal to the syslog level, but +less than log level, will still be sent to the standard Samba log +files. For example:

[global]
+    log level = 3
+    syslog = 1

With this, all logging information with a level of 0 would be sent to +the standard Samba logs and the system logger, while information with +levels 1, 2, and 3 would be sent only to the standard Samba logs. +Levels above 3 are not logged at all. All messages sent to the system +logger are mapped to a priority level that the syslogd daemon +understands, as shown in Table 6-9. The default +level is 1.

+ +

Table 6-9. syslog priority conversion

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+ Log level +	+ syslog priority +
+ 0 +	+ `LOG_ERR` +
+ 1 +	+ `LOG_WARNING` +
+ 2 +	+ `LOG_NOTICE` +
+ 3 +	+ `LOG_INFO` +
+ 4 and above +	+ `LOG_DEBUG` +

If you wish to use syslog, you will have to run +configure --with-syslog when +compiling Samba, and you will need to configure your +/etc/syslog.conf to suit. (See Section 6.8.1, earlier in this chapter.)

+ + +

+ + + +

syslog only

The syslog only option +tells Samba not to use its own logging files at all and to use only +the system logger. To enable this, specify the following option in +the global section of the Samba configuration file:

[global]
+    syslog only = yes