From owner-svn-doc-all@FreeBSD.ORG Mon Mar 24 21:22:34 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 47E94E2C; Mon, 24 Mar 2014 21:22:34 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 331C1C65; Mon, 24 Mar 2014 21:22:34 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2OLMYlo003697; Mon, 24 Mar 2014 21:22:34 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2OLMYGM003696; Mon, 24 Mar 2014 21:22:34 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403242122.s2OLMYGM003696@svn.freebsd.org> From: Dru Lavigne Date: Mon, 24 Mar 2014 21:22:34 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44346 - head/en_US.ISO8859-1/books/handbook/config X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 24 Mar 2014 21:22:34 -0000 Author: dru Date: Mon Mar 24 21:22:33 2014 New Revision: 44346 URL: http://svnweb.freebsd.org/changeset/doc/44346 Log: White space fix only. Translators can ignore. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Mar 24 20:55:36 2014 (r44345) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Mar 24 21:22:33 2014 (r44346) @@ -568,8 +568,8 @@ sshd is running as pid 433. 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 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 @@ -587,9 +587,10 @@ defaultrouter="10.1.1.254" Distribute /etc/rc.conf to every - system using an application such as rsync or - puppet, - while /etc/rc.conf.local remains + system using an application such as + rsync or + puppet, while + /etc/rc.conf.local remains unique. Upgrading the system will not overwrite @@ -1202,7 +1203,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n - Configuring System Logging + Configuring System Logging @@ -1225,26 +1226,28 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n &man.syslogd.8; - 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. + 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. &os; 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 - /etc/rc.conf. There are numerous - application arguments that can be set using - syslogd_flags in - /etc/rc.conf. Refer to &man.syslogd.8; - for more information on the available arguments. - - This section describes how to configure the &os; - system logger for both local and remote logging and how to perform log rotation - and log management. + default, syslogd is started when the + system boots. This is controlled by the variable + syslogd_enable in + /etc/rc.conf. There are numerous + application arguments that can be set using + syslogd_flags in + /etc/rc.conf. Refer to &man.syslogd.8; for + more information on the available arguments. + + This section describes how to configure the &os; system + logger for both local and remote logging and how to perform log + rotation and log management. Configuring Local Logging @@ -1253,29 +1256,29 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n 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 + 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. + 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 + 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 @@ -1292,7 +1295,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n *.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 +mail.info /var/log/maillog lpr.info /var/log/lpd-errs ftp.info /var/log/xferlog cron.* /var/log/cron @@ -1312,15 +1315,15 @@ cron.* # news.notice /var/log/news/news.notice # Uncomment this if you wish to see messages produced by devd # !devd -# *.>=info +# *.>=info !ppp *.* /var/log/ppp.log !* In this example: - - + + Line 8 matches all messages with a level of err or higher, as well as kern.warning, @@ -1328,38 +1331,37 @@ cron.* mail.crit, and sends these log messages to the console (/dev/console). - + - Line 12 matches all messages from the mail - facility at level info or above and - logs the messages to + Line 12 matches all messages from the + mail facility at level + info or above and logs the messages to /var/log/maillog. - + Line 17 uses a comparison flag (=) to only match messages at level debug and logs them to /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 + 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 - /var/log/ppp.log. - - + logged to /var/log/ppp.log. + + The available levels, in order from most to least - critical are emerg, alert, - crit, err, - warning, notice, - info, and debug. + critical are emerg, + alert, crit, + err, warning, + notice, info, and + debug. The facilities, in no particular order, are auth, authpriv, @@ -1373,10 +1375,9 @@ cron.* local7. Be aware that other operating systems might have different facilities. - To log everything - of level notice and - higher to /var/log/daemon.log, add - the following entry: + To log everything of level notice and + higher to /var/log/daemon.log, add the + following entry: daemon.notice /var/log/daemon.log @@ -1395,30 +1396,30 @@ cron.* log rotation log management - Log files can grow quickly, taking up disk space and - making it more difficult to locate useful - information. Log management - attempts to mitigate this. In &os;, newsyslog is used - to manage log files. This built-in program periodically rotates and + Log files can grow quickly, taking up disk space and + making it more difficult to locate useful information. Log + management attempts to mitigate this. In &os;, + newsyslog is used to manage log + files. This built-in program periodically rotates and compresses log files, and optionally creates missing log files and signals programs when log files are moved. The log files - may be generated by syslogd or - by any other program which generates log files. - While syslogd is normally run from + may be generated by syslogd or by + any other program which generates log files. While + syslogd is normally run from &man.cron.8;, it is not a system daemon. In the default configuration, it runs every hour. - To know which actions to take, newsyslog reads - its configuration file, - /etc/newsyslog.conf. This - file contains one line for each log file that - newsyslog manages. Each line states the file - owner, permissions, when to rotate that file, optional flags - that affect log rotation, such as compression, and programs - to signal when the log is rotated. Here is the default - configuration in &os;: + To know which actions to take, + newsyslog reads its configuration + file, /etc/newsyslog.conf. This file + contains one line for each log file that + newsyslog manages. Each line + states the file owner, permissions, when to rotate that file, + optional flags that affect log rotation, such as compression, + and programs to signal when the log is rotated. Here is the + default configuration in &os;: - # configuration file for newsyslog + # configuration file for newsyslog # $FreeBSD$ # # Entries which do not specify the '/pid_file' field will cause the @@ -1458,36 +1459,33 @@ cron.* /var/log/weekly.log 640 5 1 $W6D0 JN /var/log/xferlog 600 7 100 * JC - Each line starts with the name of the log to be - rotated, optionally followed by an owner and group for both - rotated and newly created files. The - mode field sets the permissions on the - log file and count denotes how many - rotated log files should be kept. The - size and when fields - tell newsyslog when to rotate the file. A log - file is rotated when either its size is larger than the - size field or when the time in the - when filed has passed. - An asterisk (*) means that this field is ignored. The - flags field gives - further instructions, such as how to - compress the rotated file or to create the log file if it - is missing. 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. - - For more information on all fields, valid - flags, and how to specify the rotation time, refer to - &man.newsyslog.conf.5;. Since newsyslog is run from - &man.cron.8;, it can not rotate files more often than it is - scheduled to run from &man.cron.8;. + Each line starts with the name of the log to be rotated, + optionally followed by an owner and group for both rotated and + newly created files. The mode field sets + the permissions on the log file and count + denotes how many rotated log files should be kept. The + size and when fields + tell newsyslog when to rotate the + file. A log file is rotated when either its size is larger + than the size field or when the time in the + when filed has passed. An asterisk + (*) means that this field is ignored. The + flags field gives further + instructions, such as how to compress the rotated file or to + create the log file if it is missing. 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. + + For more information on all fields, valid flags, and how + to specify the rotation time, refer to &man.newsyslog.conf.5;. + Since newsyslog is run from + &man.cron.8;, it can not rotate files more often than it is + scheduled to run from &man.cron.8;. - - + + Configuring Remote Logging @@ -1501,182 +1499,188 @@ cron.* - 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 &os;, centralized log file aggregation, merging, and rotation can - be configured using syslogd - andnewsyslog. This section demonstrates an example - configuration, where host A, named - logserv.example.com, will - collect logging information for the local network. Host + 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 &os;, 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. - - Log Server Configuration + + 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: + 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. - + + + 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. - - + + 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. + 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. - - Sample Log Server Configuration + + Sample Log Server Configuration - +logclient.example.com + +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 &man.syslog.conf.5;. + When adding multiple log clients, add a similar two-line + entry for each client. More information about the available + facilities may be found in &man.syslog.conf.5;. - Next, configure /etc/rc.conf: + Next, configure + /etc/rc.conf: - syslogd_enable="YES" + syslogd_enable="YES" 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 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 options may be specified to - allow logging from multiple clients. IP - addresses and whole netblocks may also be specified. Refer to - &man.syslogd.8; for a full list of possible options. + The first entry starts + syslogd at system boot. The + second entry allows log entries from the specified client. + The 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 options may be specified to + allow logging from multiple clients. IP + addresses and whole netblocks may also be specified. Refer + to &man.syslogd.8; for a full list of possible + options. - Finally, create the log file: + Finally, create the log file: - &prompt.root; touch /var/log/logclient.log + &prompt.root; touch /var/log/logclient.log - At this point, syslogd should - be restarted and verified: + At this point, syslogd should + be restarted and verified: - &prompt.root; service syslogd restart + &prompt.root; service syslogd restart &prompt.root; 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. - - - - 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, edit - /etc/rc.conf on the logging - client: + 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. + + + + 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, edit + /etc/rc.conf on the logging + client: - syslogd_enable="YES" + syslogd_enable="YES" 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 () - 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: - - &prompt.root; service syslogd restart - - To test that log messages are being sent across the - network, use &man.logger.1; on the client to send a message to - syslogd: - - &prompt.root; 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. - - - - 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: + The first entry enables + syslogd on boot up. The second + entry prevents logs from being accepted by this client from + other hosts () 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: + + &prompt.root; service syslogd restart + + To test that log messages are being sent across the + network, use &man.logger.1; on the client to send a message + to syslogd: + + &prompt.root; 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. + + + + Debugging Log Servers - syslogd_flags="-d -a logclien.example.com -v -v" + 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: - &prompt.root; service syslogd restart + syslogd_flags="-d -a logclien.example.com -v -v" - Debugging data similar to the following will flash on the - console immediately after the restart: + &prompt.root; service syslogd restart - logmsg: pri 56, flags 4, from logserv.example.com, msg 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 @@ -1685,13 +1689,13 @@ 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: + 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: - &prompt.root; service syslogd restart + &prompt.root; service syslogd 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 @@ -1705,31 +1709,33 @@ logmsg: pri 15, flags 0, from logclient. 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. - - - - 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 - &man.newsyslog.conf.5; for additional information. + At this point, the messages are being properly received + and placed in the correct file. + + + + 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 + &man.newsyslog.conf.5; for additional information.