Date: Tue, 1 Aug 2023 09:32:10 GMT From: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Subject: git: 9401f487d4 - main - Handbook-WG: Upgrade config chapter Message-ID: <202308010932.3719WABe063709@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by carlavilla: URL: https://cgit.FreeBSD.org/doc/commit/?id=9401f487d47fb9147a5c6792e0318b9389749de3 commit 9401f487d47fb9147a5c6792e0318b9389749de3 Author: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> AuthorDate: 2023-08-01 09:06:38 +0000 Commit: Sergio Carlavilla Delgado <carlavilla@FreeBSD.org> CommitDate: 2023-08-01 09:06:38 +0000 Handbook-WG: Upgrade config chapter Changes: * Change the title of the chapter to be more acurate * Add a config files entry (/etc, /usr/local/etc), and /etc/sysctl.conf * Rework the entry "managing services in FreeBSD" * Upgrade cron section and add periodic info * Upgrade syslog section * Remove tuning section, some parts are really outdated * Upgrade power management section * Little upgrades to swap section ACPI info obtained from: * https://freebsdfoundation.org/wp-content/uploads/2022/04/ACPI-Support-for-Embedded-Controllers.pdf * https://freebsdfoundation.org/wp-content/uploads/2018/04/Pain-and-Suffering-on-the-Road-to-Resume.pdf * https://wiki.freebsd.org/ACPI * https://papers.freebsd.org/2002/watanabe-acpi.files/watanabe-acpi-paper.pdf * https://vermaden.wordpress.com/2018/11/28/the-power-to-serve-freebsd-power-management/ * https://github.com/freebsd/drm-kmod/blob/master/drivers/gpu/drm/i915/i915_params.c PR: 219953,260994,216753 Differential Revision: https://reviews.freebsd.org/D41052 Reviewed by: fernape, karels Sponsored by: Daifressh --- .../content/en/books/handbook/config/_index.adoc | 1699 ++++++++++---------- 1 file changed, 844 insertions(+), 855 deletions(-) diff --git a/documentation/content/en/books/handbook/config/_index.adoc b/documentation/content/en/books/handbook/config/_index.adoc index 71ed091867..b82caf1419 100644 --- a/documentation/content/en/books/handbook/config/_index.adoc +++ b/documentation/content/en/books/handbook/config/_index.adoc @@ -1,17 +1,17 @@ --- -title: Chapter 14. Configuration and Tuning +title: Chapter 14. Configuration, Services, Logging and Power Management part: Part III. System Administration prev: books/handbook/partiii next: books/handbook/boot -description: This chapter explains much of the FreeBSD configuration process, including some of the parameters which can be set to tune a FreeBSD system. -tags: ["configuration", "tuning", "services", "cron", "logging", "configuration files", "sysctl", "tuning disks", "kernel limits", "swap", "power management"] +description: This chapter explains much of the FreeBSD configuration files, how to enable or disable a service, how to configure the logging system and the power management area. +tags: ["configuration", "services", "cron", "periodic", "logging", "configuration files", "sysctl", "swap", "power management"] showBookMenu: true weight: 18 path: "/books/handbook/" --- [[config-tuning]] -= Configuration and Tuning += Configuration, Services, Logging and Power Management :doctype: book :toc: macro :toclevels: 1 @@ -57,28 +57,317 @@ This chapter explains much of the FreeBSD configuration process, including some Before reading this chapter, you should: * Understand UNIX(R) and FreeBSD basics (crossref:basics[basics,FreeBSD Basics]). -* Be familiar with the basics of kernel configuration and compilation (crossref:kernelconfig[kernelconfig,Configuring the FreeBSD Kernel]). After reading this chapter, you will know: -* The basics of [.filename]#rc.conf# configuration and [.filename]#/usr/local/etc/rc.d# startup scripts. * How to use the various configuration files in [.filename]#/etc#. +* The basics of [.filename]#rc.conf# configuration and [.filename]#/usr/local/etc/rc.d# startup scripts. * How to tune FreeBSD using man:sysctl[8] variables. -* How to tune disk performance and modify kernel limitations. +* How to configure the power management in FreeBSD. -[[configtuning-starting-services]] -== Starting Services +[[configtuning-configfiles]] +== 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 [.filename]#/etc# directory, +and the [.filename]#/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 [.filename]#/etc/sysctl.conf#. +In the section <<configtuning-sysctl>>, the operation of man:sysctl[8] will be explained in more detail. + +For more information about the FreeBSD file system structure refer to man: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. + +[NOTE] +==== +Some applications like man:pkg[8] are starting to use the link:https://github.com/vstakhov/libucl[Universal Configuration Language (UCL)]. +==== + +=== The [.filename]#/etc# directory + +The [.filename]#/etc# directory contains all of the FreeBSD base system configuration files that are responsible for configuring FreeBSD. + +[CAUTION] +==== +*Extreme* caution must be taken when modifying files in the [.filename]#/etc# directory; misconfiguration could make FreeBSD unbootable or malfunction. +==== + +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|[.filename]#/etc# +|System configuration files and scripts. + +|[.filename]#/etc/defaults# +|Default system configuration files, see man:rc[8] for more information. + +|[.filename]#/etc/fstab# +|man:fstab[5] contains descriptive information about the various file systems. + +|[.filename]#/etc/mail# +|Extra man:sendmail[8] configuration and other MTA configuration files. + +|[.filename]#/etc/mtree# +|mtree configuration files, see man: mtree[8] for more information. + +|[.filename]#/etc/pam.d# +|Configuration files for the Pluggable Authentication Modules (PAM) library. + +|[.filename]#/etc/periodic# +|Scripts that are run daily, weekly, and monthly, via man:cron[8], see man:periodic[8] for more information. + +|[.filename]#/etc/rc.d# +|System and daemon startup/control scripts, see man:rc[8] for more information. + +|[.filename]#/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 <<configtuning-core-configuration>> + +|[.filename]#/etc/security# +|OpenBSM audit configuration files, see man:audit[8] for more information. + +|[.filename]#/etc/ppp# +|ppp configuration files, see man:ppp[8] for more information. + +|[.filename]#/etc/ssh# +|OpenSSH configuration files, see man:ssh[1] for more information. + +|[.filename]#/etc/ssl# +|OpenSSL configuration files. + +|[.filename]#/etc/sysctl.conf# +|Contains settings for the kernel. More information in <<configtuning-sysctl>> + +|=== + +[[configtuning-sysctl]] +=== The sysctl utility + +The man:sysctl[8] utility is used to make changes to a running FreeBSD system. + +The man: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. -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 package:mail/postfix[] or package:www/apache22[] are just two of the many software packages which may be started during system initialization. -This section explains the procedures available for starting third party software. +.Management Information Base +[.informaltable] +[cols="1,1", frame="none"] +|=== + +|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, man:sysctl[8] serves two functions: to read and to modify system settings. + +To view all readable variables: + +[source,shell] +.... +% sysctl -a +.... -In FreeBSD, most included services, such as man:cron[8], are started through the system startup scripts. +The output should be similar to the following: + +[.programlisting] +.... +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: + +[source,shell] +.... +% sysctl kern.maxproc +.... + +The output should be similar to the following: + +[.programlisting] +.... +kern.maxproc: 1044 +.... + +The Management Information Base (MIB) is hierarchical and hence, specifying a prefix prints all the nodes hanging from it: + +[source,shell] +.... +% sysctl net +.... -=== Extended Application Configuration +The output should be similar to the following: + +[.programlisting] +.... +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: + +[source,shell] +.... +# sysctl kern.maxfiles=5000 +.... + +The output should be similar to the following: + +[.programlisting] +.... +kern.maxfiles: 2088 -> 5000 +.... + +[NOTE] +==== +To keep the configuration after a reboot it is necessary to add these variables to the [.filename]#/etc/sysctl.conf# file as explained below. +==== + +[[configtuning-sysctlconf]] +=== The [.filename]#/etc/sysctl.conf# file + +The configuration file for man:sysctl[8], [.filename]#/etc/sysctl.conf#, looks much like [.filename]#/etc/rc.conf#. + +Values are set using a `variable=value` syntax. + +[NOTE] +==== +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 [.filename]#/etc/sysctl.conf#: + +[.programlisting] +.... +# 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: + +[source,shell] +.... +% sysctl -d kern.dfldsiz +.... + +The output should be similar to the following: + +[.programlisting] +.... +kern.dfldsiz: Initial data size limit +.... + +[[configtuning-core-configuration]] +=== Managing System-Specific Configuration + +The principal location for system configuration information is [.filename]#/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 [.filename]#rc*# files. + +The entries in [.filename]#/etc/rc.conf# override the default settings in [.filename]#/etc/defaults/rc.conf#. + +[TIP] +==== +The file [.filename]#/etc/defaults/rc.conf# containing the default settings should not be edited. +Instead, all system-specific changes should be made to [.filename]#/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 [.filename]#/etc/rc.conf.local#. + +For example, these entries in [.filename]#/etc/rc.conf# apply to all systems: + +[.programlisting] +.... +sshd_enable="YES" +keyrate="fast" +defaultrouter="10.1.1.254" +.... + +Whereas these entries in [.filename]#/etc/rc.conf.local# apply to this system only: + +[.programlisting] +.... +hostname="node1.example.org" +ifconfig_fxp0="inet 10.1.1.1/8" +.... + +Distribute [.filename]#/etc/rc.conf# to every system using an application such as rsync or puppet, while [.filename]#/etc/rc.conf.local# remains unique. + +Upgrading the system will not overwrite [.filename]#/etc/rc.conf#, so system configuration information will not be lost. + +[TIP] +==== +Both [.filename]#/etc/rc.conf# and [.filename]#/etc/rc.conf.local# are parsed by man:sh[1]. +This allows system operators to create complex configuration scenarios. +Refer to man:rc.conf[5] for further information on this topic. +==== + +[[configtuning-rcd]] +== Managing Services in FreeBSD + +FreeBSD uses the man:rc[8] system of startup scripts during system initialization and for managing services. + +The scripts listed in [.filename]#/etc/rc.d# provide basic services which can be controlled with the `start`, `stop`, and `restart` options to man:service[8]. -Now that FreeBSD includes [.filename]#rc.d#, configuration of application startup is easier and provides more features. -Using the key words discussed in <<configtuning-rcd>>, applications can be set to start after certain other services and extra flags can be passed through [.filename]#/etc/rc.conf# in place of hard coded flags in the startup script. A basic script may look similar to the following: [.programlisting] @@ -108,17 +397,86 @@ pidfile=${utility_pidfile-"/var/run/utility.pid"} run_rc_command "$1" .... -This script will ensure that the provided `utility` will be started after the `DAEMON` pseudo-service. -It also provides a method for setting and tracking the process ID (PID). +Refer to extref:{rc-scripting}[this article] for instructions on how to create custom man:rc[8] scripts. + +[[configtuning-starting-services]] +=== 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 package:security/openssh-portable[] or package: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 man: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 [.filename]#/etc/rc.conf# variable is set. + +So the first step to start a service, like for example package:www/nginx[] is to add it to [.filename]#/etc/rc.conf# by executing the following command: + +[source,shell] +.... +# sysrc nginx_enable="YES" +.... + +Then nginx can be started executing the following command: + +[source,shell] +.... +# service nginx start +.... + +[TIP] +==== +To `start`, `stop` or `restart` a service regardless of the settings in [.filename]#/etc/rc.conf#, these commands should be prefixed with "one". +For instance, to start package:www/nginx[] regardless of the current [.filename]#/etc/rc.conf# setting, execute the following command: + +[source,shell] +.... +# service nginx onestart +.... +==== + +[[configtuning-status-services]] +=== Status of a Service + +To determine if a service is running, use the `status` subcommand. + +For example, to verify that package:www/nginx[] is running: + +[source,shell] +.... +# service nginx status +.... -This application could then have the following line placed in [.filename]#/etc/rc.conf#: +The output should be similar to the following: [.programlisting] .... -utility_enable="YES" +nginx is running as pid 27871. .... -This method allows for easier manipulation of command line arguments, inclusion of the default functions provided in [.filename]#/etc/rc.subr#, compatibility with man:rcorder[8], and provides for easier configuration via [.filename]#rc.conf#. +[[configtuning-reload-services]] +=== 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 man:rc[8] system is used for network services and it also contributes to most of the system initialization. +For instance, when the [.filename]#/etc/rc.d/bgfsck# script is executed, it prints out the following message: + +[source,shell] +.... +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, man:yp[8] and other RPC-based services may fail to start until after the man:rpcbind[8] service has started. + +Additional information can be found in man:rc[8] and man:rc.subr[8]. === Using Services to Start Services @@ -132,12 +490,21 @@ This allows regular users to start and maintain their own applications. The `@reboot` feature of man:cron[8], may be used in place of the time specification. This causes the job to run when man:cron[8] is started, normally during system initialization. +[[cron-periodic]] +== 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 man:cron[8]. + +In addition to tasks that can be scheduled by the user via man:cron[8], FreeBSD performs routine background tasks managed by man:periodic[8]. + [[configtuning-cron]] -== Configuring man:cron[8] +=== Cron + +The man:cron[8] utility runs in the background and regularly checks [.filename]#/etc/crontab# for tasks to execute and searches [.filename]#/var/cron/tabs# for custom crontab files. -One of the most useful utilities in FreeBSD is cron. -This utility runs in the background and regularly checks [.filename]#/etc/crontab# for tasks to execute and searches [.filename]#/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. @@ -155,14 +522,28 @@ Here is a sample entry from the system crontab, [.filename]#/etc/crontab#: .... # /etc/crontab - root's crontab for FreeBSD # -# $FreeBSD$ -# <.> +# $FreeBSD$ <.> +# SHELL=/bin/sh -PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <.> +PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin <.> +# +#minute hour mday month wday who command <.> +# +# Save some entropy so that /dev/random can re-seed on boot. +*/11 * * * * operator /usr/libexec/save-entropy <.> # -#minute hour mday month wday who command <.> +# Rotate log files every hour, if necessary. +0 * * * * root newsyslog # -*/5 * * * * root /usr/libexec/atrun <.> +# 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 + .... <.> Lines 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. @@ -171,7 +552,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <.> <.> This 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. -<.> This entry defines the values for this cron job. The `\*/5`, followed by several more `*` characters, specifies that `/usr/libexec/atrun` is invoked by `root` every five 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. +<.> This 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. [[configtuning-installcrontab]] === Creating a User Crontab @@ -192,9 +573,9 @@ It is useful to add these lines to the top of the crontab file in order to set t [.programlisting] .... SHELL=/bin/sh -PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin +PATH=/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin # Order of crontab fields -# minute hour mday month wday command +# minute hour mday month wday command .... Then add a line for each command or script to run, specifying the time to run the command. @@ -203,18 +584,17 @@ Since the path to the script is not specified in `PATH`, the full path to the sc [.programlisting] .... -0 14 * * * /usr/home/dru/bin/mycustomscript.sh +0 14 * * * /home/user/bin/mycustomscript.sh .... [TIP] ==== - 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: [.programlisting] .... -env -i SHELL=/bin/sh PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin HOME=/home/dru LOGNAME=dru /usr/home/dru/bin/mycustomscript.sh +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 man:crontab[5]. @@ -222,160 +602,93 @@ Checking that scripts operate correctly in a cron environment is especially impo ==== 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. +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: [source,shell] .... % crontab -l -0 14 * * * /usr/home/dru/bin/mycustomscript.sh .... -To remove all of the cron jobs in a user crontab: +The output should be similar to the following: -[source,shell] +[.programlisting] .... -% crontab -r -remove crontab for dru? y +0 14 * * * /home/user/bin/mycustomscript.sh .... -[[configtuning-rcd]] -== Managing Services in FreeBSD - -FreeBSD uses the man:rc[8] system of startup scripts during system initialization and for managing services. -The scripts listed in [.filename]#/etc/rc.d# provide basic services which can be controlled with the `start`, `stop`, and `restart` options to man:service[8]. -For instance, man:sshd[8] can be restarted with the following command: +To remove all of the cron jobs in a user crontab: [source,shell] .... -# service sshd restart +% crontab -r .... -This procedure can be used to start services on a running system. -Services will be started automatically at boot time as specified in man:rc.conf[5]. -For example, to enable man:natd[8] at system startup, add the following line to [.filename]#/etc/rc.conf#: +The output should be similar to the following: [.programlisting] .... -natd_enable="YES" +remove crontab for user? y .... -If a `natd_enable="NO"` line is already present, change the `NO` to `YES`. -The man:rc[8] scripts will automatically load any dependent services during the next boot, as described below. +[[configtuning-periodic]] +=== Periodic -Since the man: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 [.filename]#/etc/rc.conf# variable is set. -For instance, `sshd restart` will only work if `sshd_enable` is set to `YES` in [.filename]#/etc/rc.conf#. -To `start`, `stop` or `restart` a service regardless of the settings in [.filename]#/etc/rc.conf#, these commands should be prefixed with "one". -For instance, to restart man:sshd[8] regardless of the current [.filename]#/etc/rc.conf# setting, execute the following command: +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 man:periodic[8] and its configuration resides in man:periodic.conf[5]. +The periodic tasks are initiated by entries in the system crontab, shown above. -[source,shell] -.... -# service sshd onerestart -.... +Scripts executed by man:periodic[8] are located in [.filename]#/etc/periodic/# for base utilities and in [.filename]#/usr/local/etc/periodic/# for third-party software. -To check if a service is enabled in [.filename]#/etc/rc.conf#, run the appropriate man:rc[8] script with `rcvar`. -This example checks to see if man:sshd[8] is enabled in [.filename]#/etc/rc.conf#: +They are organized in 4 subdirectories, daily, weekly, monthly and security. -[source,shell] -.... -# service sshd rcvar -# sshd -# -sshd_enable="YES" -# (default: "") -.... +[[enable-disable-periodic]] +=== Enable or Disable Periodic Tasks -[NOTE] -==== -The `# sshd` line is output from the above command, not a `root` console. -==== +FreeBSD has some scripts enabled by default to run periodically. -To determine whether or not a service is running, use `status`. -For instance, to verify that man:sshd[8] is running: +To enable or disable a task, the first step is to edit [.filename]#/etc/periodic.conf# executing the following command: [source,shell] .... -# service sshd status -sshd is running as pid 433. +# ee /etc/periodic.conf .... -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. -Support for this feature is not included for every service. - -The man:rc[8] system is used for network services and it also contributes to most of the system initialization. -For instance, when the [.filename]#/etc/rc.d/bgfsck# script is executed, it prints out the following message: +And then to enable, for example, `daily_status_zfs_enable` put the following content in the file: -[source,shell] +[.programlisting] .... -Starting background file system checks in 60 seconds. +daily_status_zfs_enable="YES" .... -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, man:yp[8] and other RPC-based services may fail to start until after the man:rpcbind[8] service has started. -To resolve this issue, information about dependencies and other meta-data is included in the comments at the top of each startup script. -The man:rcorder[8] program is used to parse these comments during system initialization to determine the order in which system services should be invoked to satisfy the dependencies. - -The following key word must be included in all startup scripts as it is required by man:rc.subr[8] to "enable" the startup script: - -* `PROVIDE`: Specifies the services this file provides. - -The following key words may be included at the top of each startup script. -They are not strictly necessary, but are useful as hints to man:rcorder[8]: - -* `REQUIRE`: Lists services which are required for this service. The script containing this key word will run _after_ the specified services. -* `BEFORE`: Lists services which depend on this service. The script containing this key word will run _before_ the specified services. - -By carefully setting these keywords for each startup script, an administrator has a fine-grained level of control of the startup order of the scripts, without the need for "runlevels" used by some UNIX(R) operating systems. +To disable a task that is active by default, all that needs to be done is to change `YES` to `NO`. -Additional information can be found in man:rc[8] and man:rc.subr[8]. -Refer to extref:{rc-scripting}[this article] for instructions on how to create custom man:rc[8] scripts. - -[[configtuning-core-configuration]] -=== Managing System-Specific Configuration +[[configuring-output-periodic-tasks]] +=== Configuring the Output of Periodic Tasks -The principal location for system configuration information is [.filename]#/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 [.filename]#rc*# files. +In [.filename]#/etc/periodic.conf# the variables `daily_output`, `weekly_output` and `monthly_output` specifies where to send the results of the script execution. -The entries in [.filename]#/etc/rc.conf# override the default settings in [.filename]#/etc/defaults/rc.conf#. -The file containing the default settings should not be edited. -Instead, all system-specific changes should be made to [.filename]#/etc/rc.conf#. +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. -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 [.filename]#/etc/rc.conf.local#. -For example, these entries in [.filename]#/etc/rc.conf# apply to all systems: +To send the results to another email or to other emails, add the email addresses separated by spaces to [.filename]#/etc/periodic.conf#: [.programlisting] .... -sshd_enable="YES" -keyrate="fast" -defaultrouter="10.1.1.254" +daily_output="email1@example.com email2@example.com" +weekly_output="email1@example.com email2@example.com" +monthly_output="email1@example.com email2@example.com" .... -Whereas these entries in [.filename]#/etc/rc.conf.local# apply to this system only: +To log periodic output instead of receiving it as email, add the following lines to [.filename]#/etc/periodic.conf#. man:newsyslog[8] will rotate these files at the appropriate times: [.programlisting] .... -hostname="node1.example.org" -ifconfig_fxp0="inet 10.1.1.1/8" +daily_output=/var/log/daily.log +weekly_output=/var/log/weekly.log +monthly_output=/var/log/monthly.log .... -Distribute [.filename]#/etc/rc.conf# to every system using an application such as rsync or puppet, while [.filename]#/etc/rc.conf.local# remains unique. - -Upgrading the system will not overwrite [.filename]#/etc/rc.conf#, so system configuration information will not be lost. - -[TIP] -==== - -Both [.filename]#/etc/rc.conf# and [.filename]#/etc/rc.conf.local# are parsed by man:sh[1]. -This allows system operators to create complex configuration scenarios. -Refer to man:rc.conf[5] for further information on this topic. -==== - [[configtuning-syslog]] == Configuring System Logging @@ -384,11 +697,8 @@ The information in system logs can be used to detect hardware and software issue 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, to manage logging. -By default, syslogd is started when the system boots. -This is controlled by the variable `syslogd_enable` in [.filename]#/etc/rc.conf#. -There are numerous application arguments that can be set using `syslogd_flags` in [.filename]#/etc/rc.conf#. -Refer to man:syslogd[8] for more information on the available arguments. +FreeBSD provides a system logger, man: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. @@ -406,7 +716,8 @@ It is also possible to add an optional comparison flag before the level to speci 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 [.filename]#syslog.conf# from FreeBSD: + +As an example, here is the default [.filename]#/etc/syslog.conf# from FreeBSD: [.programlisting] .... @@ -417,18 +728,18 @@ As an example, here is the default [.filename]#syslog.conf# from FreeBSD: # 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 +*.err;kern.warning;auth.notice;mail.crit /dev/console <.> *.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 -lpr.info /var/log/lpd-errs -ftp.info /var/log/xferlog +mail.info /var/log/maillog <.> cron.* /var/log/cron !-devd -*.=debug /var/log/debug.log +*.=debug /var/log/debug.log <.> *.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 @@ -441,48 +752,177 @@ cron.* /var/log/cron # news.notice /var/log/news/news.notice # Uncomment this if you wish to see messages produced by devd # !devd -# *.>=info -!ppp -*.* /var/log/ppp.log +# *.>=notice /var/log/devd.log <.> !* +include /etc/syslog.d +include /usr/local/etc/syslog.d .... -In this example: +<.> Matches 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 ([.filename]#/dev/console#). +<.> Matches all messages from the `mail` facility at level `info` or above and logs the messages to [.filename]#/var/log/maillog#. +<.> Uses a comparison flag (`=`) to only match messages at level `debug` and logs them to [.filename]#/var/log/debug.log#. +<.> Is 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 man:devd[8] are logged to [.filename]#/var/log/devd.log#. + +For more information about [.filename]#/etc/syslog.conf#, its syntax, and more advanced usage examples, see man:syslog.conf[5]. + +[[logging-facilities]] +=== 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. + +.syslog facilities +[options="header", cols="1,1"] +|=== +| Name | Description + +| auth +| The authorization system: man:login[1], man:su[1], man:getty[8], etc. + +| authpriv +| The same as auth, but logged to a file readable only by root. + +| console +| Messages written to [.filename]#/dev/console# by the kernel console output driver. + +| cron +| Messages written by the man:cron[8] daemon. + +| daemon +| System daemons, such as man:routed[8], that are not provided for explicitly by other facilities. + +| ftp +| The file transfer protocol daemons: man:ftpd[8], man:tftpd[8]. + +| kern +| Messages generated by the kernel. These cannot be generated by any user processes. + +| lpr +| The line printer spooling system: man:lpr[1], man:lpc[8], man: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 man: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. + +|=== + +[[logging-levels]] +=== Logging Levels + +The level describes the severity of the message, and is a keyword from the following ordered list (higher to lower): + +.syslog levels +[options="header", cols="1,1"] +|=== +| Name | Description + +| 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. + +|=== + +[[read-log-messages]] +=== Read Log Messages -* Line 8 matches 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 ([.filename]#/dev/console#). -* Line 12 matches all messages from the `mail` facility at level `info` or above and logs the messages to [.filename]#/var/log/maillog#. -* Line 17 uses a comparison flag (`=`) to only match messages at level `debug` and logs them to [.filename]#/var/log/debug.log#. -* Line 33 is 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 ppp are logged to [.filename]#/var/log/ppp.log#. +By default FreeBSD log files use the format link:https://datatracker.ietf.org/doc/html/rfc3164[rfc3164], also known as The BSD syslog Protocol. +Learn more about other formats and how to use them at man:syslog[8]. -The available levels, in order from most to least critical are `emerg`, `alert`, `crit`, `err`, `warning`, `notice`, `info`, and `debug`. +Typically the logs have the following syntax: -The facilities, in no particular order, are `auth`, `authpriv`, `console`, `cron`, `daemon`, `ftp`, `kern`, `lpr`, `mail`, `mark`, `news`, `security`, `syslog`, `user`, `uucp`, and `local0` through `local7`. -Be aware that other operating systems might have different facilities. +[.programlisting] +.... +date time hostname program[pid]: the message +.... -To log everything of level `notice` and higher to [.filename]#/var/log/daemon.log#, add the following entry: +The output of the [.filename]#/var/log/cron# file will be used as an example: [.programlisting] .... -daemon.notice /var/log/daemon.log +[...] +Jul 16 12:40:00 FreeBSD /usr/sbin/cron[81519]: (root) CMD (/usr/libexec/atrun) *** 1192 LINES SKIPPED ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202308010932.3719WABe063709>