Beeswithmachineguns

h4. Bees with Machine Guns!

A utility for arming (creating) many bees (micro EC2 instances) to attack (load test) targets (web applications).

Also, retribution for "this shameful act":http://kottke.org/10/10/tiny-catapult-for-throwing-pies-at-bees against a proud hive.

h2. Dependencies

• Python 2.6 - 3.6
• boto
• paramiko

h2. Installation for users

<pre> pip install https://github.com/newsapps/beeswithmachineguns/archive/master.zip </pre>

h2. Installation for developers (w/ virtualenv + virtualenvwrapper)

<pre> git clone git://github.com/newsapps/beeswithmachineguns.git cd beeswithmachineguns mkvirtualenv --no-site-packages beesenv easy_install pip pip install -r requirements.txt </pre>

h2. Configuring AWS credentials

Bees uses boto to communicate with EC2 and thus supports all the same methods of storing credentials that it does. These include declaring environment variables, machine-global configuration files, and per-user configuration files. You can read more about these options on "boto's configuration page":http://code.google.com/p/boto/wiki/BotoConfig.

At minimum, create a .boto file in your home directory with the following contents:

<pre> [Credentials] aws_access_key_id = <your access key> aws_secret_access_key = <your secret key> </pre>

The credentials used must have sufficient access to EC2.

Make sure the .boto file is only accessible by the current account:

<pre> chmod 600 .boto </pre>

h2. Usage

A typical bees session looks something like this:

<pre> bees up -s 4 -g public -k frakkingtoasters bees attack -n 10000 -c 250 -u http://www.ournewwebbyhotness.com/ bees down </pre>

A bees session where this is being called from a python file, while specifying content type and a payload file. This is a working example, all of these objects exist in the us-east-1 region.

<pre> import bees import json sOptions = '{"post_file":"data.json","contenttype":"application/json"}' options = json.loads(sOptions) bees.up(1,'bees-sg','us-east-1b','ami-5d155d37','m3.medium','ubuntu','commerce-bees','subnet-b12880e8') bees.attack('<URL TO TEST>',2,2,**options) bees.down() </pre>

In this case the data.json is a simple json file, mind the path.

This spins up 4 servers in security group 'public' using the EC2 keypair 'frakkingtoasters', whose private key is expected to reside at ~/.ssh/frakkingtoasters.pem.

Note: the default EC2 security group is called 'default' and by default it locks out SSH access. I recommend creating a 'public' security group for use with the bees and explicitly opening port 22 on that group.

It then uses those 4 servers to send 10,000 requests, 250 at a time, to attack OurNewWebbyHotness.com.

Lastly, it spins down the 4 servers. Please remember to do this--we aren't responsible for your EC2 bills.

If you wanted 3 agents requesting url A and one requesting url B, your attack would look as follows (empty url -> use previous):

<pre> bees attack -n 10000 -c 250 -u 'http://url.a,,,http://url.b' </pre>

For complete options type:

<pre> bees -h </pre>

h2. Introduction to additions:

h4. Additions contributed Hurl integration and multi regional testing.

hurl is an http server load tester similar to ab/siege/weighttp/wrk with support for multithreading, parallelism, ssl, url ranges, and an api-server for querying the running performance statistics. hurl is primarily useful for benchmarking http server applications. For more information about hurl please visit https://github.com/VerizonDigital/hlx

Multi regional testing was added so user can call up multiple bees from different regions simultaneously. Users have the ability to “up”, “attack”, and “down” instances from single command. “regions.json” file is supplied which contains public ami images with hurl pre installed for all regions.

What kind of changes were made that's different from the old? Instead of writing bees information into a single ~/.bees file, each zone recognized in arguments creates a new unique bees file. Bees.py was modified to read these files. Up, attack, and down functions are run with threads.

example .bees files in user home directory

<pre> $ ls ~/.bees* | xargs -0 basename .bees.ap-southeast-1b .bees.eu-west-1b .bees.us-west-2b </pre>

h4. Motivation

Having the ability to generate a lot of HTTPS requests from many different regions around the world allows us to better test our platforms and services. This is also real helpful when there are tools that need to be tested for such things as location of requests.

h4. Hurl Usage

h4. bees up

Command line arguments are still the same however to add multiple zones with multiple amis, the values must be comma delimited. The ami and zones must also be in same order for it to work. So for example “-i ami-zone1,ami-zone2,ami-zone3 -z zone1,zone2,zone3”.

<pre> ./bees up -s 2 -k bees -g bees2 -l ubuntu -i ami-9342c0e0,ami-fd489d 9e,ami-e8c93e88 -z eu-west-1b,ap-southeast-1b,us-west-2b </pre>

h4. bees attack

In order to use the hurl platform, --hurl or -j must be supplied. Attacks will run concurrently and return a summarized output. The output is summarized per region. More information can be seen if user supplies the -o, --long_output options.

<pre> ./bees attack --hurl -u $testurl -S20 -M1000 -H "Accept : text/html" </pre>

h4. bees down

Bringing down bees is the same and will bring down all bees for all regions

<pre> ./bees down </pre>

regions used: eu-west-1b,ap-southeast-1b,us-west-2b

Some options were added to work with hurl

h4. Examples

<pre> $ ./bees --help Usage: bees COMMAND [options] Bees with Machine Guns A utility for arming (creating) many bees (small EC2 instances) to attack (load test) targets (web applications). commands: up Start a batch of load testing servers. attack Begin the attack on a specific url. down Shutdown and deactivate the load testing servers. report Report the status of the load testing servers. Options: -h, --help show this help message and exit up: In order to spin up new servers you will need to specify at least the -k command, which is the name of the EC2 keypair to use for creating and connecting to the new servers. The bees will expect to find a .pem file with this name in ~/.ssh/. Alternatively, bees can use SSH Agent for the key. -k KEY, --key=KEY The ssh key pair name to use to connect to the new servers. -s SERVERS, --servers=SERVERS The number of servers to start (default: 5). -g GROUP, --group=GROUP The security group(s) to run the instances under (default: default). -z ZONE, --zone=ZONE The availability zone to start the instances in (default: us-east-1d). -i INSTANCE, --instance=INSTANCE The instance-id to use for each server from (default: ami-ff17fb96). -t TYPE, --type=TYPE The instance-type to use for each server (default: t1.micro). -l LOGIN, --login=LOGIN The ssh username name to use to connect to the new servers (default: newsapps). -v SUBNET, --subnet=SUBNET The vpc subnet id in which the instances should be launched. (default: None). -b BID, --bid=BID The maximum bid price per spot instance (default: None). attack: Beginning an attack requires only that you specify the -u option with the URL you wish to target. -u URL, --url=URL URL of the target to attack. -K KEEP_ALIVE, --keepalive=KEEP_ALIVE Keep-Alive connection. -p POST_FILE, --post-file=POST_FILE The POST file to deliver with the bee's payload. -m MIME_TYPE, --mime-type=MIME_TYPE The MIME type to send with the request. -n NUMBER, --number=NUMBER The number of total connections to make to the target (default: 1000). -C COOKIES, --cookies=COOKIES Cookies to send during http requests. The cookies should be passed using standard cookie formatting, separated by semi-colons and assigned with equals signs. -Z CIPHERS, --ciphers=CIPHERS Openssl SSL/TLS cipher name(s) to use for negotiation. Passed directly to ab's -Z option. ab-only. -c CONCURRENT, --concurrent=CONCURRENT The number of concurrent connections to make to the target (default: 100). -H HEADERS, --headers=HEADERS HTTP headers to send to the target to attack. Multiple headers should be separated by semi-colons, e.g header1:value1;header2:value2 -e FILENAME, --csv=FILENAME Store the distribution of results in a csv file for all completed bees (default: ''). -P CONTENTTYPE, --contenttype=CONTENTTYPE ContentType header to send to the target of the attack. -S SECONDS, --seconds=SECONDS hurl only: The number of total seconds to attack the target (default: 60). -X VERB, --verb=VERB hurl only: Request command -HTTP verb to use -GET/PUT/etc. Default GET -M RATE, --rate=RATE hurl only: Max Request Rate. -a THREADS, --threads=THREADS hurl only: Number of parallel threads. Default: 1 -f FETCHES, --fetches=FETCHES hurl only: Num fetches per instance. -d TIMEOUT, --timeout=TIMEOUT