-
Notifications
You must be signed in to change notification settings - Fork 0
Installing
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.
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
- For Ubuntu Trusty, add the
- 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 thatplumage-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.
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.
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
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.
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.
You may be able to get Plumage running using the legacy installation method.
Plumage wiki content is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.