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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
|
# Ruby API
The following objects exist in Oxidized.
## Input
* gets config from nodes
* must implement 'connect', 'get', 'cmd'
* 'ssh', 'telnet', 'ftp', and 'tftp' implemented
## Output
* stores config
* must implement 'store' (may implement 'fetch')
* 'git' and 'file' (store as flat ascii) implemented
## Source
* gets list of nodes to poll
* must implement 'load'
* source can have 'name', 'model', 'group', 'username', 'password', 'input', 'output', 'prompt' for each device.
* `name` - name of the device
* `model` - model to use ('ios', 'junos', etc).The model is loaded dynamically by the first node of that model type. (Also default in config file)
* `input` - method to acquire config, loaded dynamically as needed (Also default in config file)
* `output` - method to store config, loaded dynamically as needed (Also default in config file)
* `prompt` - prompt used for node (Also default in config file, can be specified in model too)
* 'sql', 'csv' and 'http' (supports any format with single entry per line, like router.db)
## Model
### At the top level
A model may use several methods at the top level in the class. `cfg` is
executed in input/output/source context. `cmd` is executed within an instance
of the model.
#### `cfg`
`cfg` may be called with a list of methods (`:ssh`, `:telnet`) and a block with
zero parameters. Calling `cfg` registers the given access methods and calling
it at least once is required for a model to work.
The block may contain commands to change some behaviour for the given methods
(e.g. calling `post_login` to disable the pager).
Supports [monkey patching](#monkey-patching).
#### `cmd`
Is used to specify commands that should be executed on a model in order to
gather its configuration. It can be called with:
* Just a string
* A string and a block
* `:all` and a block
* `:secret` and a block
The block takes a single parameter `cfg` containing the output of the command
being processed.
Calling `cmd` with just a string will emit the output of the command given in
that string as configuration.
Calling `cmd` with a string and a block will pass the output of the given
command to the block, then emit its return value (that must be a string) as
configuration.
Calling `cmd` with `:all` and a block will pass all command output through this
block before emitting it. This is useful if some cleanup is required of the
output of all commands.
Calling `cmd` with `:secret` and a block will pass all configuration to the
given block before emitting it to hide secrets if secret hiding is enabled. The
block should replace any secrets with `'<hidden>'` and return the resulting
string.
Execution order is `:all`, `:secret`, and lastly the command specific block, if
given.
Supports [monkey patching](#monkey-patching).
#### `comment`
Called with a single string containing the string to prepend for comments in
emitted configuration for this model.
If not specified the default of `'# '` will be used (note the trailing space).
#### `prompt`
Is called with a regular expression that is used to detect when command output
ends after a command has been executed.
If not specified, a default of `/^([\w.@-]+[#>]\s?)$/` is used.
#### `expect`
Called with a regular expression and a block. The block takes two parameters:
the regular expression, and the data containing the match.
The passed data is replaced by the return value of the block.
`expect` can be used to, for example, strip escape sequences from output before
it's further processed.
Supports [monkey patching](#monkey-patching).
### At the second level
The following methods are available:
#### `comment`
Used inside `cmd` invocations. Comments out every line in the passed string and
returns the result.
#### `password`
Used inside `cfg` invocations to specify the regular expression used to detect
the password prompt. If not specified, the default of `/^Password/` is used.
#### `post_login`
Used inside `cfg` invocations to specify commands to run once Oxidized has
logged in to the device. Takes one argument that is either a block (taking zero
parameters) or a string containing a command to execute.
This allows `post_login` to be used for any model-specific items prior to
running the regular commands. This could include disabling the output pager
or timestamp outputs that would cause constant differences.
Supports [monkey patching](#monkey-patching).
#### `pre_logout`
Used to specify commands to run before Oxidized closes the connection to the
device. Takes one argument that is either a block (taking zero parameters) or a
string containing a command to execute.
This allows `pre_logout` to be used to 'undo' any changes that may have been
needed via `post_login` (restore pager output, etc.)
Supports [monkey patching](#monkey-patching).
#### `send`
Usually used inside `expect` or blocks passed to `post_login`/`pre_logout`.
Takes a single parameter: a string to be sent to the device.
### Monkey patching
Several model blocks accept behavior-modifying arguments that make monkey
patching existing blocks easier. This is primarily useful when a user-supplied
model aims to override or extend existing behavior of a model included in Oxidized.
This functionality is supported by `cfg`, `cmd`, `pre_*`, `post_*`, and `expect`
blocks.
#### `clear: true`
Resets the existing block, allowing the user to completely override its contents.
#### `prepend: true`
Ensures that the contents of the block are prepended, rather than appended (the
default) to an existing block.
### `String` convenience methods
Since configuration processing tasks are occasionally similar across models,
Oxidized provides an extended [`String`](/lib/oxidized/string.rb) class with the
intention of providing convenience methods and eliminating code duplication.
#### `cut_tail`
Returns a multi-line string without the last line, or an empty string if only a
single line was present.
#### `cut_head`
Returns a multi-line string without the first line, or an empty string if only a
single line was present.
|
