Installing Metasploit Framework on Mountain Lion and Mavericks

This Guide covers the installation of Metasploit Framework OSS Project on OSX Lion and Mountain Lion I recommend you first try with the following install script since it will do more than what is covered in the guide


This guide is written for new installs of OS X, if you have had several upgrades of the Operating System with XCode I recommend using the manual install and not the automated script.

This guide uses Homebrew as well as the script to provide the necessary packages to run Metasploit. If you have MacPorts this guide will not work and will cause problems. 


Make sure you run software update and install all updates for the operating system and install the latest version of Xcode so as to be able to compile software.

Installing Command Line Development Tools Xcode 4 on Mountain Lion

If you are running Xcode 4 you will need to go to Xcode Preference and choose the command line tools and download and install from the components


Installing Command Line Development Tools Xcode 5 on Mountain Lion

If you are running Xcode 5  you will need to go to Xcode Preference and choose the command line tools and download and install from the components


Installing Command Line Development Tools Xcode 5 on Mavericks

On OS X Mavericks the Command Line Developer Tools package can be installed on demand using "xcode-select --install” and the installed tools will be automatically updated using Software Update. Once you run the command the following dialog should appear and just click on Install




Download the latest Java SE 7 JDK from Oracle. This should set all the proper shortcuts for the Java binaries

Test that Java is properly installed by running 

java -version

It should return the version of Java you just installed.  To check tha the location is /usr/bin/java for the link run:

whereis java

If both commands runs and the location is correct Java is properly installed on the system.

Installation using Install Script

Download the script from GitHub and make it executable. Test with the -h option to make sure it is working properly

$ chmod +x 
$ ./ -h
Scritp for Installing Metasploit Framework
By Carlos_Perez[at]
Ver 0.1.0

-i:Install Metasploit Framework.
-p:password for MEtasploit databse msf user. If not provided a roandom one is generated for you.
-g:Install GNU GCC (Not necessary uless you wish to compile and install ruby 1.8.7 in OSX
-h:This help message

To start the installation you just run the script with the -i option and the installation will start. If you do not plan to be testing a mixed of third party gems and versions of Ruby against the framework I recommend you do not use RVM so as to keep the install simpler. DO NOT RUN the script as root. In the case of OSX it will:

  • Check that dependencies are meet.
  • Check if Homebrew is installed and of not it will install it.
  • Install Ruby 1.9.3
  • Install base ruby gems.
  • Install and configure Postgres for use with Metasploit
  • Install GCC if selected.
  • Download and install Metasploit Framework.
  • Installs all necessaries Ruby Gems using bundler.
  • Configure the database connection and sets the proper environment variables.
  • Download and install the latest version of Armitage.
  • Download and install the Pentest plugin and DNSRecon Import plugin.

Manual Installation

Install Homebrew

/usr/bin/ruby -e "$(curl -fsSkL"

We need to make sure that the binaries we install with homebrew are first in the path:

echo PATH=/usr/local/bin:/usr/local/sbin:$PATH >> ~/.bash_profile
source ~/.bash_profile
brew tap homebrew/versions

Install Nmap

For Nmap in the case of OSX I recommend the use of Homebrew since they are quite quick and keeping their formulas updated for the tool and work out most of the problems that may arise quite quickly. To install Nmap just run the command bellow:

brew install nmap

Install Ruby 1.9.3

We will use HomeBrew to install and maintain the most stable version of Ruby 1.9.x since it works best with Metasploit.

brew install homebrew/versions/ruby193

Check that yo are running the version of ruby you just installed with:

ruby -v

Install PostgreSQL

brew install postgresql --without-ossp-uuid

Configure PostgreSQL

Init the Database if this is a first time install:

initdb /usr/local/var/postgres

Configure Postgres to automatically load on login, the instruction bellow are as an example copy and paste the commands that the brew installer showed and follow any other instruction it shows :

mkdir -p ~/Library/LaunchAgents
cp /usr/local/Cellar/postgresql/9.1.4/homebrew.mxcl.postgresql.plist ~/Library/LaunchAgents/
launchctl load -w ~/Library/LaunchAgents/homebrew.mxcl.postgresql.plist

PostgreSQL will now start every time a user logs in. Create user called msf for use in Metasploit:

createuser msf -P -h localhost

Create database for use with metasploit called msf and make the user msf the owner:

createdb -O msf msf -h localhost

Record the password used for the account created since it will be used when configuring the framework.

Next we install the gems that we will need for running Metasploit:

gem install pg sqlite3 msgpack activerecord redcarpet rspec simplecov yard bundler


When working with VNC payloads the framework need vncviwer to be installed on the machine. Since Apple includes a VNC Client by default with OSX lets create a simple bash script that will call on the hos:ip combination that Metasploit uses with vncviwer so we do not have to fight with XQuatz and X11 to get one running on OSX:

echo '#!/usr/bin/env bash'>> /usr/local/bin/vncviewer 
echo open vnc://\$1 >> /usr/local/bin/vncviewer
chmod +x /usr/local/bin/vncviewer

This will allow us to call from the terminal a connection to a VNC Server like:


Installing Metasploit Framework

For regular use of the framework only needs to clone the Git repository and create the necessary links and set the variable for the database config file

cd /usr/local/share/

git clone

cd metasploit-framework

for MSF in $(ls msf*); do ln -s /usr/local/share/metasploit-framework/$MSF /usr/local/bin/$MSF;done

sudo chmod go+w /etc/profile

sudo echo export MSF_DATABASE_CONFIG=/usr/local/share/metasploit-framework/config/database.yml >> /etc/profile

From the Metasploit-Framework folder lets use the Bundler Gem to install the properly supportted Gem versions:

bundle install

Before starting to use the framework we need to create the database config file and set the parameters:

vim /usr/local/share/metasploit-framework/config/database.yml

Enter the following text in to the file keeping the spacing and using the values used for creating the user and database:

 adapter: postgresql
 database: msf
 username: msf
 port: 5432
 pool: 75
 timeout: 5

To load the variable for the database configuration file for the current user:

source /etc/profile
source ~/.bash_profile

Execute Metasploit msfconsole for the first time so it initializes the schema for the database for the first time as your current user and not as root:


Install Armitage

Since armitage is no longer included with Framework we need to execute some additional steps:

brew install pidof
curl -# -o /tmp/armitage.tgz
tar -xvzf /tmp/armitage.tgz -C /usr/local/share

 bash  -c "echo  \'/usr/bin/java\'  -jar /usr/local/share/armitage/armitage.jar \$\*" > /usr/local/share/armitage/armitage

perl -pi -e 's/armitage.jar/\/usr\/local\/share\/armitage\/armitage.jar/g' /usr/local/share/armitage/teamserver
Link Scripts

ln -s /usr/local/share/armitage/armitage /usr/local/bin/armitage

ln -s /usr/local/armitage/teamserver /usr/local/bin/teamserver

One important thing to take into consideration, for using Armitage and many of the modules provided in Metasploit you need to run them as root. Do to the way variables are handled when using the sudo command to invoke msfconsole or Armitage you need to give it the -E option:

# For launching Armitage
sudo -E armitage

# For launching msfconsole
sudo -E msfconsole