Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 37 ยท Getting Started

Installing Metasploit and Starting the Database

Install the Metasploit Framework on Kali, Linux or Windows, initialise its PostgreSQL database with msfdb, update safely, and check that everything works.

You can get Metasploit running in a few minutes: on a security distribution it is already installed, and on other systems an official installer exists. This lesson walks through the installation paths, the PostgreSQL database that stores your findings, and how to keep the framework up to date.

Run these steps in your isolated lab machine from the previous lesson. The commands are shown as read-only because the site cannot run a Linux machine; the Python stand-ins parse the same kind of output.

Installation options

  • Kali Linux and similar distributions. The metasploit-framework package is preinstalled. Update it with the distribution's package manager.
  • Official installers. Rapid7 publishes installers for Linux, macOS and Windows. On Linux a script adds a package repository, so updates arrive through the system's package manager.
  • Containers. Community and official container images exist if you prefer to keep the tool away from your host.
  • Source. The code is on GitHub; you can clone it and run it with Ruby and Bundler. This is useful for development but slower to maintain.

Whatever you pick, install from the official source and verify downloads (checksums or signed repositories) because a fake "Metasploit" installer is a classic way to deliver malware.

Terminal
# Kali / Debian-based example (read-only, run on your own lab VM)
sudo apt update
sudo apt install metasploit-framework

First start and the database

Metasploit stores hosts, services, credentials and notes in a PostgreSQL database. It works without one, but then searches are slow and nothing persists. The helper msfdb creates and manages the database.

Terminal
# Create and start the database
sudo msfdb init
# Check its state
sudo msfdb status

A healthy status looks like this (example output):

TEXT
โ— postgresql.service - PostgreSQL RDBMS
     Active: active (exited)
COMMAND   PID USER   TYPE ...
postgres  821 postgres ...
[+] Metasploit database connected on localhost:5432

Start the console with msfconsole. It prints a banner (randomly chosen) and a prompt. Inside it, db_status confirms the connection:

TEXT
msf6 > db_status
[*] Connected to msf. Connection type: postgresql.

If it says "No connection", run sudo msfdb reinit once, or start PostgreSQL manually and msfdb start.

The exact banner, version number and prompt differ between releases. Examples in this course show typical output, labelled as examples. Your numbers will be different.

What msfdb init does

flowchart TD
    I["msfdb init"] --> C["Create PostgreSQL role and database 'msf'"]
    C --> S["Write database.yml with the connection settings"]
    S --> M["Run migrations: create tables"]
    M --> R["msfconsole connects automatically"]

After init, the console reads the connection settings from a small YAML file in your home folder.

Updating

Update regularly: new modules and fixes arrive weekly. On Kali, update through the package manager. With the official installer, the repository added by the script is updated the same way. Do not use "random scripts from forums" to update.

Terminal
# Debian-based systems
sudo apt update && sudo apt upgrade metasploit-framework

After an update, msfconsole prints the number of modules in its banner; checking that number is a quick way to see that the update worked.

Reading the banner

The startup banner shows counts such as exploits, auxiliary modules, post modules, payloads and encoders. The stand-in below parses a sample banner line (invented numbers) and checks that totals look reasonable. Parsing console output like this is useful later when you automate checks.

Python Parse a banner line

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The numbers are made up. Real numbers change with every release.

Checking the database connection in code

Most Metasploit automation talks to the database or to its RPC interface. You do not need those yet. For now, practice interpreting a msfdb status result.

Python Is the database healthy?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Troubleshooting

  • Port already in use: another PostgreSQL is listening on 5432. Stop it or configure Metasploit's port with msfdb init --connection-string options.
  • Permission errors: run msfdb with the privileges the installer expects (usually sudo on Linux).
  • Slow start: the first run builds a module cache; later starts are faster.
  • Antivirus on Windows: security software may delete Metasploit files because they contain exploit code. Add an exclusion only on a dedicated lab machine.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Metasploit store in its PostgreSQL database?

    The database keeps data discovered during a test so modules can reuse it.
  2. 2. Which command creates and starts the database?

    msfdb init creates the role, database and configuration.
  3. 3. How do you check from inside msfconsole that the database is connected?

    db_status prints the connection state.
  4. 4. Why should you install Metasploit only from official sources?

    Security tools are attractive bait; always use official repositories and verify downloads.

Summary

  • Install from the official source or use a distribution that includes it.
  • msfdb init creates the PostgreSQL database; db_status checks it.
  • Update often; module counts in the banner help confirm updates.
  • Run it only in your isolated lab.

Next: msfconsole Basics