Writing a Test Schedule

Amplet2 Test Scheduling

The schedule file is a YAML document with two main elements - the first of which contains lists of test targets (for easily testing to multiple destinations at once), the second being a list of the individual tests that should be run. Each test is described by a block with information about the frequency at which it should be performed, where it should test to, and what options should be set.

By default the client will load all files from the /etc/amplet2/schedules/ and /etc/amplet2/schedules/<ampname>/ directories that have a .sched suffix. This is helpful if there are multiple clients running on a single machine as schedules can be split into global and client specific tests.

The schedule directories are read on startup and will be re-read when the client receives a SIGUSR1 signal (a SIGHUP will also trigger this when running as a daemon) or when a new schedule is fetched from a remote server (if this option is enabled in the client configuration). When remote schedule fetching is enabled, sending the client a SIGUSR2 will also force an immediate fetch of the remote schedule file (and possible subsequent reload of the schedule).

A sample schedule file is shipped with the client and installed in /etc/amplet2/schedules/schedule.example. There are also some short example schedule snippets at the end of this page.

Schedule File Format

---
targets:
   <name>: &<alias> [<target1>, <target2>, ... <targetN>]

tests:
 - test: <string>
   target: <string>
   start: <integer>
   end: <integer>
   period: <string>
   frequency: <integer>
   args: <string>
...

targets

The targets section is used to create groups of test targets to make scheduling tests to the same set of destinations more efficient. These are YAML anchors and aliases. A group target is interchangeable with using an IP address or DNS name when specifying the target of a test. The name given to a target group is a human readable identifier (currently has no real meaning). The alias is the label used to reference this group when using it as a test target in the test definitions. If an alias is used as the target of a test then it will be expanded to be all the targets included in the list.

tests

The tests section contains all the individual test blocks that make up the schedule. Each block describes the test to be run, what the destinations are, and how frequently it should be run.

test

• Type: string
• Required: yes
• Possible values: dns http icmp tcpping throughput traceroute udpstream

The name of the test to run.

target

• Type: string
• Required: yes

The name/address of the destination to test to, the alias of a target group (use a * to deference it), or a list of any combination of these. If a name is given and it exists in the AMP nametable then the address in that file will be used, otherwise the name will be resolved using DNS. By default all the resolved addresses will be tested to (though some tests will only accept one address), unless there are qualifiers added, e.g.:

• www.example.org - test to all resolved addresses for the target
• www.example.org!1 - test to a single resolved address for the target
• www.example.org!v4 - test to all resolved IPv4 addresses for the target
• www.example.org!1!v4 - test to one resolved IPv4 addresses for the target
• www.example.org!v6 - test to all resolved IPv6 addresses for the target
• www.example.org!1!v6 - test to one resolved IPv6 addresses for the target

start

• Type: integer
• Required: no
• Default: 0

The time in seconds after the start of the repeat period that the first run of this test should be scheduled. Will default to 0 if not specified.

end

• Type: integer
• Required: no
• Default: the end of the repeat period

The time in seconds after the start of the repeat period that the test should stop being scheduled. Will default to the end of the period if not specified.

period

• Type: integer
• Required: no
• Default: day
• Possible values: hour day week

The period at which the schedule should be repeated. Start and end times are relative to this test period. A day starts at 00:00:00 UTC, a week starts at 00:00:00 Sunday UTC.

frequency

• Type: integer
• Required: no
• Default: variable based on period

The frequency in seconds at which the test should be repeated within the repeat period. A value of zero means to run the test only once within the period (don't repeat). If not specified it will default to 60 (every minute) for an hourly schedule, 600 (every 10 minutes) for a daily schedule and 3600 (every hour) for a weekly schedule.

args

• Type: string
• Required: no

Parameters to the test, exactly the same as if the test was being run standalone on the command line. If no parameters are given then the test will run with the default values, which (depending on what the particular test expects) may or may not be enough to properly run the test. See the documentation for the specific test for more information.

Schedule Examples

These target group definitions are used to help illustrate different points in the following YAML fragments:

# Declare a few target groups for use in the examples:
targets:
  dns: &dnsservers [ ns1.example.org, ns2.example.org, ns3.example.org ]
  baz: &baz [ foo.example.org, bar.example.org, 192.0.2.1, 2001:DB8::1 ]

Run an icmp test to amp-foo every 10 seconds, starting at midnight UTC:

# Run an icmp test to amp-foo every 10 seconds, starting at midnight UTC:
- test: icmp
  target: amp-foo
  frequency: 10

Run an icmp test to amp-foo and amp-bar every 10 minutes, starting at midnight UTC and using random packet sizes:

# Run an icmp test to amp-foo and amp-bar every 10 minutes, starting at
# midnight UTC and using random packet sizes:
- test: icmp
  target: [amp-foo, amp-bar]
  frequency: 10
  args: -r

Run a dns test to a target group called "dnsservers" every 10 minutes, starting at midnight UTC, querying for www.example.org IN AAAA:

# Run a dns test to a target group called "dnsservers" every 10 minutes,
# starting at midnight UTC, querying for www.example.org IN AAAA:
- test: dns
  target: *dnsservers
  frequency: 600
  args: -q www.example.org -c IN -t AAAA

Run a traceroute test to amp-foo every 15 minutes, starting at noon UTC and stopping 3 hours later:

# Run a traceroute test to amp-foo every 15 minutes, starting at noon UTC and
# stopping 3 hours later:
- test: traceroute
  target: amp-foo
  frequency: 900
  start: 43200
  end: 54000

Run a traceroute test to amp-foo and a target group called "baz" once a week at 00:00:00 Sunday UTC

# Run a traceroute test to amp-foo and a target group called "baz" once a week
# at 00:00:00 Sunday UTC
- test: traceroute
  target: [amp-foo, *baz]
  frequency: 0
  period: week

Putting together all the fragments above into a single YAML file, with document boundaries and section headings we get something like:

---
targets:
  dns: &dnsservers [ ns1.example.org, ns2.example.org, ns3.example.org ]
  baz: &baz [ foo.example.org, bar.example.org, 192.0.2.1, 2001:DB8::1 ]

tests:
- test: icmp
  target: amp-foo
  frequency: 10

- test: icmp
  target: [amp-foo, amp-bar]
  frequency: 10
  args: -r

- test: dns
  target: *dnsservers
  frequency: 600
  args: -q www.example.org -c IN -t AAAA

- test: traceroute
  target: amp-foo
  frequency: 900
  start: 43200
  end: 54000

- test: traceroute
  target: [amp-foo, *baz]
  frequency: 0
  period: week
...