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


  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';  
      # ... 

  # 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'); 


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


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



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)


A parser capable of parsing the specified 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.


  • 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.


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


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


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.




Enquire why the last call to next failed.


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




NcFTPd::Log::Parse::Xfer, NcFTPd::Log::Parse::Session, NcFTPd::Log::Parse::Misc and the NcFTPd documentation


Skye Shaw <sshaw AT>


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.