Chapter 14. Configuration, Services, Logging and Power Management

14.1. Synopsis

One of the important aspects of FreeBSD is proper system configuration. This chapter explains much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system.

Before reading this chapter, you should:

After reading this chapter, you will know:

  • How to use the various configuration files in /etc.

  • The basics of rc.conf configuration and /usr/local/etc/rc.d startup scripts.

  • How to tune FreeBSD using sysctl(8) variables.

  • How to configure the power management in FreeBSD.

14.2. Configuration Files

FreeBSD maintains a clear separation between the base system and third party applications and therefore this affects where the configuration files of these applications are located.

FreeBSD base system configuration is located at the /etc directory, and the /usr/local/etc directory contains all the configuration files of the applications installed on the system through the ports collection and packages.

The kernel state configuration is located in /etc/sysctl.conf. In the section The sysctl utility, the operation of sysctl(8) will be explained in more detail.

For more information about the FreeBSD file system structure refer to hier(7).

As a general rule, configuration files do not use a standard on what syntax they must follow. Although it is true that the # character is normally used to comment a line and that each line has a configuration variable.

Some applications like pkg(8) are starting to use the Universal Configuration Language (UCL).

14.2.1. The /etc directory

The /etc directory contains all of the FreeBSD base system configuration files that are responsible for configuring FreeBSD.

Extreme caution must be taken when modifying files in the /etc directory; misconfiguration could make FreeBSD unbootable or malfunction.

/etc

System configuration files and scripts.

/etc/defaults

Default system configuration files, see rc(8) for more information.

/etc/fstab

fstab(5) contains descriptive information about the various file systems.

/etc/mail

Extra sendmail(8) configuration and other MTA configuration files.

/etc/mtree

mtree configuration files, see man: mtree[8] for more information.

/etc/pam.d

Configuration files for the Pluggable Authentication Modules (PAM) library.

/etc/periodic

Scripts that are run daily, weekly, and monthly, via cron(8), see periodic(8) for more information.

/etc/rc.d

System and daemon startup/control scripts, see rc(8) for more information.

/etc/rc.conf

Contains descriptive information about the local host name, configuration details for any potential network interfaces and which services should be started up at system initial boot time. More information in Managing System-Specific Configuration

/etc/security

OpenBSM audit configuration files, see audit(8) for more information.

/etc/ppp

ppp configuration files, see ppp(8) for more information.

/etc/ssh

OpenSSH configuration files, see ssh(1) for more information.

/etc/ssl

OpenSSL configuration files.

/etc/sysctl.conf

Contains settings for the kernel. More information in The sysctl utility

14.2.2. The sysctl utility

The sysctl(8) utility is used to make changes to a running FreeBSD system.

The sysctl(8) utility retrieves kernel state and allows processes with appropriate privilege to set kernel state. The state to be retrieved or set is described using a "Management Information Base" ("MIB") style name, described as a dotted set of components.

Table 1. Management Information Base

sysctl

"Magic" numbers

kern

Kernel functions and features

vm

virtual memory

vfs

Filesystem

net

Network

debug

Debugging parameters

hw

Hardware

machdep

Machine dependent

user

Userland

p1003_1b

POSIX 1003.1B

At its core, sysctl(8) serves two functions: to read and to modify system settings.

To view all readable variables:

% sysctl -a

The output should be similar to the following:

kern.ostype: FreeBSD
...
vm.swap_enabled: 1
vm.overcommit: 0
vm.domain.0.pidctrl.kdd: 8
vm.domain.0.pidctrl.kid: 4
vm.domain.0.pidctrl.kpd: 3
...
vfs.zfs.sync_pass_rewrite: 2
vfs.zfs.sync_pass_dont_compress: 8
vfs.zfs.sync_pass_deferred_free: 2

To read a particular variable, specify its name:

% sysctl kern.maxproc

The output should be similar to the following:

kern.maxproc: 1044

The Management Information Base (MIB) is hierarchical and hence, specifying a prefix prints all the nodes hanging from it:

% sysctl net

The output should be similar to the following:

net.local.stream.recvspace: 8192
net.local.stream.sendspace: 8192
net.local.dgram.recvspace: 16384
net.local.dgram.maxdgram: 2048
net.local.seqpacket.recvspace: 8192
net.local.seqpacket.maxseqpacket: 8192
net.local.sockcount: 60
net.local.taskcount: 25
net.local.recycled: 0
net.local.deferred: 0
net.local.inflight: 0
net.inet.ip.portrange.randomtime: 1
net.inet.ip.portrange.randomcps: 9999
[...]

To set a particular variable, use the variable=value syntax:

# sysctl kern.maxfiles=5000

The output should be similar to the following:

kern.maxfiles: 2088 -> 5000

To keep the configuration after a reboot it is necessary to add these variables to the /etc/sysctl.conf file as explained below.

14.2.3. The /etc/sysctl.conf file

The configuration file for sysctl(8), /etc/sysctl.conf, looks much like /etc/rc.conf.

Values are set using a variable=value syntax.

The specified values are set after the system goes into multi-user mode. Not all variables are settable in this mode.

For example, to turn off logging of fatal signal exits and prevent users from seeing processes started by other users, the following tunables can be set in /etc/sysctl.conf:

# Do not log fatal signal exits (e.g., sig 11)
kern.logsigexit=0

# Prevent users from seeing information about processes that
# are being run under another UID.
security.bsd.see_other_uids=0

To obtain more information about what function a particular sysctl has, the following command can be executed:

% sysctl -d kern.dfldsiz

The output should be similar to the following:

kern.dfldsiz: Initial data size limit

14.2.4. Managing System-Specific Configuration

The principal location for system configuration information is /etc/rc.conf.

This file contains a wide range of configuration information and it is read at system startup to configure the system. It provides the configuration information for the rc* files.

The entries in /etc/rc.conf override the default settings in /etc/defaults/rc.conf.

The file /etc/defaults/rc.conf containing the default settings should not be edited. Instead, all system-specific changes should be made to /etc/rc.conf.

A number of strategies may be applied in clustered applications to separate site-wide configuration from system-specific configuration in order to reduce administration overhead.

The recommended approach is to place system-specific configuration into /etc/rc.conf.local.

For example, these entries in /etc/rc.conf apply to all systems:

sshd_enable="YES"
keyrate="fast"
defaultrouter="10.1.1.254"

Whereas these entries in /etc/rc.conf.local apply to this system only:

hostname="node1.example.org"
ifconfig_fxp0="inet 10.1.1.1/8"

Distribute /etc/rc.conf to every system using an application such as rsync or puppet, while /etc/rc.conf.local remains unique.

Upgrading the system will not overwrite /etc/rc.conf, so system configuration information will not be lost.

Both /etc/rc.conf and /etc/rc.conf.local are parsed by sh(1). This allows system operators to create complex configuration scenarios. Refer to rc.conf(5) for further information on this topic.

14.3. Managing Services in FreeBSD

FreeBSD uses the rc(8) system of startup scripts during system initialization and for managing services.

The scripts listed in /etc/rc.d provide basic services which can be controlled with the start, stop, and restart options to service(8).

A basic script may look similar to the following:

#!/bin/sh
#
# PROVIDE: utility
# REQUIRE: DAEMON
# KEYWORD: shutdown

. /etc/rc.subr

name=utility
rcvar=utility_enable

command="/usr/local/sbin/utility"

load_rc_config $name

#
# DO NOT CHANGE THESE DEFAULT VALUES HERE
# SET THEM IN THE /etc/rc.conf FILE
#
utility_enable=${utility_enable-"NO"}
pidfile=${utility_pidfile-"/var/run/utility.pid"}

run_rc_command "$1"

Refer to this article for instructions on how to create custom rc(8) scripts.

14.3.1. Starting Services

Many users install third party software on FreeBSD from the Ports Collection and require the installed services to be started upon system initialization.

Services, such as security/openssh-portable or www/nginx are just two of the many software packages which may be started during system initialization. This section explains the procedures available for starting services.

Since the rc(8) system is primarily intended to start and stop services at system startup and shutdown time, the start, stop and restart options will only perform their action if the appropriate /etc/rc.conf variable is set.

So the first step to start a service, like for example www/nginx is to add it to /etc/rc.conf by executing the following command:

# sysrc nginx_enable="YES"

Then nginx can be started executing the following command:

# service nginx start

To start, stop or restart a service regardless of the settings in /etc/rc.conf, these commands should be prefixed with "one". For instance, to start www/nginx regardless of the current /etc/rc.conf setting, execute the following command:

# service nginx onestart

14.3.2. Status of a Service

To determine if a service is running, use the status subcommand.

For example, to verify that www/nginx is running:

# service nginx status

The output should be similar to the following:

nginx is running as pid 27871.

14.3.3. Reload a Service

In some cases, it is also possible to reload a service. This attempts to send a signal to an individual service, forcing the service to reload its configuration files.

In most cases, this means sending the service a SIGHUP signal.

Not all services support this feature.

The rc(8) system is used for network services and it also contributes to most of the system initialization. For instance, when the /etc/rc.d/bgfsck script is executed, it prints out the following message:

Starting background file system checks in 60 seconds.

This script is used for background file system checks, which occur only during system initialization.

Many system services depend on other services to function properly. For example, yp(8) and other RPC-based services may fail to start until after the rpcbind(8) service has started.

Additional information can be found in rc(8) and rc.subr(8).

14.3.4. Using Services to Start Services

Other services can be started using inetd(8). Working with inetd(8) and its configuration is described in depth in “The inetd Super-Server”.

In some cases, it may make more sense to use cron(8) to start system services. This approach has a number of advantages as cron(8) runs these processes as the owner of the crontab(5). This allows regular users to start and maintain their own applications.

The @reboot feature of cron(8), may be used in place of the time specification. This causes the job to run when cron(8) is started, normally during system initialization.

14.4. Cron and Periodic

Scheduling tasks to run at a certain day or time is a very common task on FreeBSD. The tool in charge of performing this task is cron(8).

In addition to tasks that can be scheduled by the user via cron(8), FreeBSD performs routine background tasks managed by periodic(8).

14.4.1. Cron

The cron(8) utility runs in the background and regularly checks /etc/crontab for tasks to execute and searches /var/cron/tabs for custom crontab files.

These files are used to schedule tasks which cron runs at the specified times.

Each entry in a crontab defines a task to run and is known as a cron job.

Two different types of configuration files are used: the system crontab, which should not be modified, and user crontabs, which can be created and edited as needed. The format used by these files is documented in crontab(5). The format of the system crontab, /etc/crontab includes a who column which does not exist in user crontabs. In the system crontab, cron runs the command as the user specified in this column. In a user crontab, all commands run as the user who created the crontab.

User crontabs allow individual users to schedule their own tasks. The root user can also have a user crontab which can be used to schedule tasks that do not exist in the system crontab.

Here is a sample entry from the system crontab, /etc/crontab:

# /etc/crontab - root's crontab for FreeBSD
#
(1)
#
SHELL=/bin/sh
PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin (2)
#
#minute hour    mday    month   wday    who     command (3)
#
# Save some entropy so that /dev/random can re-seed on boot.
*/11    *       *       *       *       operator /usr/libexec/save-entropy (4)
#
# Rotate log files every hour, if necessary.
0       *       *       *       *       root    newsyslog
#
# Perform daily/weekly/monthly maintenance.
1       3       *       *       *       root    periodic daily
15      4       *       *       6       root    periodic weekly
30      5       1       *       *       root    periodic monthly
#
# Adjust the time zone if the CMOS clock keeps local time, as opposed to
# UTC time.  See adjkerntz(8) for details.
1,31    0-5     *       *       *       root    adjkerntz -a
1Lines that begin with the # character are comments. A comment can be placed in the file as a reminder of what and why a desired action is performed. Comments cannot be on the same line as a command or else they will be interpreted as part of the command; they must be on a new line. Blank lines are ignored.
2The equals (=) character is used to define any environment settings. In this example, it is used to define the SHELL and PATH. If the SHELL is omitted, cron will use the default Bourne shell. If the PATH is omitted, the full path must be given to the command or script to run.
3This line defines the seven fields used in a system crontab: minute, hour, mday, month, wday, who, and command. The minute field is the time in minutes when the specified command will be run, the hour is the hour when the specified command will be run, the mday is the day of the month, month is the month, and wday is the day of the week. These fields must be numeric values, representing the twenty-four hour clock, or a *, representing all values for that field. The who field only exists in the system crontab and specifies which user the command should be run as. The last field is the command to be executed.
4This entry defines the values for this cron job. The */11, followed by several more * characters, specifies that /usr/libexec/save-entropy is invoked by operator every eleven minutes of every hour, of every day and day of the week, of every month. Commands can include any number of switches. However, commands which extend to multiple lines need to be broken with the backslash "\" continuation character.

14.4.2. Creating a User Crontab

To create a user crontab, invoke crontab in editor mode:

% crontab -e

This will open the user’s crontab using the default text editor. The first time a user runs this command, it will open an empty file. Once a user creates a crontab, this command will open that file for editing.

It is useful to add these lines to the top of the crontab file in order to set the environment variables and to remember the meanings of the fields in the crontab:

SHELL=/bin/sh
PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin
# Order of crontab fields
# minute hour mday month wday command

Then add a line for each command or script to run, specifying the time to run the command. This example runs the specified custom Bourne shell script every day at two in the afternoon. Since the path to the script is not specified in PATH, the full path to the script is given:

0 14 * * * /home/user/bin/mycustomscript.sh

Before using a custom script, make sure it is executable and test it with the limited set of environment variables set by cron. To replicate the environment that would be used to run the above cron entry, use:

env -i SHELL=/bin/sh PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin HOME=/home/user LOGNAME=user /home/user/bin/mycustomscript.sh

The environment set by cron is discussed in crontab(5). Checking that scripts operate correctly in a cron environment is especially important if they include any commands that delete files using wildcards.

When finished editing the crontab, save the file. It will automatically be installed, and cron will read the crontab and run its cron jobs at their specified times. To list the cron jobs in a crontab, use this command:

% crontab -l

The output should be similar to the following:

0 14 * * * /home/user/bin/mycustomscript.sh

To remove all of the cron jobs in a user crontab:

% crontab -r

The output should be similar to the following:

remove crontab for user? y

14.4.3. Periodic

FreeBSD provides a set of system management scripts to check status of various subsystems, perform security-related checks, rotate log files, etc. These scripts are run on a periodic basis: daily. weekly, or monthly. The management of these tasks is performed by periodic(8) and its configuration resides in periodic.conf(5). The periodic tasks are initiated by entries in the system crontab, shown above.

Scripts executed by periodic(8) are located in /etc/periodic/ for base utilities and in /usr/local/etc/periodic/ for third-party software.

They are organized in 4 subdirectories, daily, weekly, monthly and security.

14.4.4. Enable or Disable Periodic Tasks

FreeBSD has some scripts enabled by default to run periodically.

To enable or disable a task, the first step is to edit /etc/periodic.conf executing the following command:

# ee /etc/periodic.conf

And then to enable, for example, daily_status_zfs_enable put the following content in the file:

daily_status_zfs_enable="YES"

To disable a task that is active by default, all that needs to be done is to change YES to NO.

14.4.5. Configuring the Output of Periodic Tasks

In /etc/periodic.conf the variables daily_output, weekly_output and monthly_output specifies where to send the results of the script execution.

By default the output of the periodic scripts are emailed to root, and therefore it is best to read root’s mail or alias root to a mailbox that is monitored.

To send the results to another email or to other emails, add the email addresses separated by spaces to /etc/periodic.conf:

daily_output="email1@example.com email2@example.com"
weekly_output="email1@example.com email2@example.com"
monthly_output="email1@example.com email2@example.com"

To log periodic output instead of receiving it as email, add the following lines to /etc/periodic.conf. newsyslog(8) will rotate these files at the appropriate times:

daily_output=/var/log/daily.log
weekly_output=/var/log/weekly.log
monthly_output=/var/log/monthly.log

14.5. Configuring System Logging

Generating and reading system logs is an important aspect of system administration. The information in system logs can be used to detect hardware and software issues as well as application and system configuration errors. This information also plays an important role in security auditing and incident response. Most system daemons and applications will generate log entries.

FreeBSD provides a system logger, syslogd(8), to manage logging. By default, syslogd is enabled and started when the system boots.

This section describes how to configure the FreeBSD system logger for both local and remote logging and how to perform log rotation and log management.

14.5.1. Configuring Local Logging

The configuration file, /etc/syslog.conf, controls what syslogd does with log entries as they are received. There are several parameters to control the handling of incoming events. The facility describes which subsystem generated the message, such as the kernel or a daemon, and the level describes the severity of the event that occurred. This makes it possible to configure if and where a log message is logged, depending on the facility and level. It is also possible to take action depending on the application that sent the message, and in the case of remote logging, the hostname of the machine generating the logging event.

This configuration file contains one line per action, where the syntax for each line is a selector field followed by an action field. The syntax of the selector field is facility.level which will match log messages from facility at level level or higher. It is also possible to add an optional comparison flag before the level to specify more precisely what is logged. Multiple selector fields can be used for the same action, and are separated with a semicolon (;). Using * will match everything. The action field denotes where to send the log message, such as to a file or remote log host.

As an example, here is the default /etc/syslog.conf from FreeBSD:

#       Spaces ARE valid field separators in this file. However,
#       other *nix-like systems still insist on using tabs as field
#       separators. If you are sharing this file between systems, you
#       may want to use only tabs as field separators here.
#       Consult the syslog.conf(5) manpage.
*.err;kern.warning;auth.notice;mail.crit                /dev/console (1)
*.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err   /var/log/messages
security.*                                      /var/log/security
auth.info;authpriv.info                         /var/log/auth.log
mail.info                                       /var/log/maillog (2)
cron.*                                          /var/log/cron
!-devd
*.=debug                                        /var/log/debug.log (3)
*.emerg                                         *
daemon.info                                     /var/log/daemon.log
# uncomment this to log all writes to /dev/console to /var/log/console.log
# touch /var/log/console.log and chmod it to mode 600 before it will work
#console.info                                   /var/log/console.log
# uncomment this to enable logging of all log messages to /var/log/all.log
# touch /var/log/all.log and chmod it to mode 600 before it will work
#*.*                                            /var/log/all.log
# uncomment this to enable logging to a remote loghost named loghost
#*.*                                            @loghost
# uncomment these if you're running inn
# news.crit                                     /var/log/news/news.crit
# news.err                                      /var/log/news/news.err
# news.notice                                   /var/log/news/news.notice
# Uncomment this if you wish to see messages produced by devd
# !devd
# *.>=notice                                    /var/log/devd.log (4)
!*
include                                         /etc/syslog.d
include                                         /usr/local/etc/syslog.d
1Matches all messages with a level of err or higher, as well as kern.warning, auth.notice and mail.crit, and sends these log messages to the console (/dev/console).
2Matches all messages from the mail facility at level info or above and logs the messages to /var/log/maillog.
3Uses a comparison flag (=) to only match messages at level debug and logs them to /var/log/debug.log.
4Is an example usage of a program specification. This makes the rules following it only valid for the specified program. In this case, only the messages generated by devd(8) are logged to /var/log/devd.log.

For more information about /etc/syslog.conf, its syntax, and more advanced usage examples, see syslog.conf(5).

14.5.2. Logging Facilities

A facility describes the part of the system generating the message. Facilities are a way of separating the different messages so that it is easier for the user to consult the logs.

Table 2. syslog facilities
NameDescription

auth

The authorization system: login(1), su(1), getty(8), etc.

authpriv

The same as auth, but logged to a file readable only by root.

console

Messages written to /dev/console by the kernel console output driver.

cron

Messages written by the cron(8) daemon.

daemon

System daemons, such as routed(8), that are not provided for explicitly by other facilities.

ftp

The file transfer protocol daemons: ftpd(8), tftpd(8).

kern

Messages generated by the kernel. These cannot be generated by any user processes.

lpr

The line printer spooling system: lpr(1), lpc(8), lpd(8), etc.

mail

The mail system.

mark

This facility adds a record every 20 minutes.

news

The network news system.

ntp

The network time protocol system.

security

Security subsystems, such as ipfw(4).

syslog

Messages generated internally by syslogd(8).

user

Messages generated by random user processes. This is the default facility identifier if none is specified.

uucp

The Unix-to-Unix Copy system. An ancient protocol. Really weird to see messages from this facility.

local0 through local7

Reserved for local use.

14.5.3. Logging Levels

The level describes the severity of the message, and is a keyword from the following ordered list (higher to lower):

Table 3. syslog levels
NameDescription

emerg

A panic condition. This is normally broadcast to all users.

alert

A condition that should be corrected immediately, such as a corrupted system database.

crit

Critical conditions, e.g., hard device errors.

err

Errors.

warning

Warning messages.

notice

Conditions that are not error conditions, but should possibly be handled specially.

info

Informational messages.

debug

Messages that contain information normally of use only when debugging a program.

none

This special level disables a particular facility.

14.5.4. Read Log Messages

By default FreeBSD log files use the format rfc3164, also known as The BSD syslog Protocol. Learn more about other formats and how to use them at syslog(8).

Typically the logs have the following syntax:

date time hostname program[pid]: the message

The output of the /var/log/cron file will be used as an example:

[...]
Jul 16 12:40:00 FreeBSD /usr/sbin/cron[81519]: (root) CMD (/usr/libexec/atrun)
Jul 16 12:44:00 FreeBSD /usr/sbin/cron[83072]: (operator) CMD (/usr/libexec/save-entropy)
[...]

Verbose logging, so the facility and the level on each message will be added, can be enabled in syslog(8) by running the following command:

# sysrc syslogd_flags="-vv"

Once the function is activated, the facility and the level will be displayed in the log as shown in the following example:

[...]
Jul 16 17:40:00 <cron.info> FreeBSD /usr/sbin/cron[1016]: (root) CMD (/usr/libexec/atrun)
Jul 16 17:44:00 <cron.info> FreeBSD /usr/sbin/cron[1030]: (operator) CMD (/usr/libexec/save-entropy)
[...]

14.5.5. Log Management and Rotation

Log files can grow quickly, taking up disk space and making it more difficult to locate useful information.

In FreeBSD, newsyslog(8) is used to manage log files and attempt to mitigate this.

This built-in program periodically rotates and compresses log files, and optionally creates missing log files and signals programs when log files are moved.

Since newsyslog is run from cron(8), it cannot rotate files more often than it is scheduled to run from cron(8). In the default configuration, it runs every hour.

Here is the default configuration in FreeBSD, more information in newsyslog.conf(5):

# configuration file for newsyslog
#
# Entries which do not specify the '/pid_file' field will cause the
# syslogd process to be signalled when that log file is rotated.  This
# action is only appropriate for log files which are written to by the
# syslogd process (ie, files listed in /etc/syslog.conf).  If there
# is no process which needs to be signalled when a given log file is
# rotated, then the entry for that file should include the 'N' flag.
#
# Note: some sites will want to select more restrictive protections than the
# defaults.  In particular, it may be desirable to switch many of the 644
# entries to 640 or 600.  For example, some sites will consider the
# contents of maillog, messages, and lpd-errs to be confidential.  In the
# future, these defaults may change to more conservative ones.
#
# logfilename          [owner:group]    mode count size when  flags [/pid_file] [sig_num]
/var/log/all.log                        600  7     *    @T00  J
/var/log/auth.log                       600  7     1000 @0101T JC
/var/log/console.log                    600  5     1000 *     J
/var/log/cron                           600  3     1000 *     JC
/var/log/daily.log                      640  7     *    @T00  JN
/var/log/debug.log                      600  7     1000 *     JC
/var/log/init.log                       644  3     1000 *     J
/var/log/kerberos.log                   600  7     1000 *     J
/var/log/maillog                        640  7     *    @T00  JC
/var/log/messages                       644  5     1000 @0101T JC
/var/log/monthly.log                    640  12    *    $M1D0 JN
/var/log/devd.log                       644  3     1000 *     JC
/var/log/security                       600  10    1000 *     JC
/var/log/utx.log                        644  3     *    @01T05 B
/var/log/weekly.log                     640  5     *    $W6D0 JN
/var/log/daemon.log                     644  5     1000 @0101T JC

<include> /etc/newsyslog.conf.d/[!.]*.conf
<include> /usr/local/etc/newsyslog.conf.d/[!.]*.conf
  1. logfilename - Name of the system log file to be archived.

  2. [owner:group] - This optional field specifies the owner and group for the archive file.

  3. mode - Specify the file mode of the log file and archives. Valid mode bits are 0666. (That is, read and write permissions for the rotated log may be specified for the owner, group, and others.)

  4. count - Specify the maximum number of archive files which may exist.

  5. size - When the size of the log file reaches size in kilobytes, the log file will be trimmed as described above. If this field contains an asterisk ('*'), the log file will not be trimmed based on size.

  6. when - Consist of an interval, a specific time, or both. Supported options in newsyslog.conf(5).

  7. flags - Indicates the flags that newsyslog accepts, supported options in newsyslog.conf(5).

  8. [/pid_file] - This optional field specifies the file name containing a daemon’s process ID or to find a group process ID.

  9. [sig_num] - This optional field specifies the signal that will be sent to the daemon process.

The last two fields are optional and specify the name of the Process ID (PID) file of a process and a signal number to send to that process when the file is rotated.

14.5.6. Configuring Remote Logging

Monitoring the log files of multiple hosts can become unwieldy as the number of systems increases. Configuring centralized logging can reduce some of the administrative burden of log file administration.

In FreeBSD, centralized log file aggregation, merging, and rotation can be configured using syslogd and newsyslog.

This section demonstrates an example configuration, where host A, named logserv.example.com, will collect logging information for the local network.

Host B, named logclient.example.com, will be configured to pass logging information to the logging server.

14.5.6.1. Log Server Configuration

A log server is a system that has been configured to accept logging information from other hosts.

Before configuring a log server, check the following:

  • If there is a firewall between the logging server and any logging clients, ensure that the firewall ruleset allows UDP port 514 for both the clients and the server.

  • The logging server and all client machines must have forward and reverse entries in the local DNS. If the network does not have a DNS server, create entries in each system’s /etc/hosts. Proper name resolution is required so that log entries are not rejected by the logging server.

On the log server, edit /etc/syslog.conf to specify the name of the client to receive log entries from, the logging facility to be used, and the name of the log to store the host’s log entries. This example adds the hostname of B, logs all facilities, and stores the log entries in /var/log/logclient.log.

Example 1. Sample Log Server Configuration
+logclient.example.com
*.*     /var/log/logclient.log

When adding multiple log clients, add a similar two-line entry for each client. More information about the available facilities may be found in syslog.conf(5).

Next, execute the following commands:

# sysrc syslogd_enable="YES"
# sysrc syslogd_flags="-a logclient.example.com -v -v"

The first entry starts syslogd at system boot. The second entry allows log entries from the specified client. The -v -v increases the verbosity of logged messages. This is useful for tweaking facilities as administrators are able to see what type of messages are being logged under each facility.

Multiple -a options may be specified to allow logging from multiple clients. IP addresses and whole netblocks may also be specified. Refer to syslogd(8) for a full list of possible options.

Finally, create the log file:

# touch /var/log/logclient.log

At this point, syslogd should be restarted and verified:

# service syslogd restart
# pgrep syslog

If a PID is returned, the server restarted successfully, and client configuration can begin. If the server did not restart, consult /var/log/messages for the error.

14.5.6.2. Log Client Configuration

A logging client sends log entries to a logging server on the network. The client also keeps a local copy of its own logs.

Once a logging server has been configured, execute the following commands on the logging client:

# sysrc syslogd_enable="YES"
# sysrc syslogd_flags="-s -v -v"

The first entry enables syslogd on boot up. The second entry prevents logs from being accepted by this client from other hosts (-s) and increases the verbosity of logged messages.

Next, define the logging server in the client’s /etc/syslog.conf. In this example, all logged facilities are sent to a remote system, denoted by the @ symbol, with the specified hostname:

*.*  @logserv.example.com

After saving the edit, restart syslogd for the changes to take effect:

# service syslogd restart

To test that log messages are being sent across the network, use logger(1) on the client to send a message to syslogd:

# logger "Test message from logclient"

This message should now exist both in /var/log/messages on the client and /var/log/logclient.log on the log server.

14.5.6.3. Debugging Log Servers

If no messages are being received on the log server, the cause is most likely a network connectivity issue, a hostname resolution issue, or a typo in a configuration file. To isolate the cause, ensure that both the logging server and the logging client are able to ping each other using the hostname specified in their /etc/rc.conf. If this fails, check the network cabling, the firewall ruleset, and the hostname entries in the DNS server or /etc/hosts on both the logging server and clients. Repeat until the ping is successful from both hosts.

If the ping succeeds on both hosts but log messages are still not being received, temporarily increase logging verbosity to narrow down the configuration issue. In the following example, /var/log/logclient.log on the logging server is empty and /var/log/messages on the logging client does not indicate a reason for the failure.

To increase debugging output, edit the syslogd_flags entry on the logging server and issue a restart:

sysrc syslogd_flags="-d -a logclient.example.com -v -v"
# service syslogd restart

Debugging data similar to the following will flash on the console immediately after the restart:

logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart
syslogd: restarted
logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel
Logging to FILE /var/log/messages
syslogd: kernel boot file is /boot/kernel/kernel
cvthname(192.168.1.10)
validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com;
rejected in rule 0 due to name mismatch.

In this example, the log messages are being rejected due to a typo which results in a hostname mismatch. The client’s hostname should be logclient, not logclien. Fix the typo, issue a restart, and verify the results:

# service syslogd restart

The output should be similar to the following:

logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart
syslogd: restarted
logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel
syslogd: kernel boot file is /boot/kernel/kernel
logmsg: pri 166, flags 17, from logserv.example.com,
msg Dec 10 20:55:02 <syslog.err> logserv.example.com syslogd: exiting on signal 2
cvthname(192.168.1.10)
validate: dgram from IP 192.168.1.10, port 514, name logclient.example.com;
accepted in rule 0.
logmsg: pri 15, flags 0, from logclient.example.com, msg Dec 11 02:01:28 trhodes: Test message 2
Logging to FILE /var/log/logclient.log
Logging to FILE /var/log/messages

At this point, the messages are being properly received and placed in the correct file.

14.5.6.4. Security Considerations

As with any network service, security requirements should be considered before implementing a logging server. Log files may contain sensitive data about services enabled on the local host, user accounts, and configuration data. Network data sent from the client to the server will not be encrypted or password protected. If a need for encryption exists, consider using security/stunnel, which will transmit the logging data over an encrypted tunnel.

Local security is also an issue. Log files are not encrypted during use or after log rotation. Local users may access log files to gain additional insight into system configuration. Setting proper permissions on log files is critical. The built-in log rotator, newsyslog, supports setting permissions on newly created and rotated log files. Setting log files to mode 600 should prevent unwanted access by local users. Refer to newsyslog.conf(5) for additional information.

14.6. Power and Resource Management

It is important to utilize hardware resources in an efficient manner. Power and resource management allows the operating system to monitor system limits and to possibly run some actions triggered by events related to those limits.

14.6.1. ACPI configuration

On FreeBSD the management of these resources is managed by the acpi(4) kernel device.

In FreeBSD the acpi(4) driver is loaded by default at system boot.

This driver cannot be unloaded after boot because the system bus uses it for various hardware interactions.

In addition to acpi(4), FreeBSD has several dedicated kernel modules for various ACPI vendor subsystems. These modules will add some extra functionality like fan speed, keyboard backlit or screen brightness.

The list can be obtained by running the following command:

% ls /boot/kernel | grep acpi

The output should be similar to the following:

acpi_asus.ko
acpi_asus_wmi.ko
acpi_dock.ko
acpi_fujitsu.ko
acpi_hp.ko
acpi_ibm.ko
acpi_panasonic.ko
acpi_sony.ko
acpi_toshiba.ko
acpi_video.ko
acpi_wmi.ko
sdhci_acpi.ko
uacpi.ko

In the event that, for example, an IBM/Lenovo laptop is used, it will be necessary to load the module acpi_ibm(4) by executing the following command:

# kldload acpi_ibm

And add this line to /boot/loader.conf to load it at boot:

acpi_ibm_load="YES"

An alternative to the acpi_video(4) module is the backlight(9) driver. It provides a generic way for handling a panel backlight. The default GENERIC kernel includes this driver. The backlight(8) utility can be used to query and adjust the brightness of the panel backlight. In this example the brightness is decreased by 10%:

% backlight decr 10

14.6.2. CPU Power Management

CPU is the most consuming part of the system. Knowing how to improve CPU efficiency is a fundamental part of our system in order to save energy.

In order to make proper use of the machine’s resources in a correct way, FreeBSD supports technologies such as Intel Turbo Boost, AMD Turbo Core, Intel Speed Shift among others through the use of powerd(8) and cpufreq(4).

The first step will be to obtain the CPU information by executing the following command:

% sysctl dev.cpu.0 (1)
1In this case the 0 digit represents the first core of the CPU.

The output should be similar to the following:

dev.cpu.0.cx_method: C1/mwait/hwc C2/mwait/hwc C3/mwait/hwc/bma
dev.cpu.0.cx_usage_counters: 3507294 0 0
dev.cpu.0.cx_usage: 100.00% 0.00% 0.00% last 3804us
dev.cpu.0.cx_lowest: C3 (1)
dev.cpu.0.cx_supported: C1/1/1 C2/2/1 C3/3/57 (2)
dev.cpu.0.freq_levels: 2267/35000 2266/35000 1600/15000 800/12000 (3)
dev.cpu.0.freq: 1600 (4)
dev.cpu.0.temperature: 40.0C (5)
dev.cpu.0.coretemp.throttle_log: 0
dev.cpu.0.coretemp.tjmax: 105.0C
dev.cpu.0.coretemp.resolution: 1
dev.cpu.0.coretemp.delta: 65
dev.cpu.0.%parent: acpi0
dev.cpu.0.%pnpinfo: _HID=none _UID=0 _CID=none
dev.cpu.0.%location: handle=\_PR_.CPU0
dev.cpu.0.%driver: cpu
dev.cpu.0.%desc: ACPI CPU
1Lowest Cx state to use for idling the CPU.
2CPU supported Cx states.
3Currently available levels for the CPU (frequency/power usage).
4Current active CPU frequency in MHz.
5Current temperature of the CPU.

If the temperature information is not displayed, load the coretemp(4) module. In case of using an AMD CPU, load the amdtemp(4) module.

Once the CPU information is available the easiest way to configure power saving is to let powerd(8) take over.

Enable powerd(8) service in /etc/rc.conf to start at system boot:

# sysrc powerd_enable=YES

It will also be necessary to indicate certain parameters to powerd(8) to tell it how to manage the state of the CPU executing the following command:

# sysrc powerd_flags="-a hiadaptive -i 25 -r 85 -N"
  1. -a: Selects the mode to use while on AC power.

  2. hiadaptive: Operation mode. More info at powerd(8).

  3. -i: Specifies the CPU load percent level when adaptive mode should begin to degrade performance to save power.

  4. -r: Specifies the CPU load percent level where adaptive mode should consider the CPU running and increase performance.

  5. -N: Treat "nice" time as idle for the purpose of load calculation; i.e., do not increase the CPU frequency if the CPU is only busy with "nice" processes.

And then enable the service executing the following command:

# service powerd start

14.6.3. CPU Frequency Control

FreeBSD includes a generic cpufreq(4) driver to allow the administrator, or software such as powerd(8) and sysutils/powerdxx, to manage the frequency of the CPU to achieve the desired balance between performance and economy. A lower setting will save power while reducing the heat generated by the CPU. A higher setting will increase performance at the cost of using additional power and generating more heat.

14.6.4. Intel® Enhanced Speed Step™

The Intel® Enhanced Speed Step™ driver, est(4), replaces the generic cpufreq(4) driver for CPUs that provide this feature. The CPU frequency can be statically adjusted using sysctl(8), or with the /etc/rc.d/power_profile startup script. Additional software, such as powerd(8) or sysutils/powerdxx, can be used to automatically adjust the CPU frequency based on processor utilization.

Each supported frequency, along with its expected power consumption, can be listed by examining the sysctl(3) tree:

# sysctl dev.cpufreq.0.freq_driver dev.cpu.0.freq_levels dev.cpu.0.freq

The output should be similar to the following:

dev.cpufreq.0.freq_driver: est0
dev.cpu.0.freq_levels: 3001/53000 3000/53000 2900/50301 2700/46082 2600/43525 2400/39557 2300/37137 2100/33398 2000/31112 1800/27610 1700/25455 1500/22171 1400/20144 1200/17084 1100/15181 900/12329 800/10550
dev.cpu.0.freq: 800

A frequency 1 MHz higher than the maximum frequency of the CPU indicates the Intel® Turbo Boost™ feature.

14.6.5. Intel Speed Shift™

Users running newer Intel® CPUs may find some differences in dynamic frequency control when upgrading to FreeBSD 13. A new driver for the Intel® Speed Shift™ feature set, available on certain SKUs, exposes the ability for the hardware to dynamically vary the core frequencies, including on a per core basis. FreeBSD 13 comes with the hwpstate_intel(4) driver to automatically enable Speed Shift™ control on equipped CPUs, replacing the older Enhanced Speed Step™ est(4) driver. The sysctl(8) dev.cpufreq.%d.freq_driver will indicate if the system is using Speed Shift.

To determine which frequency control driver is being used, examining the dev.cpufreq.0.freq_driver oid.

# sysctl dev.cpufreq.0.freq_driver

The output should be similar to the following:

dev.cpufreq.0.freq_driver: hwpstate_intel0

This indicates that the new hwpstate_intel(4) driver is in use. On such systems, the oid dev.cpu.%d.freq_levels will show only the maximum CPU frequency, and will indicate a power consumption level of -1.

The current CPU frequency can be determined by examining the dev.cpu.%d.freq oid.

# sysctl dev.cpu.0.freq_levels dev.cpu.0.freq

The output should be similar to the following:

dev.cpu.0.freq_levels: 3696/-1
dev.cpu.0.freq: 898

For more information, including on how to balance performance and energy use, and on how to disable this driver, refer to the man page hwpstate_intel(4).

Users accustomed to using powerd(8) or sysutils/powerdxx will find these utilities have been superseded by the hwpstate_intel(4) driver and no longer work as expected.

14.6.6. Graphics Card Power Management

Graphics cards have become a fundamental part of computing in recent years. Some graphics cards may have excessive power consumption. FreeBSD allows certain configurations to improve power consumption.

In case of using a Intel® graphics card with the graphics/drm-kmod driver these options can be added to /boot/loader.conf:

compat.linuxkpi.fastboot=1 (1)
compat.linuxkpi.enable_dc=2 (2)
compat.linuxkpi.enable_fbc=1 (3)
1Try to skip unnecessary mode sets at boot time.
2Enable power-saving display C-states.
3Enable frame buffer compression for power savings

14.6.7. Suspend/Resume

The suspend/resume function allows the machine to be kept in a state in which there is no a big energy consumption and allows the system to be resumed without having to lose the state of the running programs.

In order for the suspend/resume functionality to work correctly the graphics drivers must be loaded on the system. In non-KMS-supported graphics cards sc(4) must be used not to break the suspend/resume functionality.

More information about which driver to use and how to configure it can be found at the The X Window System chapter.

acpi(4) supports the next list of sleep states:

Table 4. Supported Sleep States
S1Quick suspend to RAM. The CPU enters a lower power state, but most peripherals are left running.

S2

Lower power state than S1, but with the same basic characteristics. Not supported by many systems.

S3 (Sleep mode)

Suspend to RAM. Most devices are powered off, and the system stops running except for memory refresh.

S4 (Hibernation)

Suspend to disk. All devices are powered off, and the system stops running. When resuming, the system starts as if from a cold power on. Not yet supported by FreeBSD.

S5

System shuts down cleanly and powers off.

14.6.7.1. Configuring Suspend/Resume

The first step will be to know which type of sleep states supports the hardware we are using executing the following command:

% sysctl hw.acpi.supported_sleep_state

The output should be similar to the following:

hw.acpi.supported_sleep_state: S3 S4 S5

As stated above FreeBSD does not yet support the S4 state.

acpiconf(8) can be used to check if the S3 state works correctly by running the following command, if it succeeds, the screen should go black and the machine will turn off:

# acpiconf -s 3

In the vast majority of cases the Suspend/Resume functionality wants to be used on a laptop.

FreeBSD can be configured to enter the S3 state when closing the lid by adding the following line to the /etc/sysctl.conf file.

hw.acpi.lid_switch_state=S3

14.6.7.2. Troubleshooting in Suspend/Resume

A lot of effort has been made to make the Suspend and Resume functions work properly and in the best way on FreeBSD. But currently the Suspend and Resume functions only work properly on some specific laptops.

Some checks can be done in case it doesn’t work properly.

In some cases it is enough to turn off the bluetooth. In others it is enough loading the correct driver for the graphics card, etc.

In case it doesn’t work correctly, some tips can be found on the FreeBSD Wiki in the section Suspend/Resume.

14.7. Adding Swap Space

Sometimes a FreeBSD system requires more swap space. This section describes two methods to increase swap space: adding swap to an existing partition or new hard drive, and creating a swap file on an existing file system.

For information on how to encrypt swap space, which options exist, and why it should be done, refer to “Encrypting Swap”.

14.7.1. Swap on a New Hard Drive or Existing Partition

Adding a new drive for swap gives better performance than using a partition on an existing drive. Setting up partitions and drives is explained in Adding Disks while Designing the Partition Layout discusses partition layouts and swap partition size considerations.

It is possible to use any partition not currently mounted, even if it already contains data. Using swapon on a partition that contains data will overwrite and destroy that data. Make sure that the partition to be added as swap is really the intended partition before running swapon.

swapon(8) can be used to add a swap partition to the system executing the following command:

# swapon /dev/ada1p2

To automatically add this swap partition on boot, add an entry to /etc/fstab:

/dev/ada1p2 none swap sw 0 0

See fstab(5) for an explanation of the entries in /etc/fstab.

14.7.2. Creating a Swap File

These examples create a 512M swap file called /usr/swap0.

Swap files on ZFS file systems are strongly discouraged, as swapping can lead to system hangs.

The first step is to create the swap file:

# dd if=/dev/zero of=/usr/swap0 bs=1m count=512

The second step is to put the proper permissions on the new file:

# chmod 0600 /usr/swap0

The third step is to inform the system about the swap file by adding a line to /etc/fstab:

md none swap sw,file=/usr/swap0,late 0 0

Swap space will be added on system startup. To add swap space immediately, use swapon(8):

# swapon -aL

Last modified on: March 14, 2024 by Gordon Bergling