Kea 3.0.0
isc::legal_log::RotatingFile Class Reference

RotatingFile implements an appending text file which rotates to a new file on a daily basis. More...

#include <rotating_file.h>

Inheritance diagram for isc::legal_log::RotatingFile:

Public Types

enum class  TimeUnit { Second , Day , Month , Year }
 Time unit type used to rotate file. More...

Public Member Functions

 RotatingFile (const isc::db::DatabaseConnection::ParameterMap &parameters)
 Constructor.
virtual ~RotatingFile ()
 Destructor.
void apply (const isc::db::DatabaseConnection::ParameterMap &parameters)
 Parse file specification and create forensic log backend.
virtual void close ()
 Closes the underlying file.
std::string getBaseName () const
 Returns the file base name.
std::string getFileName () const
 Returns the current file name.
std::string getPath () const
 Returns the file path.
virtual std::string getType () const
 Return backend type.
virtual void open ()
 Opens the current file for writing.
void updateFileNameAndTimestamp (struct tm &time_info, bool use_existing)
 Function which updates the file name and internal timestamp from previously created file name (if it can still be used).
virtual void writeln (const std::string &text, const std::string &addr)
 Appends a string to the current file.
Public Member Functions inherited from isc::dhcp::LegalLogMgr
 LegalLogMgr (const isc::db::DatabaseConnection::ParameterMap parameters)
 Constructor.
virtual ~LegalLogMgr ()=default
 Destructor.
virtual struct tm currentTimeInfo () const
 Returns the current local date and time.
virtual std::string getNowString () const
 Returns the current date and time as string.
virtual std::string getNowString (const std::string &format) const
 Returns the current date and time as a string using a specific strftime format string.
virtual isc::db::DatabaseConnection::ParameterMap getParameters () const
 Return backend parameters.
isc::dhcp::ExpressionPtr getRequestFormatExpression ()
 Gets request extended format expression for custom logging.
isc::dhcp::ExpressionPtr getResponseFormatExpression ()
 Gets response extended format expression for custom logging.
std::string getTimestampFormat ()
 Gets the timestamp format used for logging.
virtual bool isUnusable ()
 Flag which indicates if the forensic log backend has at least one unusable connection.
virtual struct timespec now () const
 Returns the current system time.
virtual void setParameters (isc::db::DatabaseConnection::ParameterMap parameters)
 Sets backend parameters.
void setRequestFormatExpression (const std::string &extended_format)
 Sets request extended format expression for custom logging.
void setResponseFormatExpression (const std::string &extended_format)
 Sets response extended format expression for custom logging.
void setTimestampFormat (const std::string &timestamp_format)
 Sets the timestamp format used for logging.

Static Public Member Functions

static isc::dhcp::LegalLogMgrPtr factory (const isc::db::DatabaseConnection::ParameterMap &parameters)
 Factory class method.
static std::string getYearMonthDay (const struct tm &time_info)
 Build the year-month-day string from a date.
Static Public Member Functions inherited from isc::dhcp::LegalLogMgr
static std::string genDurationString (const uint32_t secs)
 Translates seconds into a text string of days, hours, minutes and seconds.
static std::string getLogPath (bool reset=false, const std::string explicit_path="")
 Fetches the supported legal log file path.
static std::string getTimeString (const struct timespec &time, const std::string &format)
 Returns a time as string.
static void parseConfig (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
 Parse database specification.
static void parseDatabase (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
 Parse database specification.
static void parseExtraParameters (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
 Parse extra parameters which are not related to backend connection.
static void parseFile (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
 Parse file specification.
static void parseSyslog (const isc::data::ConstElementPtr &parameters, isc::db::DatabaseConnection::ParameterMap &map)
 Parse syslog specification.
static std::string validatePath (const std::string logpath)
 Validates a log path against the supported path for legal log files.
static std::string vectorDump (const std::vector< uint8_t > &bytes)
 Creates a string from a vector of printable bytes.
static std::string vectorHexDump (const std::vector< uint8_t > &bytes, const std::string &delimiter=":")
 Creates a string of hex digit pairs from a vector of bytes.

Protected Member Functions

virtual bool isOpen () const
 Returns true if the file is open.
virtual void openInternal (struct tm &time_info, bool use_existing)
 Open file using specified timestamp.
virtual void rotate ()
 Rotates the file if necessary.
void useExistingFiles (struct tm &time_info)
 Update file name with previously created file.

Detailed Description

RotatingFile implements an appending text file which rotates to a new file on a daily basis.

The physical file name(s) are determined as follows:

Forms the current file name from:

"<path>/<base_name>.<date>.txt"

where:

  • path - is the pathname supplied via the constructor. The path must exist and be writable by the process
  • base_name - an arbitrary text label supplied via the constructor
  • date - is the system date, at the time the file is opened, in local time. The format of the value is CCYYMMDD (century,year,month,day) or TXXXXXXXXXXXXXXXXXXXX (XXXXXXXXXXXXXXXXXXXX is the time in seconds since epoch)

Prior to each write, the system date is compared to the current file date to determine if rotation is necessary (i.e. day boundary has been crossed since the last write). If so, the current file is closed, and the new file is created.

Content is added to the file by passing the desired line text into the method, writeln(). This method prepends the content with the current date and time and appends an EOL.

The class implements virtual methods in facilitate unit testing and derives from LegalLogMgr abstract class.

Definition at line 50 of file rotating_file.h.

Member Enumeration Documentation

◆ TimeUnit

Time unit type used to rotate file.

Enumerator
Second 
Day 
Month 
Year 

Definition at line 54 of file rotating_file.h.

Constructor & Destructor Documentation

◆ RotatingFile()

isc::legal_log::RotatingFile::RotatingFile ( const isc::db::DatabaseConnection::ParameterMap & parameters)

Constructor.

Create a RotatingFile for the given file name without opening the file. The file will be rotated after a specific time interval has passed since the log file was created or opened. If the time unit used is day, month or year, the file will be rotated at the beginning of the respective 'count' number of days, months or years (when the write function call detects that the day, month or year has changed).

Note
The supported parameters are:
  • logfile parameters:
    • path
    • base-name
    • time-unit - one of: second, day, month, year
    • prerotate
    • postrotate
    • count
Parameters
parametersA data structure relating keywords and values concerned with the manager configuration.
Exceptions
LegalLogMgrErrorif given file name is empty.

Definition at line 35 of file rotating_file.cc.

References isc::dhcp::LegalLogMgr::LegalLogMgr(), apply(), and Day.

Referenced by factory().

Here is the call graph for this function:

◆ ~RotatingFile()

isc::legal_log::RotatingFile::~RotatingFile ( )
virtual

Destructor.

The destructor does call the close method.

Definition at line 126 of file rotating_file.cc.

References close().

Here is the call graph for this function:

Member Function Documentation

◆ apply()

void isc::legal_log::RotatingFile::apply ( const isc::db::DatabaseConnection::ParameterMap & parameters)

Parse file specification and create forensic log backend.

It supports the following parameters via the Hook Library Parameter mechanism:

path - Directory in which the legal file(s) will be written. The default value is "<prefix>/var/log/kea". The directory must exist.

base-name - An arbitrary value which is used in conjunction with current system date to form the current legal file name. It defaults to "kea-legal".

Legal file names will have the form:

<path>/<base-name>.<CCYYMMDD>.txt
<path>/<base-name>.<TXXXXXXXXXXXXXXXXXXXX>.txt

time-unit - The time unit used to rotate the log file. Valid values are: "second", "day", "month", or "year". It defaults to "day".

count - The number of time units that need to pass until the log file is rotated. It can be any positive number, or 0, which disables log rotation. It defaults to 1.

prerotate - An external executable or script called with the name of the file that will be closed. Kea does not wait for the process to finish.

postrotate - An external executable or script called with the name of the file that was opened. Kea does not wait for the process to finish.

Parameters
parametersThe library parameters.

Definition at line 41 of file rotating_file.cc.

References isc::asiolink::ProcessSpawn::ASYNC, Day, isc::dhcp::LegalLogMgr::getLogPath(), isc_throw, Month, Second, isc::hooks::HookLibraryScriptsChecker::validatePath(), isc::Exception::what(), and Year.

Referenced by RotatingFile().

Here is the call graph for this function:

◆ close()

void isc::legal_log::RotatingFile::close ( )
virtual

Closes the underlying file.

Method is exception safe.

Implements isc::dhcp::LegalLogMgr.

Definition at line 410 of file rotating_file.cc.

References isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_CLOSE_ERROR, LEGAL_LOG_STORE_CLOSED, LOG_ERROR, and LOG_INFO.

Referenced by ~RotatingFile(), and rotate().

◆ factory()

LegalLogMgrPtr isc::legal_log::RotatingFile::factory ( const isc::db::DatabaseConnection::ParameterMap & parameters)
static

Factory class method.

Parameters
parametersA data structure relating keywords and values concerned with the database.
Returns
The Rotating File Store Backend.

Definition at line 427 of file rotating_file.cc.

References RotatingFile(), isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_OPEN, LOG_INFO, and isc::db::DatabaseConnection::redactedAccessString().

Referenced by isc::legal_log::RotatingFileInit::RotatingFileInit(), and load().

Here is the call graph for this function:

◆ getBaseName()

std::string isc::legal_log::RotatingFile::getBaseName ( ) const
inline

Returns the file base name.

Returns
The file base name.

Definition at line 189 of file rotating_file.h.

◆ getFileName()

std::string isc::legal_log::RotatingFile::getFileName ( ) const
inline

Returns the current file name.

Returns
The file name.

Definition at line 182 of file rotating_file.h.

Referenced by rotate().

◆ getPath()

std::string isc::legal_log::RotatingFile::getPath ( ) const
inline

Returns the file path.

Returns
The file path.

Definition at line 196 of file rotating_file.h.

◆ getType()

virtual std::string isc::legal_log::RotatingFile::getType ( ) const
inlinevirtual

Return backend type.

Returns the type of the backend (e.g. "mysql", "logfile" etc.).

Returns
Type of the backend.

Implements isc::dhcp::LegalLogMgr.

Definition at line 175 of file rotating_file.h.

◆ getYearMonthDay()

string isc::legal_log::RotatingFile::getYearMonthDay ( const struct tm & time_info)
static

Build the year-month-day string from a date.

Parameters
time_infoThe time info to be converted to string.
Returns
the YYYYMMDD string.

Definition at line 131 of file rotating_file.cc.

Referenced by updateFileNameAndTimestamp().

◆ isOpen()

bool isc::legal_log::RotatingFile::isOpen ( ) const
protectedvirtual

Returns true if the file is open.

Returns
True if the physical file is open, false otherwise.

Definition at line 405 of file rotating_file.cc.

Referenced by open(), and rotate().

◆ open()

void isc::legal_log::RotatingFile::open ( )
virtual

Opens the current file for writing.

Forms the current file name if using seconds as time units:

"<path_>/<base_name_>.<TXXXXXXXXXXXXXXXXXXXX>.txt"

where XXXXXXXXXXXXXXXXXXXX is the time in seconds since epoch,

or if using days, months, years as time units:

"<path_>/<base_name_>.<CCYYMMDD>.txt"

where CCYYMMDD is the current date in local time,

and opens the file for appending. If the file does not exist it is created. If the file is already open, the method simply returns.

Exceptions
LegalLogMgrErrorif the file cannot be opened.

Implements isc::dhcp::LegalLogMgr.

Definition at line 278 of file rotating_file.cc.

References isc::dhcp::LegalLogMgr::currentTimeInfo(), isc::util::MultiThreadingMgr::instance(), isOpen(), and openInternal().

Here is the call graph for this function:

◆ openInternal()

void isc::legal_log::RotatingFile::openInternal ( struct tm & time_info,
bool use_existing )
protectedvirtual

Open file using specified timestamp.

Parameters
time_infoThe current time info used to open log rotate file.
use_existingFlag which indicates if the name should be updated with previously created file name if the file can still be used.

Definition at line 288 of file rotating_file.cc.

References isc_throw, isc::legal_log::legal_log_logger, LEGAL_LOG_STORE_OPENED, LOG_INFO, and updateFileNameAndTimestamp().

Referenced by open(), and rotate().

Here is the call graph for this function:

◆ rotate()

void isc::legal_log::RotatingFile::rotate ( )
protectedvirtual

Rotates the file if necessary.

The system date (no time component) is latter than the current file date (i.e. day boundary has been crossed), then the current physical file is closed and replaced with a newly created and open file.

Definition at line 306 of file rotating_file.cc.

References isc::asiolink::ProcessSpawn::ASYNC, close(), isc::dhcp::LegalLogMgr::currentTimeInfo(), Day, getFileName(), isOpen(), Month, openInternal(), Second, and Year.

Here is the call graph for this function:

◆ updateFileNameAndTimestamp()

void isc::legal_log::RotatingFile::updateFileNameAndTimestamp ( struct tm & time_info,
bool use_existing )

Function which updates the file name and internal timestamp from previously created file name (if it can still be used).

Parameters
time_infoThe current time info that should be used for the new name if previous files can not be reused.
use_existingFlag which indicates if the name should be updated with previously created file name if the file can still be used.

Definition at line 138 of file rotating_file.cc.

References getYearMonthDay(), Second, and useExistingFiles().

Referenced by openInternal().

Here is the call graph for this function:

◆ useExistingFiles()

void isc::legal_log::RotatingFile::useExistingFiles ( struct tm & time_info)
protected

Update file name with previously created file.

Parameters
time_infoThe current time info used to open log rotate file.

Definition at line 165 of file rotating_file.cc.

References Day, Month, Second, and Year.

Referenced by updateFileNameAndTimestamp().

◆ writeln()

void isc::legal_log::RotatingFile::writeln ( const std::string & text,
const std::string & addr )
virtual

Appends a string to the current file.

Invokes rotate() and then attempts to add the new line followed by EOL to the end of the file. The content of new line will be:

"<timestamp>SP<text><EOL>"

where:

  • timestamp - current local date and time as given by the strftime format "%Y-%m-%d %H:%M:%S %Z"
  • text - text supplied by the parameter
  • EOL - the character(s) generated std::endl
Parameters
addrAddress or prefix (ignored).
textString to append.
Exceptions
LegalLogMgrErrorif the write fails.

Implements isc::dhcp::LegalLogMgr.

Definition at line 374 of file rotating_file.cc.

References isc::util::MultiThreadingMgr::instance().

Here is the call graph for this function:

The documentation for this class was generated from the following files: