How to log in Metasploit

Usually, if something in Metasploit triggers an error, there is a backtrace or at least a brief message that explains what the problem is about. Most of the time, there is nothing wrong with that. But sometimes if you wish to report that problem, you might lose that information, which makes your bug report less informative, and the problem may take much longer to solve. This is why logging to file in many cases is extremely useful. In this documentation, we'll explain about how to take advantage of this properly.

Basic Usage

As an user, you should know that all the logged errors are saved in a file named framework.log. The save path is defined in Msf::Config.log_directory, which means in msfconsole, you can switch to irb and figure out where it is:

msf > irb
[*] Starting IRB shell...

>> Msf::Config.log_directory
=> "/Users/test/.msf4/logs"

By default, all the log errors are on level 0 - the least informative level. But of course, you can change this by setting the datastore option, like this:

msf > setg LogLevel 3
LogLevel => 3
msf >

Log Levels

There are 4 different logging levels defined in log/rex/logging.rb:

Log Level	Description
LEV_0 (Default)	The default log level if none is specified. It should be used when a log message should always be displayed when logging is enabled. Very few log messages should occur at this level aside from necessary information logging and error/warning logging. Debug logging at level zero is not advised.
LEV_1 (Extra)	This log level should be used when extra information may be needed to understand the cause of an error or warning message or to get debugging information that might give clues as to why something is happening. This log level should be used only when information may be useful to understanding the behavior of something at a basic level. This log level should not be used in an exhaustively verbose fashion.
LEV_2 (Verbose)	This log level should be used when verbose information may be needed to analyze the behavior of the framework. This should be the default log level for all detailed information not falling into LEV_0 or LEV_1. It is recommended that this log level be used by default if you are unsure.
LEV_3 (Insanity)	This log level should contain very verbose information about the behavior of the framework, such as detailed information about variable states at certain phases including, but not limited to, loop iterations, function calls, and so on. This log level will rarely be displayed, but when it is the information provided should make it easy to analyze any problem.

For debugging purposes, it's always better to turn on the highest level of logging.

Logging API

There are mainly five logging methods you will most likely be using a lot, and they all have the exact same arguments. Let's use one of the logging methods to explain what these arguments are about:

def elog(msg, src = 'core', level = 0, from = caller)

• msg - The message you want to log
• src - The source of the error (default is core, as in Metasploit core)
• level - The log level
• from - The current execution stack. caller is a method from Kernel.

Notice that only the msg argument is required, the rest are optional.

Now, let's go over these five methods and explain how they're meant to be used:

Method	Purpose
dlog()	LOG_DEBUG
elog()	LOG_ERROR
wlog()	LOG_WARN
ilog()	LOG_INFO
rlog()	LOG_RAW

Code Example

elog("The sky has fallen")