From 87600b1f5f12711afe29c408e02dbbd927e3f25d Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Mon, 12 Mar 2018 00:19:20 +0100 Subject: Lint and standardize markdown documentation --- docs/Ruby-API.md | 46 +++++++++++++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 15 deletions(-) (limited to 'docs/Ruby-API.md') diff --git a/docs/Ruby-API.md b/docs/Ruby-API.md index 2dbc10e..8621870 100644 --- a/docs/Ruby-API.md +++ b/docs/Ruby-API.md @@ -3,33 +3,39 @@ The following objects exist in Oxidized. ## Input - * gets config from nodes - * must implement 'connect', 'get', 'cmd' - * 'ssh', 'telnet, ftp, and tftp' implemented + +* 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 + +* 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' - * name - name of the devices - * model - model to use ios/junos/xyz, model is loaded dynamically when needed (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) + +* gets list of nodes to poll +* must implement 'load' +* source can have 'name', 'model', 'group', 'username', 'password', 'input', 'output', 'prompt' + * name - name of the devices + * model - model to use ios/junos/xyz, model is loaded dynamically when needed (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. @@ -38,6 +44,7 @@ The block may contain commands to change some behaviour for the given methods (e.g. calling `post_login` to disable the pager). #### `cmd` + Is used to specify commands that should be executed on a model in order to gather its configuration. It can be called with: @@ -69,18 +76,21 @@ Execution order is `:all`, `:secret`, and lastly the command specific block, if given. #### `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. @@ -90,26 +100,32 @@ The passed data is replaced by the return value of the block. it's further processed. ### 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 switch. Takes one argument that is either a block (taking zero parameters) or a string containing a command to execute. #### `pre_logout` + Used to specify commands to run before Oxidized closes the connection to the switch. Takes one argument that is either a block (taking zero parameters) or a string containing a command to execute. #### `send` + Usually used inside `expect` or blocks passed to `post_login`/`pre_logout`. Takes a single parameter: a string to be sent to the switch. -- cgit v1.2.1 From d1723993e6048621f6a2428bcba51c1cd17a124e Mon Sep 17 00:00:00 2001 From: Jason Ackley Date: Tue, 24 Apr 2018 10:11:24 -0500 Subject: Ruby-API.md cleanups Refer to things as 'device' versus 'switch' Add some example use case notes for post_login and pre_logout. MD highlight some items in the list for clarity misc text clarity adjustments. --- docs/Ruby-API.md | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) (limited to 'docs/Ruby-API.md') diff --git a/docs/Ruby-API.md b/docs/Ruby-API.md index 8621870..a9963b3 100644 --- a/docs/Ruby-API.md +++ b/docs/Ruby-API.md @@ -6,7 +6,7 @@ The following objects exist in Oxidized. * gets config from nodes * must implement 'connect', 'get', 'cmd' -* 'ssh', 'telnet, ftp, and tftp' implemented +* 'ssh', 'telnet', 'ftp', and 'tftp' implemented ## Output @@ -18,12 +18,12 @@ The following objects exist in Oxidized. * gets list of nodes to poll * must implement 'load' -* source can have 'name', 'model', 'group', 'username', 'password', 'input', 'output', 'prompt' - * name - name of the devices - * model - model to use ios/junos/xyz, model is loaded dynamically when needed (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) +* 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 @@ -116,16 +116,20 @@ 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 switch. Takes one argument that is either a block (taking zero +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. + #### `pre_logout` Used to specify commands to run before Oxidized closes the connection to the -switch. Takes one argument that is either a block (taking zero parameters) or a +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.) + #### `send` Usually used inside `expect` or blocks passed to `post_login`/`pre_logout`. -Takes a single parameter: a string to be sent to the switch. +Takes a single parameter: a string to be sent to the device. -- cgit v1.2.1