NAME

NcFTPd::Log::Parse - parse NcFTPd xfer, session, and misc logs

SYNOPSIS

  use NcFTPd::Log::Parse;
  $parser = NcFTPd::Log::Parse->new(xfer => 'xfer.20100101'); # Parse a xfer log
  $parser = NcFTPd::Log::Parse::Xfer->new('xfer.20100101');   # Same as above

  while($line = $parser->next) {
    if($line->{operation} eq 'S') {
      print 'Upload';  
      $line->{pathname};
      $line->{size};
      # ... 
    }
  }

  # Check for an error, otherwise it was EOF
  if($parser->error) {
    die 'Parsing failed: ' . $parser->error;
  }

  $parser = NcFTPd::Log::Parse->new(xfer   => 'xfer.20100101', 
				    expand => 1,  	    
				    filter => sub { $_->{user} eq 'sshaw' });
  $line = $parser->next;
  $line->{operation}   # Expanded 'S' to 'store'
  $line->{notes}       # Expanded 'SfPs' to ['Used sendfile', 'PASV connection']

  # Load parser based on the log's name (using NcFTPd's default log names)
  $parser = NcFTPd::Log::Parse->new('xfer.20100101');  
  $parser = NcFTPd::Log::Parse->new('session.20100101'); 
  

DESCRIPTION

The NcFTPd::Log::Parse package is composed of 3 parsers:

NcFTPd::Log::Parse::Xfer

NcFTPd::Log::Parse::Misc

NcFTPd::Log::Parse::Session

A parser can be created via the factory class NcFTPd::Log::Parse:

$parser = NcFTPd::Log::Parse->new(xfer => 'ftp.log')

Or it can be created directly:

$parser = NcFTPd::Log::Parse::Xfer->new('ftp.log')

Options can be provided to both calls to new via a hash:

    $parser = NcFTPd::Log::Parse->new(xfer   => 'ftp.log', 
				      expand => 1, 
				      filter => sub { ... })

Lines are parsed on demand by calling the next method:

$entry = $parser->next

Each call to next returns a hash reference.

On error and EOF undef is returned. In order to discern between the two you must check the error method:

   if($parser->error) {
      # it wasn't EOF
   } 

METHODS

new

Create a parser capable of parsing the specified file. The file must be a path to a NcFTPd misc, session, or xfer file:

$parser = NcFTPd::Log::Parse->new($file, %options)
$parser = NcFTPd::Log::Parse->new(xfer => $file, %options)

Returns

A parser capable of parsing the specified file.

Arguments

$file

The file to parse can be given as a single argument:

$parser = NcFTPd::Log::Parse->new('session.log', %options)

Or as a part of the options hash, where the key is the log type and the value is the path to a log:

$parser = NcFTPd::Log::Parse->new(xfer => 'ftp.log', %options);    

When $file is given as a single argument an attempt is made to create the correct parser based on the filename's prefix. These prefixes are based on NcFTPd defaults.

%options

• xfer => $file

  Create a xfer log parser for the given file

• sess => $file

• session => $file

  Create a session log parser for the given file

• misc => $file

  Create a misc log parser for the given file

• filter => sub { ... }

  Only return entries that match the filter. By default all entries are returned.

  If the sub reference returns true the entry will be kept, otherwise it's skipped and the next line in the file is parsed. The current entry is provided to the sub as a hash reference (its parsed form) via the $_ variable:

      filter => sub { 
  	# Uploads by a_user
          $_->{user} eq 'a_user' &&
  	$_->{operation} eq 'S'
      }

• expand => 1|0

• expand => [ 'field1', 'field2', ... ]

  Expand all "expandable" entries, or just the "expandable" entries named in the array reference. Defaults to 0, no entries are expanded.

  A few types of log entries have cryptic fields. This option will expand these to something you can understand without having to refer to the NcFTPd docs. A value of 1 will expand all "expandable" fields, 0 will not expand any. You can also provide an ARRAY ref containing fields to expand.

  Check the parser specific documentation to see what's expanded.

Errors

If a parser cannot be created an error will be raised.

next

Parse and return the next entry in the log or, if a filter been provided, the next entry matching the filter.

Returns

On success a hash reference is returned. The keys are dependent upon the type of log being parsed, see the log specific parser documentation for details.

On error undef is returned. Call error retrieve the reason for the failure.

Arguments

None

error

Enquire why the last call to next failed.

Returns

A string containing the error or an empty string if there wasn't an error.

Arguments

None

SEE ALSO

NcFTPd::Log::Parse::Xfer, NcFTPd::Log::Parse::Session, NcFTPd::Log::Parse::Misc and the NcFTPd documentation http://ncftpd.com/ncftpd/doc/misc

AUTHOR

Skye Shaw <sshaw AT lucas.cis.temple.edu>

COPYRIGHT

Copyright (C) 2011 Skye Shaw

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm NcFTPd::Log::Parse

perl -MCPAN -e shell
install NcFTPd::Log::Parse