doc: add more details to log rotation doc

diff --git a/doc/userguide/configuration/suricata-yaml.rst b/doc/userguide/configuration/suricata-yaml.rst
index e69859c0f7be47cd65703fc1f8b7c4ab84dcef46..1b5e9cce5862e88a8dfba23567d034df9f5d3b00 100644 (file)
--- a/doc/userguide/configuration/suricata-yaml.rst
+++ b/doc/userguide/configuration/suricata-yaml.rst
@@ -209,6 +209,8 @@ with the -l command line parameter, enter the following:
 
   suricata -c suricata.yaml -i eth0 -l /var/log/suricata-logs/
 
+.. _suricata_yaml_outputs:
+
 Outputs
 ~~~~~~~
 
@@ -363,6 +365,8 @@ For more advanced configuration options, see :ref:`Eve JSON Output <eve-json-out
 
 The format is documented in :ref:`Eve JSON Format <eve-json-format>`.
 
+.. _suricata_yaml_unified2:
+
 Alert output for use with Barnyard2 (unified2.alert)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -503,6 +507,8 @@ Configuration options:
       append: yes                 # If this option is set to yes, the (if any exists) dns.log file wil not be overwritten while restarting Suricata.
       filetype: regular / unix_stream / unix_dgram
 
+.. _suricata_yaml_pcap_log:
+
 Packet log (pcap-log)
 ~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/doc/userguide/output/eve/eve-json-output.rst b/doc/userguide/output/eve/eve-json-output.rst
index 8dce34994f5557dfac5c6480660f1c38961ac0b8..faac2ecb151ddc6b61e5c1f7b9fbfeda1916b31e 100644 (file)
--- a/doc/userguide/output/eve/eve-json-output.rst
+++ b/doc/userguide/output/eve/eve-json-output.rst
@@ -234,6 +234,8 @@ The example above adds epoch time to the filename. All the date modifiers from t
 C library should be supported. See the man page for ``strftime`` for all supported
 modifiers.
 
+.. _output_eve_rotate:
+
 Rotate log file
 ~~~~~~~~~~~~~~~
 

diff --git a/doc/userguide/output/log-rotation.rst b/doc/userguide/output/log-rotation.rst
index 85c4a63e75b8eacf21ab203f09270bc300d2cf84..e15e857e7a85adf8dd3390d35e90b3592fc11da1 100644 (file)
--- a/doc/userguide/output/log-rotation.rst
+++ b/doc/userguide/output/log-rotation.rst
@@ -1,12 +1,22 @@
 Log Rotation
 ============
 
-Suricata can generate lot of output, so it's important to manage the files
-to avoid issues with disks filling up.
+All outputs in the :ref:`outputs <suricata_yaml_outputs>` section of
+the configuration file can be subject to log rotation.
 
-A HUP signal sent to Suricata will force it to reopen the logfiles.
+For most outputs an external tool like *logrotate* is required to
+rotate the log files in combination with sending a SIGHUP to Suricata
+to notify it that the log files have been rotated.
 
-Example logrotate file:
+On receipt of a SIGHUP, Suricata simply closes all open log files and
+then re-opens them in append mode. If the external tool has renamed
+any of the log files, new files will be created, otherwise the files
+will be re-opened and new data will be appended to them with no
+noticeable affect.
+
+The following is an example *logrotate* configuration file that will
+rotate Suricata log files then send Suricata a SIGHUP triggering
+Suricata to open new files:
 
 ::
 
@@ -18,7 +28,20 @@ Example logrotate file:
       create
       sharedscripts
       postrotate
-              /bin/kill -HUP $(cat /var/run/suricata.pid)
+              /bin/kill -HUP `cat /var/run/suricata.pid 2>/dev/null` 2>/dev/null || true
       endscript
   }
 
+.. note:: The above *logrotate* configuration file depends on the
+          existence of a Suricata PID file. If running in daemon mode
+          a PID file will be created by default, otherwise the
+          :option:`--pidfile` option should be used to create a PID file.
+
+In addition to the SIGHUP style rotation discussed above, some outputs
+support their own time and date based rotation, however removal of old
+log files is still the responsibility of external tools. These outputs
+include:
+
+- :ref:`Eve <output_eve_rotate>`
+- :ref:`Unified2 <suricata_yaml_unified2>`
+- :ref:`PCAP log <suricata_yaml_pcap_log>`