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