Nalar

Nalar ( aka. NGINX Access Log Analyzer for Rust ) is a Rust library designed for analyzing Nginx access logs. It's purpose is to simplify the process of setting up necessary log configuration in nginx.conf and provide user-friendly statistics on incoming traffic to your web server. Self-hosting is intended for user convenience.

!!! WARNING: THIS CRATE IS CURRENTLY IN DEVELOPMENT AND IS NOT YET READY FOR USE IN PRODUCTION. !!!

Table of Contents

• Capabilities
• Features
• Dependencies
• Installation
• Usage
  • Available Log Formats
• Documentation
• Testing
• License

Capabilities

• Log parsing: Detailed parsing of Nginx access logs.
• Traffic analysis: Nalar provides statistics on incoming traffic.
• Config modification: Automatically inserts necessary log conf data into nginx.conf.

Features

• default: Enables the utils feature set.
• utils: enables the utils module, as well as the errors module as it is a dependency.
• errors: enables the errors module.

Dependencies

• regex

Installation

To use Nalar in your project, add it to your Cargo.toml file:

[dependencies]
nalar = "x.x.x"

Usage

Here is a simple example demonstrating some of crates current functionality:

use nalar::utils::{
    access_log::AccessLog,
    regex_utils::get_captures
};


fn main() {
    let test_str: &str = r#"1001:111:c111:11a1:c11e:111a:c111:1f11 - - [04/Jun/2023:02:51:24 +0000] "GET /style.css HTTP/1.1" 304 0 "https://cocks.rs/" "Mozilla/5.0 (X11; Linux x86_64; rv:109.0) Gecko/20100101 Firefox/113.0""#;

    println!("EXAMPLE DEMONSTRATING SOME CURRENT FUNCTIONALITY\n\n");

    println!("test_str: {}\n\n", test_str);

    let log = AccessLog::default();

    println!("default log instantiated: {}\n\n", log);

    println!("{}\n\n", log.conf_get());

    let caps = match get_captures(log, test_str) {
        Ok(caps) => caps,
        Err(e) => {
            return eprintln!("{}", e);
        },
    };
    
    caps.name("remote_addr").map(|m| println!("remote_addr: {}", m.as_str()));
    caps.name("remote_user").map(|m| println!("remote_user: {}", m.as_str()));
    caps.name("time_local").map(|m| println!("time_local: {}", m.as_str()));
    caps.name("request").map(|m| println!("request: {}", m.as_str()));
    caps.name("status").map(|m| println!("status: {}", m.as_str()));
    caps.name("body_bytes_sent").map(|m| println!("body_bytes_sent: {}", m.as_str()));
    caps.name("http_referer").map(|m| println!("http_referer: {}", m.as_str()));
    caps.name("http_user_agent").map(|m| println!("http_user_agent: {}", m.as_str()));

    println!("\n\n");
}

Available Log Formats

nalar currently supports three distinct log formats for NGINX access logs:

1. Default:

   • This is the default log format used by NGINX (named combined in nginx by default) and nalar.
   • Format within nginx.conf:

     log_format default '$remote_addr - $remote_user [$time_local] '
                         '"$request" $status $body_bytes_sent '
                         '"$http_referer" "$http_user_agent"';
     

2. More:

   • A slightly more defined and verbose log format.
   • Format within nginx.conf:

     log_format more '"$time_local" client=$remote_addr '
         'method=$request_method request="$request" '
         'request_length=$request_length '
         'status=$status bytes_sent=$bytes_sent '
         'body_bytes_sent=$body_bytes_sent '
         'referer=$http_referer '
         'user_agent="$http_user_agent" '
         'request_time=$request_time ';
     

3. Detailed:

   • The most detailed log format that includes comprehensive information about the request.
   • Format within nginx.conf:

     log_format detailed 'site="$server_name" server="$host" dest_port="$server_port" dest_ip="$server_addr" '
         'src="$remote_addr" user="$remote_user" '
         'time_local="$time_local" protocol="$server_protocol" status="$status" '
         'bytes_out="$bytes_sent" bytes_in="$upstream_bytes_received" '
         'http_referer="$http_referer" http_user_agent="$http_user_agent" '
         'nginx_version="$nginx_version" '
         'uri_query="$query_string" uri_path="$uri" '
         'http_method="$request_method" response_time="$upstream_response_time" '
         'cookie="$http_cookie" request_time="$request_time" https="$https"';
     

You can configure nalar to use any of these log formats by calling the conf_entry() function on the LogFormat enum corresponding to the format you want to use.

For example:

let format = LogFormat::Detailed;
let conf_entry = format.conf_entry();

This would return the string that you need to add to your NGINX configuration file to set the log format to 'Detailed'.

The LogFormat enum also includes name() and variables() methods that return the name of the format and the variables used in the format respectively.

let format_name = format.name();  // Returns "detailed".
let variables_used = format.variables();  // Returns a string listing the variables used in the Detailed log format.

Documentation

Generate and view the documentation by running cargo doc --open.

Testing

Run the internal testing suite using cargo test.

Authors

• t-fbd / turn - Initial work and current development, testing, documentation

License

MIT License