summaryrefslogtreecommitdiff
path: root/README
blob: 630056cdd5dcef2aeff509c755a6e69db96d0117 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
Source:
    https://projects.bytemark.co.uk/projects/custodian

Github Mirror:
    https://github.com/BytemarkHosting/custodian


Copyright:
    Copyright (c) 2012-2015 Bytemark Computer Consulting Ltd

Bug Tracker:
    https://projects.bytemark.co.uk/projects/custodian/issues/new

Licence:
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.




About Custodian
---------------

Custodian is a simple, scalable, and reliable protocol-tester that allows
a number of services to be tested across a network.

The core design is based upon a work queue, which is manipulated by two
main tools:

  custodian-enqueue
    * A parser that reads a list of hosts and tests to apply.  These
      tests are broken down into individual jobs, serialized and stored
      in a central queue.

  custodian-dequeue
    * A tool that pulls jobs from the queue, executing them in turn, and
      raises/clears alerts based upon the result of the test.


Custodian uses class-factories to ensure that protocol tests, and notification
objects, are only loosely tied to the core.  This is done so that custodian
may be extended or adapted more easily to your environment.



Configuration
-------------

The software is configured by the main configuration file located at:

   /etc/custodian/custodian.cfg

This file contains the alerting mechanism to use, the IP:port of the queue
the two scripts mentioned above use, and similar static things.

Each of the available configuration options has a sensible default which
is documented in that same file.



Dependencies
------------

The software is written in Ruby and has successfully been deployed in
production under:

* Ruby 1.8
* Ruby 1.9.x
* Ruby 2.1.x

The software has not yet been tested upon JRuby, or similar.

Dependencies, beyond ruby, are limited to the following gems:

* For HTTP/HTTPS testing: curb
* For communication with the queue: redis



Formatting
----------

Our code is formatted and tested with [rubodoc](https://github.com/bbatsov/rubocop).

Code should not be committed to the repository which results in warnings
or errors from the current `.rubodoc` configuration file.



Documentation
-------------

The software is documented online at the project home-page:

    https://projects.bytemark.co.uk/projects/custodian/wiki

Beyond that each script has a manpage which is installed when the
package is installed - or which may be examined by invoking the
script with the "--manual" flag.