Section 4.8. Logging Configuration Options

4.8. Logging Configuration Options

Occasionally, you'll need to find out what Samba is up to, such as when Samba is performing an unexpected action or is not performing at all. To find out why Samba did what it did, check the logfiles.

Samba logfiles can be as brief or verbose as you like. Here is an example of what a Samba logfile at level 3 looks like:

 [2005/07/21 13:23:25, 3] smbd/service.c:close_cnum(514)   cabbage (192.168.1.100) closed connection to service IPC$ [2005/07/21 13:23:25, 3] smbd/connection.c:yield_connection(40)   Yielding connection to IPC$ [2005/07/21 13:23:25, 3] smbd/process.c:process_smb(615)   Transaction 923 of length 49 [2005/07/21 13:23:25, 3] smbd/process.c:switch_message 4-8)   switch message SMBread (pid 467) [2005/07/21 13:23:25, 3] lib/doscalls.c:dos_ChDir(336)   dos_ChDir to /home/samba [2005/07/21 13:23:25, 3] smbd/reply.c:reply_read(2199)   read fnum=4207 num=2820 nread=2820 [2005/07/21 13:23:25, 3] smbd/process.c:process_smb(615)   Transaction 924 of length 55 

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

Samba includes several options that allow administrators to define the granularity, verbosity, and location of logfiles. Each of these are global options and cannot appear inside a share definition. Here are some of the more common logging options that you might use on a production server:

 [global]     log level = 1     log file = /var/log/samba/log.%m     max log size = 50 

Here, we've added a custom logfile that reports information up to debug level 1. This is a relatively light debugging level. The logging level ranges from 0 to 10; level 0 provides only critical error messages and level 10 provides a plethora of low-level information.^[*] A log level of 1 provides some information about connections, and levels 2 or 3 can provide useful debugging information without wasting disk space on the server. In practice, avoid using log levels greater than 3 unless you are working on the Samba source code or temporaily debugging a specific problem.

^[*] The log levels used in the Samba source code are at the discretion of individual developers. For example, level 100 can be used to debug password changes. Generally, 10 is the highest debug level used when debugging (even by developers).

The logging file is in the /var/log/samba directory, thanks to the log file configuration option. You can use variable substitution to create logfiles specifically for individual users or clients, as with the %m variable. 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.

A common question is why two logfiles are created for each client machine when the logfile is defined as log.%m. The reason is the use of port 445 by newer Windows operating systems. When a new connection is received on port 445, the %m can be expanded only to the client's IP address. After the client transmits its name as part of the authentication process (SMBsessetup&X), Samba can resubstitute the %m variable with the real machine name and reopen the expected log filename.

We've added a precaution to the logfiles: no one logfile can exceed 50 KB in size, as specified by the max log size option. If a logfile 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 precaution prevents the hard drive from being overwhelmed with Samba logfiles during the life of the Samba daemons.

4.8.1. Using syslog

It is possible to use the system logger (syslog, implemented by the syslogd daemon) in addition to or in place of the standard Samba logging file. However, in order to use syslog, you must first make sure that Samba was built with the --with-syslog configure option. See Chapter 2 for more information on configuring and compiling Samba. See the smb.conf manpage for more information about the --with-syslog option.

Next, configure your /etc/syslog.conf file to accept logging information from Samba. If there is not already a daemon.* entry in the /etc/syslog. conf file, add the following:^[*]

^[*] Many syslogd implementations require that you send a HUP signal to force it to reread its configuration file. Others may require that any new logfiles exist prior to writing to log entries.

 daemon.*        /var/log/daemon.log 

This line specifies that any logging information from system daemons is stored in the /var/log/daemon.log file, 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 are sent to syslog. This parameter only defines the threshold below which messages are sent to syslogd. The log level parameter still controls which messages are logged in the first place. For example, setting the following:

 syslog = 3 

specifies that any logging messages with a level of 2 or below is to 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 0 through 2 are sent to both syslog and the Samba logging files, and messages with a level of 3 or 4 are sent to the Samba logging files, but not to syslog.

If you want to specify that messages be sent only to syslogand not to the standard Samba logging filesyou can enable the syslog only option.

 syslog only = yes 

If this is set, any logging information at or above the number specified in the syslog option is discarded.

4.8.2. Logging Configuration Options

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

Table 4-8. Logging configuration options

Parameter	Value	Description	Default	Scope
log file	string	Name of the logfile that Samba is to use.	Specified in Samba makefile	Global
log level(debug level)	integer	Number of messages that are sent to the logfile.	0	Global
max log size	integer	Maximum size of a logfile, in kilobytes.	5000	Global
debug timestamp (timestamp logs)	boolean	Controls whether Samba includes timestamped headers for log entries.	yes	Global
debug pid	boolean	Specifies whether Samba should include the process ID in the log header.	no	Global
debug uid	boolean	Specifies whether Samba should include the real and effective uid in the log header.	no	Global
syslog	integer	The threshold below which messages are sent to syslogd.	1	Global
syslog only	boolean	If yes, uses syslogd entirely and sends no output to the Samba logfiles.	no	Global

4.8.2.1. log file

By default, Samba writes log information to text files in the ${prefix}/var directory defined at compile time (for example, /usr/local/samba/var). The log file option can be used to set the name of the logfile to another location. For example, to put the Samba log information in /var/log/samba.log, you could use the following:

 [global]     log file = /var/log/samba.log 

Variable substitution allows you to create logfiles specifically for individual users or clients.

You can override the default logfile location using the -l command-line switch when either daemon is started. However, this switch does not override the log file option. If you do specify this parameter, initial logging information is 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 logfile.

4.8.2.2. log level

The log level option sets the amount of data to be logged. Normally this option is set to 0 (the default, which logs only critical messages) or 1. However, if you have a specific problem, you might want to set it to 2 or 3, either of which provides the most useful debugging information you would need to track down a problem. Levels above 5 provide information primarily for the developers to use for chasing internal bugs, and slow down the server considerably. For normal day-to-day operation, the recommended setting is 0, unless you are tracking specific information.

4.8.2.3. max log size

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

 [global]     log file = /var/log/samba.log     max log size = 1000 

Here, if the size of any logfile exceeds 1 MB, Samba renames the logfile samba.log.old, and a new logfile is generated. If there is already a file with the .old extension, Samba deletes it. 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 logfile.

It is generally a good idea to use some type of log rotation strategy, either by leveraging internal functionality or by using external tools such as logrotate.

4.8.2.4. debug timestamp

By default, Samba includes a timestamp header with each log entry. This can be very useful when running at level 0 or 1, due to the infrequency at which messages are logged. 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 disabling the debug timestamp (also known as timestamp logs). For example, a normal Samba logfile presents its output in the following form:

 [2005/10/04 13:55:12, 1] smbd/service.c:make_connection_snum(666)   rain (127.0.0.1) connect to service lizard initially as user lizard (uid=780, gid=100) (pid 28317) 

With a no value for this option, the output would appear without the timestamp, giving no indication of when the event occurred.

4.8.2.5. debug pid, debug uid

These two options provide a means of separating log messages for different users that are interwoven into a single logfile. When enabled, the debug pid parameter includes a pid= PROCESSID field in the header information. The debug uid option fills in the real and effective uid and group values in the header. The following is an example of a message written by an smbd with a pid of 28554, a uid of 780, and a gid of 100:

 [2005/10/04 14:05:38, 1, pid=28554, effective(780, 100), real(780, 0)] smbd/service. c:make_connection_snum(605) 

Both options require that the debug timestamp parameter be enabled to have any effect.

4.8.2.6. syslog

The syslog option causes Samba log messages to be sent to the Unix system logger and is available only when Samba has been compiled to include --with-syslog when running the configure script at build time. The presence of the string WITH_SYSLOG in the output of smbd -b confirms that compile-time support for syslog has been enabled. The amount of log information to be sent is specified as a numeric value; syslog can accept any valid log level. Logging information with a level lower than the number specified is sent to the system logger. Debug logs greater than or equal to the syslog level, but less than the log level, are still sent to the standard Samba logfiles. For example:

 [global]     log level = 3     syslog = 2 

In this instance, all logging information with a level of 0 and 1 is sent to the standard Samba logs and the system logger, and information at levels 2 and 3 is 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 4-9. The default level is 1.

Table 4-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

4.8.2.7. syslog only

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

 [global]    log level    = 2    syslog       = 3    syslog only  = yes 

This option has no effect if Samba has not been compiled to include the --with-syslog feature.