6.8 Logging Configuration Options

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.

6.8.1 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.

6.8.2 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

6.8.2.1 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.

6.8.2.2 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.

6.8.2.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.

6.8.2.4 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 

6.8.2.5 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
	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.)

6.8.2.6 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