svn commit: r44341 - in head/en_US.ISO8859-1/books/handbook: config network-servers
Dru Lavigne
dru at FreeBSD.org
Mon Mar 24 13:53:42 UTC 2014
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
<sect1 xml:id="configtuning-syslog">
<info>
- <title>Configuring the System Logger,
- <command>syslogd</command></title>
+ <title>Configuring System Logging</title>
<authorgroup>
<author>
@@ -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.</para>
- <para>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
- <xref linkend="network-syslogd"/>.</para>
-
- <sect2>
- <title>Using <command>syslogd</command></title>
-
<para>In the default &os; configuration, &man.syslogd.8; is
started at boot. This is controlled by the variable
<literal>syslogd_enable</literal> in
@@ -1256,10 +1245,13 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 n
<xref linkend="configtuning-rcd"/> for more information about
<filename>/etc/rc.conf</filename> and the &man.rc.8;
subsystem.</para>
- </sect2>
+
+ <para>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.</para>
<sect2>
- <title>Configuring <command>syslogd</command></title>
+ <title>Configuring Local Logging</title>
<indexterm><primary>syslog.conf</primary></indexterm>
@@ -1393,13 +1385,11 @@ cron.*
facilities, refer to &man.syslog.3; and &man.syslogd.8;.
For more information about
<filename>/etc/syslog.conf</filename>, its syntax, and more
- advanced usage examples, see &man.syslog.conf.5; and
- <xref linkend="network-syslogd"/>.</para>
+ advanced usage examples, see &man.syslog.conf.5;.</para>
</sect2>
<sect2>
- <title>Log Management and Rotation with
- <command>newsyslog</command></title>
+ <title>Log Management and Rotation</title>
<indexterm><primary>newsyslog</primary></indexterm>
<indexterm><primary>newsyslog.conf</primary></indexterm>
@@ -1419,10 +1409,6 @@ cron.*
&man.cron.8;, it is not a system daemon. In the default
configuration, it is run every hour.</para>
- <sect3>
- <title>Configuring
- <command>newsyslog</command></title>
-
<para>To know which actions to take, &man.newsyslog.8; reads
its configuration file, by default
<filename>/etc/newsyslog.conf</filename>. 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;.</para>
+ </sect2>
+
+ <sect2 xml:id="network-syslogd">
+ <info>
+ <title>Configuring Remote Logging</title>
+
+ <authorgroup>
+ <author>
+ <personname>
+ <firstname>Tom</firstname>
+ <surname>Rhodes</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ </info>
+
+ <para>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.</para>
+
+ <para>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 <systemitem>A</systemitem>, named
+ <systemitem
+ class="fqdomainname">logserv.example.com</systemitem>, will
+ collect logging information for the local network. Host
+ <systemitem>B</systemitem>, named <systemitem
+ class="fqdomainname">logclient.example.com</systemitem>, will
+ be configured to pass logging information to the logging
+ server.</para>
+
+ <sect3>
+ <title>Log Server Configuration</title>
+
+ <para>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:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>If there is a firewall between the logging server and
+ any logging clients, ensure that the firewall ruleset
+ allows <acronym>UDP</acronym> port 514 for both the
+ clients and the server.</para>
+ </listitem>
+
+ <listitem>
+ <para>The logging server and all client machines must have
+ forward and reverse entries in the local
+ <acronym>DNS</acronym>. If the network does not have a
+ <acronym>DNS</acronym> server, create entries in each
+ system's <filename>/etc/hosts</filename>. Proper name
+ resolution is required so that log entries are not
+ rejected by the logging server.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>On the log server, edit
+ <filename>/etc/syslog.conf</filename> 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
+ <systemitem>B</systemitem>, logs all facilities, and stores
+ the log entries in
+ <filename>/var/log/logclient.log</filename>.</para>
+
+ <example>
+ <title>Sample Log Server Configuration</title>
+
+ <programlisting>+logclient.example.com
+*.* /var/log/logclient.log</programlisting>
+ </example>
+
+ <para>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;.</para>
+
+ <para>Next, configure <filename>/etc/rc.conf</filename>:</para>
+
+ <programlisting>syslogd_enable="YES"
+syslogd_flags="-a logclient.example.com -v -v"</programlisting>
+
+ <para>The first entry starts <application>syslogd</application>
+ at system boot. The second entry allows log entries from the
+ specified client. The <option>-v -v</option> 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.</para>
+
+ <para>Multiple <option>-a</option> options may be specified to
+ allow logging from multiple clients. <acronym>IP</acronym>
+ addresses and whole netblocks may also be specified. Refer to
+ &man.syslogd.8; for a full list of possible options.</para>
+
+ <para>Finally, create the log file:</para>
+
+ <screen>&prompt.root; <userinput>touch /var/log/logclient.log</userinput></screen>
+
+ <para>At this point, <application>syslogd</application> should
+ be restarted and verified:</para>
+
+ <screen>&prompt.root; <userinput>service syslogd restart</userinput>
+&prompt.root; <userinput>pgrep syslog</userinput></screen>
+
+ <para>If a <acronym>PID</acronym> is returned, the server
+ restarted successfully, and client configuration can begin.
+ If the server did not restart, consult
+ <filename>/var/log/messages</filename> for the error.</para>
+ </sect3>
+
+ <sect3>
+ <title>Log Client Configuration</title>
+
+ <para>A logging client sends log entries to a logging server on
+ the network. The client also keeps a local copy of its own
+ logs.</para>
+
+ <para>Once a logging server has been configured, edit
+ <filename>/etc/rc.conf</filename> on the logging
+ client:</para>
+
+ <programlisting>syslogd_enable="YES"
+syslogd_flags="-s -v -v"</programlisting>
+
+ <para>The first entry enables <application>syslogd</application>
+ on boot up. The second entry prevents logs from being
+ accepted by this client from other hosts (<option>-s</option>)
+ and increases the verbosity of logged messages.</para>
+
+ <para>Next, define the logging server in the client's
+ <filename>/etc/syslog.conf</filename>. In this example, all
+ logged facilities are sent to a remote system, denoted by the
+ <literal>@</literal> symbol, with the specified
+ hostname:</para>
+
+ <programlisting>*.* @logserv.example.com</programlisting>
+
+ <para>After saving the edit, restart
+ <application>syslogd</application> for the changes to take
+ effect:</para>
+
+ <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen>
+
+ <para>To test that log messages are being sent across the
+ network, use &man.logger.1; on the client to send a message to
+ <application>syslogd</application>:</para>
+
+ <screen>&prompt.root; <userinput>logger "<replaceable>Test message from logclient</replaceable>"</userinput></screen>
+
+ <para>This message should now exist both in
+ <filename>/var/log/messages</filename> on the client and
+ <filename>/var/log/logclient.log</filename> on the log
+ server.</para>
+ </sect3>
+
+ <sect3>
+ <title>Debugging Log Servers</title>
+
+ <para>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 <command>ping</command> each other
+ using the hostname specified in their
+ <filename>/etc/rc.conf</filename>. If this fails, check the
+ network cabling, the firewall ruleset, and the hostname
+ entries in the <acronym>DNS</acronym> server or
+ <filename>/etc/hosts</filename> on both the logging server and
+ clients. Repeat until the <command>ping</command> is
+ successful from both hosts.</para>
+
+ <para>If the <command>ping</command> 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,
+ <filename>/var/log/logclient.log</filename> on the logging
+ server is empty and <filename>/var/log/messages</filename> on
+ the logging client does not indicate a reason for the failure.
+ To increase debugging output, edit the
+ <literal>syslogd_flags</literal> entry on the logging server
+ and issue a restart:</para>
+
+ <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting>
+
+ <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen>
+
+ <para>Debugging data similar to the following will flash on the
+ console immediately after the restart:</para>
+
+ <screen>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.</screen>
+
+ <para>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 <literal>logclient</literal>, not
+ <literal>logclien</literal>. Fix the typo, issue a restart,
+ and verify the results:</para>
+
+ <screen>&prompt.root; <userinput>service syslogd restart</userinput>
+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</screen>
+
+ <para>At this point, the messages are being properly received
+ and placed in the correct file.</para>
+ </sect3>
+
+ <sect3>
+ <title>Security Considerations</title>
+
+ <para>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 <package>security/stunnel</package>, which will transmit
+ the logging data over an encrypted tunnel.</para>
+
+ <para>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 <literal>600</literal>
+ should prevent unwanted access by local users. Refer to
+ &man.newsyslog.conf.5; for additional information.</para>
</sect3>
</sect2>
</sect1>
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 @@
</listitem>
<listitem>
- <para>How to configure the standard logging daemon,
- <command>syslogd</command>, to accept logs from remote
- hosts.</para>
- </listitem>
-
- <listitem>
<para>How to set up <acronym>iSCSI</acronym>.</para>
</listitem>
</itemizedlist>
@@ -5396,254 +5390,6 @@ driftfile /var/db/ntp.drift</programlist
</sect2>
</sect1>
- <sect1 xml:id="network-syslogd">
- <!--
- <sect1info>
- <authorgroup>
- <author>
- <firstname>Tom</firstname>
- <surname>Rhodes</surname>
- <contrib>Contributed by </contrib>
- </author>
- </authorgroup>
- </sect1info>
- -->
-
- <title>Remote Host Logging with <command>syslogd</command></title>
-
- <para>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.</para>
-
- <para>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 <systemitem>A</systemitem>, named
- <systemitem
- class="fqdomainname">logserv.example.com</systemitem>, will
- collect logging information for the local network. Host
- <systemitem>B</systemitem>, named <systemitem
- class="fqdomainname">logclient.example.com</systemitem>, will
- be configured to pass logging information to the logging
- server.</para>
-
- <sect2>
- <title>Log Server Configuration</title>
-
- <para>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:</para>
-
- <itemizedlist>
- <listitem>
- <para>If there is a firewall between the logging server and
- any logging clients, ensure that the firewall ruleset
- allows <acronym>UDP</acronym> port 514 for both the
- clients and the server.</para>
- </listitem>
-
- <listitem>
- <para>The logging server and all client machines must have
- forward and reverse entries in the local
- <acronym>DNS</acronym>. If the network does not have a
- <acronym>DNS</acronym> server, create entries in each
- system's <filename>/etc/hosts</filename>. Proper name
- resolution is required so that log entries are not
- rejected by the logging server.</para>
- </listitem>
- </itemizedlist>
-
- <para>On the log server, edit
- <filename>/etc/syslog.conf</filename> 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
- <systemitem>B</systemitem>, logs all facilities, and stores
- the log entries in
- <filename>/var/log/logclient.log</filename>.</para>
-
- <example>
- <title>Sample Log Server Configuration</title>
-
- <programlisting>+logclient.example.com
-*.* /var/log/logclient.log</programlisting>
- </example>
-
- <para>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;.</para>
-
- <para>Next, configure <filename>/etc/rc.conf</filename>:</para>
-
- <programlisting>syslogd_enable="YES"
-syslogd_flags="-a logclient.example.com -v -v"</programlisting>
-
- <para>The first entry starts <application>syslogd</application>
- at system boot. The second entry allows log entries from the
- specified client. The <option>-v -v</option> 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.</para>
-
- <para>Multiple <option>-a</option> options may be specified to
- allow logging from multiple clients. <acronym>IP</acronym>
- addresses and whole netblocks may also be specified. Refer to
- &man.syslogd.8; for a full list of possible options.</para>
-
- <para>Finally, create the log file:</para>
-
- <screen>&prompt.root; <userinput>touch /var/log/logclient.log</userinput></screen>
-
- <para>At this point, <application>syslogd</application> should
- be restarted and verified:</para>
-
- <screen>&prompt.root; <userinput>service syslogd restart</userinput>
-&prompt.root; <userinput>pgrep syslog</userinput></screen>
-
- <para>If a <acronym>PID</acronym> is returned, the server
- restarted successfully, and client configuration can begin.
- If the server did not restart, consult
- <filename>/var/log/messages</filename> for the error.</para>
- </sect2>
-
- <sect2>
- <title>Log Client Configuration</title>
-
- <para>A logging client sends log entries to a logging server on
- the network. The client also keeps a local copy of its own
- logs.</para>
-
- <para>Once a logging server has been configured, edit
- <filename>/etc/rc.conf</filename> on the logging
- client:</para>
-
- <programlisting>syslogd_enable="YES"
-syslogd_flags="-s -v -v"</programlisting>
-
- <para>The first entry enables <application>syslogd</application>
- on boot up. The second entry prevents logs from being
- accepted by this client from other hosts (<option>-s</option>)
- and increases the verbosity of logged messages.</para>
-
- <para>Next, define the logging server in the client's
- <filename>/etc/syslog.conf</filename>. In this example, all
- logged facilities are sent to a remote system, denoted by the
- <literal>@</literal> symbol, with the specified
- hostname:</para>
-
- <programlisting>*.* @logserv.example.com</programlisting>
-
- <para>After saving the edit, restart
- <application>syslogd</application> for the changes to take
- effect:</para>
-
- <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen>
-
- <para>To test that log messages are being sent across the
- network, use &man.logger.1; on the client to send a message to
- <application>syslogd</application>:</para>
-
- <screen>&prompt.root; <userinput>logger "<replaceable>Test message from logclient</replaceable>"</userinput></screen>
-
- <para>This message should now exist both in
- <filename>/var/log/messages</filename> on the client and
- <filename>/var/log/logclient.log</filename> on the log
- server.</para>
- </sect2>
-
- <sect2>
- <title>Debugging Log Servers</title>
-
- <para>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 <command>ping</command> each other
- using the hostname specified in their
- <filename>/etc/rc.conf</filename>. If this fails, check the
- network cabling, the firewall ruleset, and the hostname
- entries in the <acronym>DNS</acronym> server or
- <filename>/etc/hosts</filename> on both the logging server and
- clients. Repeat until the <command>ping</command> is
- successful from both hosts.</para>
-
- <para>If the <command>ping</command> 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,
- <filename>/var/log/logclient.log</filename> on the logging
- server is empty and <filename>/var/log/messages</filename> on
- the logging client does not indicate a reason for the failure.
- To increase debugging output, edit the
- <literal>syslogd_flags</literal> entry on the logging server
- and issue a restart:</para>
-
- <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting>
-
- <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen>
-
- <para>Debugging data similar to the following will flash on the
- console immediately after the restart:</para>
-
- <screen>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.</screen>
-
- <para>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 <literal>logclient</literal>, not
- <literal>logclien</literal>. Fix the typo, issue a restart,
- and verify the results:</para>
-
- <screen>&prompt.root; <userinput>service syslogd restart</userinput>
-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</screen>
-
- <para>At this point, the messages are being properly received
- and placed in the correct file.</para>
- </sect2>
-
- <sect2>
- <title>Security Considerations</title>
-
- <para>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 <package>security/stunnel</package>, which will transmit
- the logging data over an encrypted tunnel.</para>
-
- <para>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 <literal>600</literal>
- should prevent unwanted access by local users. Refer to
- &man.newsyslog.conf.5; for additional information.</para>
- </sect2>
- </sect1>
-
<sect1 xml:id="network-iscsi">
<!--
<sect1info>
More information about the svn-doc-head
mailing list