Skip to content

Configuring the Amplet2 Client

Jump to bottom
Brendon Jones edited this page Jul 24, 2017 · 8 revisions

Amplet2 Client Configuration File

The amplet2 client uses libconfuse to parse the configuration file. When run standalone it expects to find a configuration file in /etc/amplet2/clients/default.conf, while the init script will attempt to start a client for each .conf file in the /etc/amplet2/clients/ directory. The init script is shipped disabled by default so that configuration can take place before the daemon starts for the first time - make sure to enable it in /etc/default/amplet2-client (Debian Wheezy) or with systemctl enable amplet2-client.service (Debian Jessie) once configured appropriately. A specific configuration file can be given using the the -c or --config command line options when run standalone:

# amplet2 --config /etc/amplet2/clients/default.conf

A sample configuration file is shipped with the client and installed in /etc/amplet2/clients/client.example. There is also a short example configuration file at the end of this page.

Core Options

These options describe how the AMP client should behave. Most of them have sensible default values and are optional, though you will at a minimum need to configure the name/address of the collector.

ampname = <string>
loglevel = <string>
interface = <string>
ipv4 = <string>
ipv6 = <string>
packetdelay = <integer>
nameservers = <string>
ssl = <ssl subsection>
collector = <collector subsection>
control = <control subsection>
remotesched = <remote schedule subsection>

ampname

  • Type: string
  • Required: no, but strongly recommended

The ampname is reported as the source of the tests. It should generally be unique (unless you have a really good reason not to). If it is not set then it defaults to the fully qualified domain name (or just the hostname) of the machine. If SSL connections are being used then this name must match the Common Name in the certificate.

loglevel

  • Type: string
  • Required: no
  • Default: info
  • Possible values: emerg alert crit err warn notice info debug

Log level to control the number of messages logged. The given level is the minimum severity required to generate a log message. If not set then it defaults to info which will report errors and informational messages about what the client is doing.

interface

  • Type: string
  • Required: no

The name of the source interface that all tests should bind to when sending test data (e.g. eth0). If not set then tests will use whichever interface is appropriate based on the host operating system, routing tables, etc.

ipv4

  • Type: string
  • Required: no

Source IPv4 address that all tests should bind to when sending test data. If not set then tests will use whichever address is appropriate based on the interface they are using, operating system, routing tables, etc.

ipv6

  • Type: string
  • Required: no

Source IPv6 address that all tests should bind to when sending test data. If not set then tests will use whichever address is appropriate based on the interface they are using, operating system, routing tables, etc.

packetdelay

  • Type: integer
  • Required: no
  • Default: 100

Minimum gap (in microseconds) between sending probe packets for most tests. By default this is set to 100us which may be too short for some connections with slower upload speeds. For example, we are currently using 2000us for ADSL connected hosts. Some tests such as the throughput test will ignore this value.

nameservers

  • Type: string
  • Required: no

Override the default nameservers in /etc/resolv.conf and use these ones instead. A single address or a libconfuse list of addresses can be specified. If you give more than 3, only the first 3 valid addresses will be used.

ssl

  • Type: ssl subsection
  • Required: no

Locations of the various SSL files (certificates, keys etc) and how the client should proceed if it is missing configuration. See the ssl subsection for more information.

collector

Information about where and how results should be reported. See the collector subsection for more information.

control

  • Type: control subsection
  • Required: no

Information about how the control interface should be managed. See the control subsection for more information.

remotesched

Information about how the fetching of schedule information from a remote server should be managed. See the remote schedule subsection for more information.

SSL Options

(available since v0.8.0)

SSL settings used for reporting to the collector or communicating with other amplet2 clients to start remote test servers (e.g. throughput). cacert, cert and key don't need to be set (they will be automagically set) but the files are always required even if not doing SSL to the RabbitMQ server. Run an amppki server on the collector to have it act as a certificate authority and sign client certificates when the client first runs, unless you want to use your own CA and distribute certificates yourself.

ssl {
    waitforcert = <boolean>
    cacert = <string>
    cert = <string>
    key = <string>
}

waitforcert

  • Type: boolean
  • Required: no
  • Default: true

Should the AMP client wait to receive a signed certificate from the collector? If set to false and no certificate is available then the client will exit. Otherwise the public key will be sent to the collector and the client will wait for a signed certificate to be returned. See more information about the client SSL configuration.

cacert

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<collector>.pem

The path of the SSL CA certificate for the central collector. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

cert

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<ampname>/<collector>.cert

The path of the SSL certificate for the AMP client. If the certificate is not specified and one has not already been fetched then the client will ask the collector to sign one and send it back. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

key

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<ampname>/key.pem

The path of the SSL private key for the AMP client. If the key is not specified and one has not already been generated then it will be created. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

Collector Options

The collector is the RabbitMQ broker to which data is reported. To improve reliability data can be reported to an intermediate, local broker first which will then ensure the data is sent upstream as and when the collector is available. A diskless/lightweight client may want to forgoe this and report directly to the collector to save local resources. Using a local broker will cause the AMP client to automatically generate a RabbitMQ shovel to move data to the central collector.

collector {
    vialocal = <boolean>
    address = <string>
    vhost = <string>
    exchange = <string>
    routingkey = <string>
    port = <integer>
    ssl = <boolean>
    cacert = <string>
    cert = <string>
    key = <string>
    waitforcert = <boolean>
}

vialocal

  • Type: boolean
  • Required: no
  • Default: true if RabbitMQ can be found locally, otherwise false

Is there an intermediary RabbitMQ broker running on the local machine? If so then AMP will configure a shovel to send results to the central collector after they have been reported locally. This helps prevent lost data should the central collector become unavailable for any reason. If there is no local broker and the collector can't be reached then results will be discarded.

address

  • Type: string
  • Required: yes

The central collector to which data should be reported. Results will either be reported directly to this address, or sent to a local broker which will then send them on to this address.

vhost

  • Type: string
  • Required: no
  • Default: /

The virtual host on the central collector to which data should be reported. The default vhost / used here is the default vhost used by RabbitMQ.

exchange

  • Type: string
  • Required: no
  • Default: amp_exchange

The exchange on the central collector to which data should be reported. The combination of exchange and routing key can control which queue data is sent to.

routingkey

  • Type: string
  • Required: no
  • Default: test

The routing key used when reporting data to the central collector. The combination of exchange and routing key can control which queue data is sent to.

port

  • Type: integer
  • Required: no
  • Default: 5672

The port number used to connect to the RabbitMQ server. By default RabbitMQ uses TCP port 5672 for non-SSL connections and TCP port 5671 for SSL connections.

ssl

  • Type: boolean
  • Required: no
  • Default: false if port is 5672, otherwise true

Should results be reported to the central collector using an SSL connection?

cacert

(deprecated since v0.8.0)

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<collector>.pem

The path of the SSL CA certificate for the central collector. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

cert

(deprecated since v0.8.0)

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<ampname>/<collector>.cert

The path of the SSL certificate for the AMP client. If the certificate is not specified and one has not already been fetched then the client will ask the collector to sign one and send it back. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

key

(deprecated since v0.8.0)

  • Type: string
  • Required: no
  • Default: /etc/amplet2/keys/<ampname>/key.pem

The path of the SSL private key for the AMP client. If the key is not specified and one has not already been generated then it will be created. This is used both when reporting results using an SSL connection and for establishing control connections with other clients. See more information about the client SSL configuration.

waitforcert

(deprecated since v0.8.0)

  • Type: boolean
  • Required: no
  • Default: true

Should the AMP client wait to receive a signed certificate from the collector? If set to false and no certificate is available then the client will exit. Otherwise the public key will be sent to the collector and the client will wait for a signed certificate to be returned. See more information about the client SSL configuration.

Control Options

The control interface is used by other amplets to request test servers be started (i.e. throughput, udpstream), or to remotely run tests from a client. Anyone connecting to this port has to provide a valid SSL certificate.

control {
    enabled = <boolean>
    interface = <string>
    ipv4 = <string>
    ipv6 = <string>
    port = <integer>
    acl server = <acl subsection>
    acl test = <acl subsection>
}

enabled

  • Type: boolean
  • Required: no
  • Default: false

Should the control socket be enabled? If set to true then the AMP client will listen for control messages from other AMP clients or configuration tools. This must be enabled if the client wants to act as a server for cooperative AMP tests (i.e. throughput, udpstream).

interface

  • Type: string
  • Required: no

The name of the interface that the control socket should bind to when listening for control connections (e.g. eth0). If not set then it will fall back to the interface set in the core options, failing that then the control socket will not bind to a particular interface.

ipv4

  • Type: string
  • Required: no

Source IPv4 address that the control socket should bind to when listening for control connections. If not set then it will fall back to the IPv4 address set in the core options, failing that then the control socket will listen on all IPv4 addresses.

ipv6

  • Type: string
  • Required: no

Source IPv6 address that the control socket should bind to when listening for control connections. If not set then it will fall back to the IPv6 address set in the core options, failing that then the control socket will listen on all IPv6 addresses.

port

  • Type: integer
  • Required: no
  • Default: 8869

The TCP port number the control socket should listen on, and the port number used to connect to other AMP clients (to arrange servers for cooperative AMP tests).

ACL Options

The ACL options allow you to restrict which other amplet2 clients can connect to the control port. The Common Name in the SSL certificate is matched against the lists given for the appropriate permission. To start a test server requires matching the acl server block, running a test on behalf of a remote client requires matching the acl test block.

acl <server|test> {
    allow = <string>
    deny = <string>
}

allow

  • Type: string
  • Required: no
  • Default: {}

The allow string is a libconfuse lists that contains names of clients or domains that should be granted this permission. Any name that starts with a dot is treated as a domain name and matches all subdomains. More specific matches in the deny rule will overrule less specific matches here, with all matching every name. The default behaviour is to allow no names.

deny

  • Type: string
  • Required: no
  • Default: all

The deny string is a libconfuse lists that contains names of clients or domains that should be denied this permission. Any name that starts with a dot is treated as a domain name and matches all subdomains. More specific matches in the allow rule will overrule less specific matches here, with all matching every name. The default behaviour is to deny all names.

Remote Schedule Options

Schedule fetching allows the schedule file to be kept up to date with a remote source, without the need to use systems like puppet etc. If you use HTTPS then the server will be verified (using the built in CA bundle, or the specified cacert). If you specify client credentials then they will be sent to the server for possible verification too.

remotesched {
    fetch = <boolean>
    url = <string>
    identify = <boolean>
    frequency = <integer>
    cacert = <string>
    cert = <string>
    key = <string>
}

fetch

  • Type: boolean
  • Required: no
  • Default: false

Should a remote server be queried for schedule updates?

url

  • Type: string
  • Required: no

The URL that contains the up to date schedule file. If identify is true then this is the base URL that is modified with the client ampname.

identify

  • Type: boolean
  • Required: no
  • Default: true

Should the AMP client append its ampname to the URL when querying for a new schedule file? This can make it easier to have a standard configuration file for a group of machines, which only differ in ampname.

frequency

  • Type: integer
  • Required: no
  • Default: 3600

How frequently (in seconds) the client should poll for a new schedule file.

cacert

  • Type: string
  • Required: no

The path of the SSL CA certificate for the schedule website. Required if the client will be fetching the schedule using HTTPS and the certificate is not in the default bundle.

cert

  • Type: string
  • Required: no

The path of the SSL certificate for the AMP client to present to the schedule website to verify identity (assuming the server is set up to check this). If not specified then no certificate will be presented.

key

  • Type: string
  • Required: no

The path of the SSL private key for the AMP client to use when attempting to prove identity to the schedule website (assuming the server is set up to check this). If not specified then no certificate will be presented.

Example Configuration File

# Core options for a client called foo.example.org
ampname     = foo.example.org
packetdelay = 1000
interface   = eth0
nameservers = { 203.0.113.53, 203.0.113.54 }

# The client expects to generate its own key and for the collector to sign it,
# it will wait until the certificate is signed before continuing.    
ssl {
    waitforcert = true
}

# Collector is running on amp.example.org and expects SSL connections only.
# Data is first reported to a RabbitMQ broker running on the localhost before
# it is sent to the collector.
collector {
    vialocal    = true
    address     = amp.example.org
    exchange    = amp_exchange
    routingkey  = amp
    port        = 5671
    ssl         = true
}

# Control socket is enabled and listening on the default port
control {
    enabled     = true
    acl server {
        allow = all
        deny = {}
    }
}

# Remote schedule fetching is enabled and happens once an hour
remotesched {
    fetch       = true
    url         = http://amp.example.org/configs/
    identify    = true
    frequency   = 3600
}
Clone this wiki locally