summaryrefslogtreecommitdiffstats
path: root/web/input/doc
diff options
context:
space:
mode:
Diffstat (limited to 'web/input/doc')
-rw-r--r--web/input/doc/index.md10
-rw-r--r--web/input/doc/state-retention.md126
2 files changed, 134 insertions, 2 deletions
diff --git a/web/input/doc/index.md b/web/input/doc/index.md
index f273e73..6604594 100644
--- a/web/input/doc/index.md
+++ b/web/input/doc/index.md
@@ -40,13 +40,19 @@ The following ideas are not yet implemented (and might never be):
40* **[Check Aggregation: check\_many][check-many]** 40* **[Check Aggregation: check\_many][check-many]**
41 A plugin wrapper allowing aggregation and serialization of multiple checks. 41 A plugin wrapper allowing aggregation and serialization of multiple checks.
42 42
43* **[State Retention Routines][retention-rfc]**
44 Saving state information between plugin invocations. This is actually
45 [implemented][retention-api] by now.
46
43[man]: doc/man/index.html "Manual Pages" 47[man]: doc/man/index.html "Manual Pages"
44[faq]: doc/faq/index.html "Frequently Asked Questions" 48[faq]: doc/faq/index.html "Frequently Asked Questions"
45[extra-opts]: doc/extra-opts.html "Extra-Opts" 49[extra-opts]: doc/extra-opts.html "Extra-Opts"
46[video]: doc/presentation.html "Nagios::Plugin Presentation" 50[video]: doc/presentation.html "Nagios::Plugin Presentation"
47[module]: http://search.cpan.org/dist/Nagios-Plugin/ "Nagios::Plugin" 51[module]: http://search.cpan.org/dist/Nagios-Plugin/ "Nagios::Plugin"
48[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines" 52[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
49[new-threshold]: doc/new-threshold-syntax.html "New Threshold Syntax" 53[new-threshold]: doc/new-threshold-syntax.html "Proposal for New Threshold Syntax"
50[check-many]: doc/check-many.html "Check Aggregation Plugin" 54[check-many]: doc/check-many.html "Proposal for Check Aggregation Plugin"
55[retention-rfc]: doc/state-retention.html "Proposal for State Retention Routines"
56[retention-api]: doc/faq/private-c-api.html#state-information "State Retention API"
51 57
52<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %--> 58<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->
diff --git a/web/input/doc/state-retention.md b/web/input/doc/state-retention.md
new file mode 100644
index 0000000..174abd1
--- /dev/null
+++ b/web/input/doc/state-retention.md
@@ -0,0 +1,126 @@
1title: State Retention
2parent: Documentation
3---
4
5# State Retention Routines
6
7_Ton Voon, June 16, 2010_
8
9The aim is to create a set of library routines that can be used for saving
10state information between invocations of a plugin. This way, it is possible
11to calculate the rate of change and provide threshold calculations on this,
12rather than just the current state.
13
14This is based on a patch submitted by Alain Williams,
15Nagios::Plugin::Differences by Jose Luis Martinez and comments on the mailing
16list (see [references](#references)).
17
18Lots of discussion between Holger and I ended up with this.
19
20## Terms
21
22**Location**
23: Use `./configure` `--sharedstatedir` to define, default `$PREFIX/var`.
24 Override with `NAGIOS_PLUGIN_STATE_DIRECTORY` envvar at runtime if set.
25 Add plugin name to end.
26
27**Key**
28: Is used as the filename of the store. Default to `state.dat`. Recommend
29 that this is set to the string returned by `np_state_generate_key()`, to
30 be unique per plugin call. Key can only consist of alphanumerics and
31 underscore.
32
33## Format
34
35Example format:
36
37 # NP state file
38 1 [file format version]
39 {data version}
40 {time}
41 {data}
42
43## Structs
44
45### np\_state\_key
46
47 char *name
48 char *plugin_name
49 int data_version
50 char *_filename
51
52### np\_state\_data
53
54 time_t time
55 void *data
56 int length (of binary data)
57
58## Calls
59
60### np\_state\_generate\_key(argv)
61
62Returns a string to use as a `key_name`, based on an MD5 hash of `argv`, thus
63hopefully a unique key per service/plugin invocation. Use the
64[Extra-Opts][extra-opts] parse of `argv`, so that uniqueness in parameters are
65reflected there.
66
67### np\_state\_init(plugin\_name, key\_name, data\_version)
68
69Sets variables. Generates filename. Returns `np_state_key`. Die with
70`UNKNOWN` if exception.
71
72### np\_state\_read(np\_state\_key)
73
74Returns `np_state_data`. Will return `NULL` if no data is available (first
75run). If key currently exists, read data. If state file format version is
76not expected, return as if no data. Get state data version number and compare
77to expected. If numerically lower, then return as no previous state. Die
78with `UNKNOWN` if exceptional error.
79
80### np\_state\_write\_string(np\_state\_key, time, string)
81
82If `time==NULL`, use current time. Create state file, with state file format
83version, default text. Write version, time, and data. Avoid locking problems
84- use `mv` to write and then swap. Possible loss of state data if two things
85writing to same key at same time.
86
87### np\_state\_write\_binary(np\_state\_key, time, start, length)
88
89Same as `np_state_write_string()`, but writes binary data.
90
91### np\_state\_data\_cleanup(np\_state\_data)
92
93Cleanup.
94
95### np\_state\_key\_cleanup(np\_state\_key)
96
97Cleanup.
98
99## Notes
100
101- All opens and close within these functions, retaining atomicity.
102- Libtap tests for library.
103- Update [Development Guidelines][guidelines] with library usage.
104- This has problems if a remote host is checked from different Nagios
105 instances.
106- Binary data may not restore on a program compiled with different options
107 from the program that saved it; e.g., 32 or 64 bit.
108- Binary data may include a structure containing a pointer. Pointer values
109 may not be used in the reading program - i.e., you need to overwrite the
110 value with something `malloc()`ed in the current run of the program.
111- State files could be left lying around. We recommend you run a regular job
112 to remove unmodified state files older than 1 week.
113
114## References
115
116- <https://www.nagios-plugins.org/archive/devel/2009-September/007767.html>
117 for the initial patch.
118- <https://www.nagios-plugins.org/archive/devel/2009-September/thread.html#7773>
119 for a conversation about the patch.
120- <https://www.nagios-plugins.org/archive/devel/2009-September/007749.html>
121 for Nagios::Plugin::Differences.
122
123[extra-opts]: doc/extra-opts.html "Extra-Opts"
124[guidelines]: doc/guidelines.html "Nagios Plugin Development Guidelines"
125
126<!--% # vim:set filetype=markdown textwidth=78 joinspaces: # %-->