Skip to content
Philip Boulain edited this page Jan 7, 2016 · 8 revisions

This guide assumes you have three machines; one client, one server, and one which will run both the master and the UI. See infrastructure considerations for more.

Building from source for Debian-like systems

Plumage has some Debian packaging metadata which can make installing and updating it much easier. You can perform these steps on any modern Debian/Ubuntu system; not necessarily one of the ones you plan to run Plumage on. (If you're familiar with package maintenance, see the packaging readme.)

  • If you don't have one already, set up an sbuild environment for your target distribution.
    • For Ubuntu Trusty, add the universe repository to your build chroot, since some of the dependencies live there:
      • sudo schroot -c source:trusty-amd64-sbuild -u root
      • echo 'deb http://gb.archive.ubuntu.com/ubuntu/ trusty universe' >> /etc/apt/sources.list
      • echo 'deb-src http://gb.archive.ubuntu.com/ubuntu/ trusty universe' >> /etc/apt/sources.list
      • logout
  • Unpack a Plumage distribution tarball, or clone the git repository (preferably at a release tag).
  • Within the Plumage source, ln -s packaging/debian to set up for building as a Debian package
  • Run sbuild
  • Some scrolling text later, you should have a set of .deb files in the directory above. Copy the appropriate ones to each machine depending on its role(s).
  • Install the packages as normal with dpkg -i. Note that plumage-client-highperf is architecture-specific, although optional (see below).
  • Run sudo apt-get install -f if dpkg complains about unmet dependencies to install them and finish the job.
  • Edit /etc/default/plumage-{role} to taste. The defaults should be OK.
  • Edit /etc/plumage/*.json for your setup. You will likely want to adjust hostnames so they can find each-other, and the agent IPs (see below).
  • If you made changes to the above, run /etc/init.d/plumage-{role} force-reload for the appropriate roles.

plumage-client-highperf

The plumage-client-highperf package installs a setuid root binary that passes through to the Plumage Client subprocess for managing Polygraph itself after raising the limit on the number of open filehandles for the process. This is necessary for high-load Polygraph testing.

If you want to avoid setuid root binaries, you can not install this package, and edit /etc/plumage/client.json to set the path to plumage_run without the _suid suffix.

Agent IP address generation

Plumage needs to know which IP addresses to tell Polygraph to use. At the moment, this is a little too hardcoded to be a range of IPv4 addresses within a /24 subnet. Clients and Servers need to know a agent_prefix of the first three octets of the addresses, and a agent_octet_min and agent_octet_max that define the range of the last octet. Plumage will automatically distribute Polygraph processes across these addresses as needed to use the available processors in the host. (It is currently not possible to override this automatic detection, but Plumage is smart enough to not spawn more processes than there are addresses, so you can clamp it indirectly by reducing the address range.)

For a Debian or Ubuntu server, the easiest thing to do on your client and server boxes is edit the networking configuration, /etc/network/interfaces to create a range of alias addresses for testing:

auto em1 # the interface you are using
iface em1 inet static
    # The machine's "normal" address, for the web service to use
    address 10.80.2.1
    # usual netmask, network, broadcast, gateway, dns-* options
    # Make a a whole bunch of aliases
    # In this example setup, we are using .2 for a DNS server,
    # and would give Plumage a range of 64 from 3 to 66.
    post-up for octet in `seq 2 66`; do ip address add 10.80.2.$octet/24 dev em1; done

Setting host parameters

Your Polygraph configurations will need to know which addresses to bind to/send traffic to/from, and this is the role of [host parameters](Host parameters). While you could hard-code this for simple setups, it's a lot more flexible to have each Client/Server pair offer parameters to the configuration template.

Host parameters are set in client.json, as a host_parameters hash which is passed through as-is to the templating engine.

Security considerations

Plumage is designed for internal test networks, where access control is handled by firewalling, and those with it (the testing team of an organization) are trusted. Never expose Plumage to the wider Internet. This applies to all components of it, since they communicate via a web service API.

Plumage allows unfettered control of Polygraph, a (potentially) network-saturating traffic generator. While it runs as a restricted user, PGL allows shelling out to run commands. So by design Plumage offers remote code execution.

The SUID wrapper, on the other hand, is very restricted and small enough to be easily audited.

Next: Write and test a configuration

Non-Debian installation

You may be able to get Plumage running using the legacy installation method.