Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/sshaw/ncftpd-log-parse

Parse NcFTPd xfer, session, and misc logs
https://github.com/sshaw/ncftpd-log-parse

ftp ftp-server logs ncftp parser perl

Last synced: about 1 month ago
JSON representation

Parse NcFTPd xfer, session, and misc logs

Awesome Lists containing this project

README 

        
=head1 NAME



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



=head1 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'); 

  

=head1 DESCRIPTION

 

The C package is composed of 3 parsers:



=over 2



=item L



=item L



=item L



=back



A parser can be created via the factory class C:



    $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 L<< C|/new >> via a hash:



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

				      expand => 1, 

				      filter => sub { ... })



Lines are parsed on demand by calling the L<< C|/next >> method:



    $entry = $parser->next



Each call to C returns a hash reference. 



On error and EOF C is returned. In order to discern between the two you must 

check the L<< C|/error >> method:



    if($parser->error) {

       # it wasn't EOF

    } 

 

=head1 METHODS



=head2 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)



=head3 Returns



A parser capable of parsing the specified file. 



=head3 Arguments



C<$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 C<$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.



C<%options>



=over 4



=item * C<< xfer => $file >>



Create a L for the given file



=item * C<< sess => $file >>



=item * C<< session => $file >> 



Create a L for the given file



=item * C<< misc => $file >> 



Create a L for the given file



=item * C<< 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 C<$_> variable:



    filter => sub { 

	# Uploads by a_user

        $_->{user} eq 'a_user' &&

	$_->{operation} eq 'S'

    }



=item * C<< expand => 1|0 >> 



=item * C<< expand => [ 'field1', 'field2', ... ] >> 



Expand all "expandable" entries, or just the "expandable" entries named in the array reference. 

Defaults to C<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 C<1> will expand all "expandable" fields, C<0> will not expand any.  

You can also provide an C ref containing fields to expand. 



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



=back



=head3 Errors



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



=head2 next



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



=head3 Returns



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

L for details. 



On error C is returned. Call L<< C|/error >> retrieve the reason for the failure.



=head3 Arguments



None



=head2 error

  

Enquire why the last call to  L<< C|/next >> failed. 



=head3 Returns



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



=head3 Arguments



None



=head1 SEE ALSO



L, L, L and 

the NcFTPd documentation L



=head1 AUTHOR



Skye Shaw 



=head1 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.