KillerBees is a stress test tool for web projects. It is ideal to test products or features before their release. It uses Amazon's computing cloud to simulate high concurrency by running parallel requests from many machines. The product/feature has to be accessible publicly.
Using this application in distributed mode may result in a large bill in your Amazon EC2 account. Be aware that this application is intended to run in several machines, and you will be billed for it. Make sure the machines are terminated after your test to prevent unnecessary billing. Use this application only against your own product, don't do evil :)
KillerBees runs in Amazon's cloud so you need an AWS account to use it. We provide you with a non-working AMI name (OS image) that you will need to replace with one of your own.
KillerBees will automatically launch the number of Amazon instances you specify and distribute itself to them. To do this, you'll need to have a public-private key pair. To get this, login to the AWS Console go to the EC2 Dashboard and select Key Pairs from the menu on the left. Click Create Key Pair and give your new key pair a name. Your private key will be downloaded. Save it to the machine you'll use to control KillerBees (Linux only), for example to /home/your_user/test.pem.
For KillerBees to work you'll need to have the public key too, which you don't get from Amazon. However, you can extract it from the private key:
$ ssh-keygen -y -f /home/your_user/test.pem > /home/your_user/test.pem.pub
You'll also need to know your AWS access key and secret key. You can get these from the AWS console by clicking your account name in the top right corner, selecting Security Credentials then going to the Access Keys section.
With that you are ready to install KillerBees.
Note that by default you are limited to 20 EC2 instances. If you need more juice than this (test it first, 20 is more than you think!), you can request more.
To install KillerBees you need Composer. If you don't have it yet, you can get it easily:
$ curl -sS https://getcomposer.org/installer | php
...then download and install KillerBees:
$ git clone [REPO_URL]
$ cd killerbees/
$ ../composer.phar install
Once Composer installs the dependencies, you can start configuring it.
$ php bin/killerbees configure:amazon
Follow the instructions on the screen.
-
amazon_ami: We recommend using the default AMI that we published, it works the best with KillerBees.
-
amazon_instance_type: Micro instances (default) are just fine for this job and they are easy on your wallet.
-
amazon_security_group: This sets the security group (firewall settings) for your EC2 instance. If you leave it empty, default security group will be sued which is just fine for our purposes as it allows SSH (port 22).
-
amazon_key_name: Name of the key pair you generated for EC2. In our example in Prerequisites it's
test. This key will be used to log into the created instances and run the attack. -
amazon_private_key_filepath: Full path to the private key you generated for EC2. In our example in Prerequisites it's
/home/your_user/test.pem. -
amazon_public_key_filepath: Full path to the public key you generated for EC2. In our example in Prerequisites it's
/home/your_user/test.pem.pub. -
amazon_user: It's the default user with SSH access to the machine. If you used our AMI, it's 'ec2-user'.
-
amazon_credentials.key: Your Amazon AWS credentials key, see Prerequisites. Used to launch instances.
-
amazon_credentials.secret: Your Amazon AWS secret key, see Prerequisites. Used to launch instances.
You need to create a file with the URLs to attack. The file format is YAML.
Here is a minimalistic example of the config:
bootstrap_requests:
requests:
- method: GET
url: http://www.example.com
This config will make KillerBees attack a single URL (using GET method) with no bootstrapping. Create this file and save it somewhere, for example under /home/your_user/attack1.yml.
Once the application has been properly installed, configured, and the set of URLs have been defined (see documentation above) then you will be able to inflict a wound to the selected target. There are two ways of running the application:
Use the following command to attack from a single machine, use this for the first test:
$ php bin/killerbees attack:local
The target URLs will receive the impacts from current machine only.
In order to attack from several machines then you need to start the number of instances you want and run the attack:distributed command.
Fire up the EC2 machines:
$ php bin/killerbees ec2:run --instances 10
And run the test from all machines:
$ php bin/killerbees attack:distributed
At this point the application will package itself and will be distributed and run as attack:local in every single machine. When you have finished your tests, terminate the machines:
$ php bin/killerbees ec2:terminate
Don't forget to terminate the instances once your test is done, otherwise receiving your monthly AWS bill will be a disturbing experience. Ensure in your AWS panel that everything is shut down.
All supported commands will be shown when executing the application with no parameters:
$ php bin/killerbees
KillerBees version Beta
Usage:
[options] command [arguments]
Options:
--help -h Display this help message.
--quiet -q Do not output any message.
--verbose -v|vv|vvv Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
--version -V Display this application version.
--ansi Force ANSI output.
--no-ansi Disable ANSI output.
--no-interaction -n Do not ask any interactive question.
Available commands:
help Displays help for a command
list Lists commands
attack
attack:distributed Launch an attack distributed on multiple amazon ec2 instances matching the given AMI
attack:local Launch an attack locally
configure
configure:amazon Configure KillerBees amazon parameters
ec2
ec2:run Run Ec2 Instances
ec2:terminate Terminate Ec2 Instances created with the given AMI
generate
generate:url Generate basic url config skeleton