Armitage Documentation

How to start Armitage

Step 0. Make sure you're root or a system administrator user.

Step 1. Start Armitage

On Linux, type armitage in a terminal or navigate to the Armitage folder and type ./armitage

Step 2. Click Connect

Step 3. Click Yes

Step 4. Wait

Metasploit's RPC server will start in the background. It's not instant. You will see a connection refused message again and again. This is Armitage checking if the server is ready yet.

Troubleshooting Guide

Here's a quick guide to the errors you may see and what they mean:

1. authentication error

Metasploit's RPC server is running but you have provided the wrong username or password for it. Click Cancel and check your username and password again.

If you don't know the username and password, then find the msfrpcd (Linux) process that is running and kill it. Once msfrpcd is killed, you may start Armitage again and this problem will be gone.

2. connection refused - Armitage never connects!

It's possible that you don't have enough RAM. I've seen the Metasploit RPC daemon die on startup from lack of memory. Or, maybe you didn't click Yes when Armitage asked if you wanted it to start Metasploit's RPC daemon.

3. Couldn't launch MSF. Cannot run program "msfrpcd": error=2, No such file or directory

Either Metasploit is not installed or your environment is not setup correctly. You probably did not use the full setup Metasploit installer and that is why. Install Metasploit with the full setup installer.

4. Could not connect to database: Connection Refused

Your database is not running. Armitage and Metasploit require a Postgresql database to work.

For Kali Linux users--it's possible you need to start the Metasploit service to update the database. Try this:

  • service postgresql start
  • service metasploit start
  • service metasploit stop

5. I do not have permission to read: /opt/metasploit/config/database.yml Run me as root please

To connect to Metasploit's database, Armitage must be able to read the database.yml file created by Metasploit. This file is installed so that only root may read it. Start Armitage with root privileges.

If you connect Armitage to a *remote* Metasploit instance (with a deconfliction server setup), then Armitage will not require root privileges.

6. I can not find database.yml. I *really* need it.

To connect to the Metasploit Framework database, Armitage needs to know the location of the database.yml file. This is normally available in the MSF_DATABASE_CONFIG environment variable.

If you installed Metasploit by hand, make sure MSF_DATABASE_CONFIG is set. You may want to try sudo -E to launch Armitage. This form of sudo will have Armitage inherit the root user's environment--including the MSF_DATABASE_CONFIG variable.

Kali Linux users, if you're getting this error--try:

  • service postgresql start
  • service metasploit start
  • service metasploit stop

7. org.postgresql.util.PSQLException: FATAL: password authentication failed for user "msf"

I don't want to sound mean about this--but you setup the Metasploit Framework by hand and did something wrong. I can't help you troubleshoot this when Rapid7 publishes a working installer, DarkOperator has written a wonderful (working) install script, and Kali Linux comes with all the dependencies setup for you.

You're getting this error because Armitage is not able to authenticate to your postgres database with the information in your database.yml file. Does msfconsole connect to the database? That's awesome! But, it doesn't mean your environment is Armitage friendly.

Armitage has its own YAML parser. The Armitage YAML parser is a piece of garbage. If your YAML file is not parseable by Armitage--then you may get this error. If your YAML file has some sort of error or something perfectly valid, Armitage may misinterpret the password value.

I don't know what to tell you other than setup your environment with a working method. This is what I test my garbage parser on. If there's a problem with the supported environments, I'll address it.

8. Unexpected end of file from server

You're trying to connect to when a team server is running. If you have a team server running, connect to your external IP address. This is Armitage's cue that it should use the team server protocol (over SSL) and not the msfrpcd protocol (non-SSL).

9. Connection reset

You're trying to connect Armitage to a local SSL enabled msfrpcd. This won't work. You probably started msfrpcd on your own following the expert instructions of some shady blogger with a lot of ads on their site. Good job. Go ask them for help!

You should let Armitage start msfrpcd for you. If you prefer to start it yourself, then use:

msfrpcd -U msf -P test -f -S -a

This will start msfrpcd without SSL bound to suitable for you to connect to locally with Armitage.

What's Next?

Now that Armitage is running, I recommend exploring the rest of this site. You'll find videos, screencasts, and articles on the Media page. Reading the manual is a must as well. Check out the frequently asked questions page if you encounter a problem. If you don't find answers on this site, use the contact page to learn where to get help.