diff options
author | Holger Weiss <holger@zedat.fu-berlin.de> | 2014-01-13 22:31:20 (GMT) |
---|---|---|
committer | Holger Weiss <holger@zedat.fu-berlin.de> | 2014-01-13 22:31:20 (GMT) |
commit | 15ec07c19fa25cfb075f0e69c7f01c398b8f2622 (patch) | |
tree | 24bbaa7da71c76cf1ed040fe2b043dd8dd4ff671 /web/input/doc/state-retention.md | |
parent | 1b4b3825dac84f6e3e4e40351b047cc7a3a4d179 (diff) | |
download | site-15ec07c19fa25cfb075f0e69c7f01c398b8f2622.tar.gz |
Import "State Retention" page from old web site
Add Ton's "State Retention" RFC to the list of "Proposals" (even though
it has been implemented and documented¹ by now).
¹ https://www.nagios-plugins.org/doc/faq/private-c-api.html#state-information
Diffstat (limited to 'web/input/doc/state-retention.md')
-rw-r--r-- | web/input/doc/state-retention.md | 126 |
1 files changed, 126 insertions, 0 deletions
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 @@ | |||
1 | title: State Retention | ||
2 | parent: Documentation | ||
3 | --- | ||
4 | |||
5 | # State Retention Routines | ||
6 | |||
7 | _Ton Voon, June 16, 2010_ | ||
8 | |||
9 | The aim is to create a set of library routines that can be used for saving | ||
10 | state information between invocations of a plugin. This way, it is possible | ||
11 | to calculate the rate of change and provide threshold calculations on this, | ||
12 | rather than just the current state. | ||
13 | |||
14 | This is based on a patch submitted by Alain Williams, | ||
15 | Nagios::Plugin::Differences by Jose Luis Martinez and comments on the mailing | ||
16 | list (see [references](#references)). | ||
17 | |||
18 | Lots 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 | |||
35 | Example 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 | |||
62 | Returns a string to use as a `key_name`, based on an MD5 hash of `argv`, thus | ||
63 | hopefully a unique key per service/plugin invocation. Use the | ||
64 | [Extra-Opts][extra-opts] parse of `argv`, so that uniqueness in parameters are | ||
65 | reflected there. | ||
66 | |||
67 | ### np\_state\_init(plugin\_name, key\_name, data\_version) | ||
68 | |||
69 | Sets variables. Generates filename. Returns `np_state_key`. Die with | ||
70 | `UNKNOWN` if exception. | ||
71 | |||
72 | ### np\_state\_read(np\_state\_key) | ||
73 | |||
74 | Returns `np_state_data`. Will return `NULL` if no data is available (first | ||
75 | run). If key currently exists, read data. If state file format version is | ||
76 | not expected, return as if no data. Get state data version number and compare | ||
77 | to expected. If numerically lower, then return as no previous state. Die | ||
78 | with `UNKNOWN` if exceptional error. | ||
79 | |||
80 | ### np\_state\_write\_string(np\_state\_key, time, string) | ||
81 | |||
82 | If `time==NULL`, use current time. Create state file, with state file format | ||
83 | version, 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 | ||
85 | writing to same key at same time. | ||
86 | |||
87 | ### np\_state\_write\_binary(np\_state\_key, time, start, length) | ||
88 | |||
89 | Same as `np_state_write_string()`, but writes binary data. | ||
90 | |||
91 | ### np\_state\_data\_cleanup(np\_state\_data) | ||
92 | |||
93 | Cleanup. | ||
94 | |||
95 | ### np\_state\_key\_cleanup(np\_state\_key) | ||
96 | |||
97 | Cleanup. | ||
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: # %--> | ||