From owner-svn-doc-all@FreeBSD.ORG Mon Mar 24 13:53:42 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 4A8997C7; Mon, 24 Mar 2014 13:53:42 +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 2A32A8C1; Mon, 24 Mar 2014 13:53:42 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2ODrg9q015415; Mon, 24 Mar 2014 13:53:42 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2ODrfeu015412; Mon, 24 Mar 2014 13:53:41 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201403241353.s2ODrfeu015412@svn.freebsd.org> From: Dru Lavigne Date: Mon, 24 Mar 2014 13:53:41 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44341 - in head/en_US.ISO8859-1/books/handbook: config network-servers 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 13:53:42 -0000 Author: dru Date: Mon Mar 24 13:53:41 2014 New Revision: 44341 URL: http://svnweb.freebsd.org/changeset/doc/44341 Log: Initial prep work to combine 12.7 Configure System Logging and 28.12 Remote System Logging with syslogd. Rename some titles to be action oriented and not include utility name. This section still needs an editorial review. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/config/chapter.xml head/en_US.ISO8859-1/books/handbook/network-servers/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 11:00:35 2014 (r44340) +++ head/en_US.ISO8859-1/books/handbook/config/chapter.xml Mon Mar 24 13:53:41 2014 (r44341) @@ -1202,8 +1202,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n - Configuring the System Logger, - <command>syslogd</command> + Configuring System Logging @@ -1233,16 +1232,6 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n without a controlling terminal usually log information to a system logging facility or other log file. - This section describes how to configure and use the &os; - system logger, &man.syslogd.8;, and how to perform log rotation - and log management using &man.newsyslog.8;. Focus will be on - setting up and using &man.syslogd.8; on a local machine. For - more advanced setups using a separate loghost, see - . - - - Using <command>syslogd</command> - In the default &os; configuration, &man.syslogd.8; is started at boot. This is controlled by the variable syslogd_enable in @@ -1256,10 +1245,13 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n for more information about /etc/rc.conf and the &man.rc.8; subsystem. - + + This section describes how to configure and the &os; + system logger for both local and remote logging and how to perform log rotation + and log management. - Configuring <command>syslogd</command> + Configuring Local Logging syslog.conf @@ -1393,13 +1385,11 @@ cron.* facilities, refer to &man.syslog.3; and &man.syslogd.8;. For more information about /etc/syslog.conf, its syntax, and more - advanced usage examples, see &man.syslog.conf.5; and - . + advanced usage examples, see &man.syslog.conf.5;. - Log Management and Rotation with - <command>newsyslog</command> + Log Management and Rotation newsyslog newsyslog.conf @@ -1419,10 +1409,6 @@ cron.* &man.cron.8;, it is not a system daemon. In the default configuration, it is run every hour. - - Configuring - <command>newsyslog</command> - To know which actions to take, &man.newsyslog.8; reads its configuration file, by default /etc/newsyslog.conf. This @@ -1496,6 +1482,252 @@ cron.* &man.newsyslog.conf.5;. Since &man.newsyslog.8; is run from &man.cron.8;, it can not rotate files more often than it is run from &man.cron.8;. + + + + + Configuring Remote Logging + + + + + Tom + Rhodes + + Contributed by + + + + + 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. + + Centralized log file aggregation, merging, and rotation can + be configured using &os; native tools, such as &man.syslogd.8; + and &man.newsyslog.8;. 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 + + 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. + + + 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 &man.syslog.conf.5;. + + Next, configure /etc/rc.conf: + + 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. + + Finally, create the log file: + + &prompt.root; touch /var/log/logclient.log + + At this point, syslogd should + be restarted and verified: + + &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: + + 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: + + syslogd_flags="-d -a logclien.example.com -v -v" + + &prompt.root; 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: + + &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 +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. + + + + 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, &man.newsyslog.8;, + 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. Modified: head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Mon Mar 24 11:00:35 2014 (r44340) +++ head/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml Mon Mar 24 13:53:41 2014 (r44341) @@ -84,12 +84,6 @@ - How to configure the standard logging daemon, - syslogd, to accept logs from remote - hosts. - - - How to set up iSCSI. @@ -5396,254 +5390,6 @@ driftfile /var/db/ntp.drift - - - - Remote Host Logging with <command>syslogd</command> - - Interacting with system logs is a crucial aspect of both - security and system administration. 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. - - Centralized log file aggregation, merging, and rotation can - be configured using &os; native tools, such as &man.syslogd.8; - and &man.newsyslog.8;. 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 - - 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. - - - 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 &man.syslog.conf.5;. - - Next, configure /etc/rc.conf: - - 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. - - Finally, create the log file: - - &prompt.root; touch /var/log/logclient.log - - At this point, syslogd should - be restarted and verified: - - &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: - - 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: - - syslogd_flags="-d -a logclien.example.com -v -v" - - &prompt.root; 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: - - &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 -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. - - - - 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, &man.newsyslog.8;, - 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. - - -