\" Copyright (c) 2022, Peter Haag
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions are met:
.\"
.\"  * Redistributions of source code must retain the above copyright notice,
.\"    this list of conditions and the following disclaimer.
.\"  * Redistributions in binary form must reproduce the above copyright notice,
.\"    this list of conditions and the following disclaimer in the documentation
.\"    and/or other materials provided with the distribution.
.\"  * Neither the name of the author nor the names of its contributors may be
.\"    used to endorse or promote products derived from this software without
.\"    specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
.\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate$
.Dt NFEXPIRE 1
.Os
.Sh NAME
.Nm nfexpire
.Nd manage expiration of flow files based on time or volume.
.Sh SYNOPSIS
.Nm 
.Fl l Ar directory
.Nm
.Fl r Ar directory
.Nm
.Fl e Ar directory
.Op Fl s Ar maxsize
.Op Fl t Ar maxlife
.Op Fl w Ar watermark
.Op Fl T Ar runtime
.Nm
.Fl u Ar path
.Op Fl s Ar maxsize
.Op Fl t Ar maxlife
.Op Fl w Ar watermark
.Sh DESCRIPTION
.Nm
manages the expiration of netflow data files based on their lifetime and/or the total volume
of all flow files. The flow files are usually created be any nfdump collector (
.Ar nfcapd
.Ar sfcapd
or
.Ar nfpcapd
)
.Pp
.Nm
is used to setup the expire parameters (maintenance mode) or to actually run the expire
process (expire mode) based on these parameters. The expire process can be triggered by either
a cron job, by the collector process itself (nfcapd, sfcapd auto expire mode), or by running
.Nm
manually. 
.Pp
.Nm
interacts with the collector, therefore it is safe to setup and expire files from a directory
which is used by any collector to store flow files.
.Pp
.Nm
stores a statistics file
.Ar .nfstat
in the given directory to maintain the status and parameters. You should not modify this file
manually unless you know what you do. The
.Ar directory
argument for
.Nm
corresponds to the
.Ar -l
argument on the collector command line.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl l Ar directory
List the current expire statistics from directory datadir. If this is the first time
.Nm
runs on this
.Ar directory
it automatically rescans the flow files first to update the statistics. If this an 
active data directory used by any collector, the statistics are updated automatically.
.It Fl r Ar directory
Rescans the data directory, even if a statistics file already exist. This command
can be used to update the statistics after a disk full event, after manually changing
the compression of the files, or if files have been deleted manually or manipulated
otherwise.
.It Fl e Ar directory
Expire data files according to the parameters
.Ar maxsize
and
.Ar maxlife .
The expire parameters are taken from the statfile, if they were previously set with
.Fl u
or they can be overwritten with the additional options
.Fl s t
and
.Fl w .
Files are deleted from the oldest towards the latest according both limits and
stops at the
.Ar watermark
below the limit.
.It Fl u Ar directory
Updates the expire parameters such as size and lifetime limits, specified by
.Fl s t
and
.Fl w
and stores them in the statfile as default values. Any running collector process in auto 
expire mode will take these new values starting with the next expire cycle. 
Running nfexpire the next time in expire mode will take these new parameters unless they 
will be overwritten by the arguments
.Fl s t
and
.Fl w .
.It Fl s Ar maxsize
This option sets the max size limit for all data files.
.Ar maxsize
accepts values such as 100M, 100MB 1G 1.5G (number + quantity factor) etc. Accpeted size 
factors are K, KB, M, MB, G, GB and T, TB. If no factor is given, bytes (B) is assumed.
A value of 0 disables the max size limit.
.It Fl t Ar maxlife
This option sets the max lifetime for the data files. 
.Ar maxlife
accepts values such as 31d, 240H 1.5d (number + quantity factor) etc. Accpeted time
factors are w (weeks) d (days) H (hours). If no factor is given, hours (H) is assumed.
A value of 0 disables the max lifetime limit.
.It Fl w Ar watermark
This options sets the water mark in % of any limit. It applies to both limits
.Ar maxsize
and
.Ar maxlife .
The expire process is triggered if any of the limits are hit and stops, if the new value reaches the
.Ar watermark
level in % of the limit. This means files are allowed to grow between 
.Ar watermark
% lower level and 100% upper level. The default for 
.Ar watermark
is 95%.
.It Fl T Ar runtime
This option forces
.Nm
to end the expire task after
.Ar runtime
seconds, even if the task is not yet completed.
.Nm
updates the statistics and exists cleanly, so it will pick up next time where it left.
By default nfexpire runs until the task is done.
.It Fl p 
This option puts
.Nm
in profile mode. Only legacy NfSen will need this option.
.It Fl Y
This option prints a NfSen compatible statistic. Only legacy NfSen will need this option.
.It Fl h
Print help text on stdout with all options and exit.
.El
.Sh RETURN VALUES
.Nm
returns 0 on success and 255 otherwise.
.Sh SEE ALSO
.Xr nfdump 1
.Xr nfcapd 1
.Xr sfcapd 1