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 --- README.md | 83 ++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 47 insertions(+), 36 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index d501cb5..f733906 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ Oxidized is a network device configuration backup tool. It's a RANCID replacemen [Youtube Video: Oxidized TREX 2014 presentation](http://youtu.be/kBQ_CTUuqeU#t=3h) -#### Index +## Index + 1. [Supported OS Types](docs/Supported-OS-Types.md) 2. [Installation](#installation) * [Debian](#debian) @@ -54,9 +55,10 @@ Oxidized is a network device configuration backup tool. It's a RANCID replacemen * [Source](docs/Ruby-API.md#source) * [Model](docs/Ruby-API.md#model) -# Installation +## Installation + +### Debian -## Debian Install all required packages and gems. ```shell @@ -65,7 +67,8 @@ gem install oxidized gem install oxidized-script oxidized-web # if you don't install oxidized-web, make sure you remove "rest" from your config ``` -## CentOS, Oracle Linux, Red Hat Linux +### CentOS, Oracle Linux, Red Hat Linux + On CentOS 6 / RHEL 6, install Ruby greater than 1.9.3 (for Ruby 2.1.2 installation instructions see [Installing Ruby 2.1.2 using RVM](#installing-ruby-212-using-rvm)), then install Oxidized dependencies ```shell @@ -85,7 +88,8 @@ gem install oxidized gem install oxidized-script oxidized-web ``` -## FreeBSD +### FreeBSD + [Use RVM to install Ruby v2.1.2](#installing-ruby-2.1.2-using-rvm) Install all required packages and gems. @@ -96,7 +100,8 @@ gem install oxidized gem install oxidized-script oxidized-web ``` -## Build from Git +### Build from Git + ```shell git clone https://github.com/ytti/oxidized.git cd oxidized/ @@ -104,38 +109,40 @@ gem build *.gemspec gem install pkg/*.gem ``` -# Running with Docker +## Running with Docker clone git repo: -``` +```shell git clone https://github.com/ytti/oxidized ``` build container locally: -``` +```shell docker build -q -t oxidized/oxidized:latest oxidized/ ``` create config directory in main system: -``` +```shell mkdir /etc/oxidized ``` run container the first time: _Note: this step in only needed for creating Oxidized's configuration file and can be skipped if you already have it -``` +```shell docker run --rm -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -t oxidized/oxidized:latest oxidized ``` + If the RESTful API and Web Interface are enabled, on the docker host running the container edit /etc/oxidized/config and modify 'rest: 127.0.0.1:8888' by 'rest: 0.0.0.0:8888' this will bind port 8888 to all interfaces then expose port out. [Issue #445](https://github.com/ytti/oxidized/issues/445) You can also use docker-compose to launch oxidized container: -``` + +```yaml # docker-compose.yml # docker-compose file example for oxidized that will start along with docker daemon oxidized: @@ -151,13 +158,13 @@ oxidized: create the `/etc/oxidized/router.db` [See CSV Source for further info](docs/Configuration.md#source-csv) -``` +```shell vim /etc/oxidized/router.db ``` run container again: -``` +```shell docker run -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -t oxidized/oxidized:latest oxidized[1]: Oxidized starting, running as pid 1 oxidized[1]: Loaded 1 nodes @@ -169,43 +176,47 @@ Puma 2.13.4 starting... If you want to have the config automatically reloaded (e.g. when using a http source that changes) -``` +```shell docker run -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -e CONFIG_RELOAD_INTERVAL=3600 -t oxidized/oxidized:latest ``` If you need to use an internal CA (e.g. to connect to an private github instance) -``` +```shell docker run -v /etc/oxidized:/root/.config/oxidized -v /path/to/MY-CA.crt:/usr/local/share/ca-certificates/MY-CA.crt -p 8888:8888/tcp -e UPDATE_CA_CERTIFICATES=true -t oxidized/oxidized:latest ``` -# Installing Ruby 2.1.2 using RVM +## Installing Ruby 2.1.2 using RVM Install Ruby 2.1.2 build dependencies -``` + +```shell yum install curl gcc-c++ patch readline readline-devel zlib zlib-devel yum install libyaml-devel libffi-devel openssl-devel make cmake yum install bzip2 autoconf automake libtool bison iconv-devel libssh2-devel ``` Install RVM -``` + +```shell curl -L get.rvm.io | bash -s stable ``` Setup RVM environment and compile and install Ruby 2.1.2 and set it as default -``` + +```shell source /etc/profile.d/rvm.sh rvm install 2.1.2 rvm use --default 2.1.2 ``` -# Configuration +## Configuration + Oxidized configuration is in YAML format. Configuration files are subsequently sourced from `/etc/oxidized/config` then `~/.config/oxidized/config`. The hashes will be merged, this might be useful for storing source information in a system wide file and user specific configuration in the home directory (to only include a staff specific username and password). Eg. if many users are using `oxs`, see [Oxidized::Script](https://github.com/ytti/oxidized-script). It is recommended practice to run Oxidized using its own username. This username can be added using standard command-line tools: -``` +```shell useradd oxidized ``` @@ -215,7 +226,7 @@ To initialize a default configuration in your home directory `~/.config/oxidized You can set the env variable `OXIDIZED_HOME` to change its home directory. -``` +```shell OXIDIZED_HOME=/etc/oxidized $ tree -L 1 /etc/oxidized @@ -239,14 +250,15 @@ Possible outputs are either [File](docs/Configuration.md#output-file), [GIT](doc Maps define how to map a model's fields to model [model fields](https://github.com/ytti/oxidized/tree/master/lib/oxidized/model). Most of the settings should be self explanatory, log is ignored if `use_syslog`(requires Ruby >= 2.0) is set to `true`. First create the directory where the CSV `output` is going to store device configs and start Oxidized once. -``` + +```shell mkdir -p ~/.config/oxidized/configs oxidized ``` Now tell Oxidized where it finds a list of network devices to backup configuration from. You can either use CSV or SQLite as source. To create a CSV source add the following snippet: -``` +```yaml source: default: csv csv: @@ -267,9 +279,9 @@ router02.example.com:ios Run `oxidized` again to take the first backups. -# Extra +## Extra -## Ubuntu SystemV init setup +### Ubuntu SystemV init setup The init script assumes that you have a used named 'oxidized' and that oxidized is in one of the following paths: @@ -284,26 +296,26 @@ The init script assumes that you have a used named 'oxidized' and that oxidized 1. Copy init script from extra/ folder to /etc/init.d/oxidized 2. Setup /var/run/ -``` +```shell mkdir /var/run/oxidized chown oxidized:oxidized /var/run/oxidized ``` 3. Make oxidized start on boot -``` +```shell update-rc.d oxidized defaults ``` -# Help +## Help If you need help with Oxidized then we have a few methods you can use to get in touch. - - [Gitter](https://gitter.im/oxidized/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - You can join the Lobby on gitter to chat to other Oxidized users. - - [GitHub](https://github.com/ytti/oxidized/) - For help and requests for code changes / updates. - - [Forum](https://community.librenms.org/c/help/oxidized) - A user forum run by [LibreNMS](https://github.com/librenms/librenms) where you can ask for help and support. +* [Gitter](https://gitter.im/oxidized/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) - You can join the Lobby on gitter to chat to other Oxidized users. +* [GitHub](https://github.com/ytti/oxidized/) - For help and requests for code changes / updates. +* [Forum](https://community.librenms.org/c/help/oxidized) - A user forum run by [LibreNMS](https://github.com/librenms/librenms) where you can ask for help and support. -# Help Needed +## Help Needed As things stand right now, `oxidized` is maintained by a single person. A great many [contributors](https://github.com/ytti/oxidized/graphs/contributors) have @@ -338,13 +350,12 @@ Brian Anderson (from Rust fame) wrote an [excellent post](http://brson.github.io/2017/04/05/minimally-nice-maintainer) on what it means to be a maintainer. -# License and Copyright +## License and Copyright Copyright 2013-2015 Saku Ytti 2013-2015 Samer Abdel-Hafez - Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at -- cgit v1.2.3 From 6aca017378874993a2e4b34fc5ed947e4c62046c Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Mon, 12 Mar 2018 21:45:21 +0100 Subject: Refresh docker section in readme --- README.md | 36 ++++++++++++++++++++---------------- 1 file changed, 20 insertions(+), 16 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index f733906..1d75611 100644 --- a/README.md +++ b/README.md @@ -109,38 +109,42 @@ gem build *.gemspec gem install pkg/*.gem ``` -## Running with Docker +### Running with Docker -clone git repo: +Currently, Docker Hub automatcally builds the master branch as [oxidized/oxidized](https://hub.docker.com/r/oxidized/oxidized/), you can make use of this container or build your own. + +To build your own, clone git repo: ```shell git clone https://github.com/ytti/oxidized ``` -build container locally: +Then, build the container locally (requires docker 17.05.0-ce or higher): ```shell docker build -q -t oxidized/oxidized:latest oxidized/ ``` -create config directory in main system: +Once you've built the container (or chosen to make use of the automatically built container in Docker Hub, which will be downloaded for you by docker on the first `run` command had you not built it), proceed as follows: + +Create a configuration directory in the host system: ```shell mkdir /etc/oxidized ``` -run container the first time: -_Note: this step in only needed for creating Oxidized's configuration file and can be skipped if you already have it +Run the container for the first time to initialize the config: + +_Note: this step in only required for creating the Oxidized configuration file and can be skipped if you already have one._ ```shell docker run --rm -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -t oxidized/oxidized:latest oxidized ``` If the RESTful API and Web Interface are enabled, on the docker host running the container -edit /etc/oxidized/config and modify 'rest: 127.0.0.1:8888' by 'rest: 0.0.0.0:8888' -this will bind port 8888 to all interfaces then expose port out. [Issue #445](https://github.com/ytti/oxidized/issues/445) +edit `/etc/oxidized/config` and modify `rest: 127.0.0.1:8888` to `rest: 0.0.0.0:8888`. This will bind port 8888 to all interfaces, and expose the port so that it could be accessed externally. [(Issue #445)](https://github.com/ytti/oxidized/issues/445) -You can also use docker-compose to launch oxidized container: +Alternatively, you can use docker-compose to launch the oxidized container: ```yaml # docker-compose.yml @@ -156,13 +160,13 @@ oxidized: - /etc/oxidized:/root/.config/oxidized ``` -create the `/etc/oxidized/router.db` [See CSV Source for further info](docs/Configuration.md#source-csv) +Create the `/etc/oxidized/router.db` (see [CSV Source](docs/Sources.md#source-csv) for futher info): ```shell vim /etc/oxidized/router.db ``` -run container again: +Run container again to start oxidized with your configuration: ```shell docker run -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -t oxidized/oxidized:latest @@ -174,19 +178,19 @@ Puma 2.13.4 starting... * Listening on tcp://0.0.0.0:8888 ``` -If you want to have the config automatically reloaded (e.g. when using a http source that changes) +If you want to have the config automatically reloaded (e.g. when using a http source that changes): ```shell docker run -v /etc/oxidized:/root/.config/oxidized -p 8888:8888/tcp -e CONFIG_RELOAD_INTERVAL=3600 -t oxidized/oxidized:latest ``` -If you need to use an internal CA (e.g. to connect to an private github instance) +If you need to use an internal CA (e.g. to connect to an private github instance): ```shell docker run -v /etc/oxidized:/root/.config/oxidized -v /path/to/MY-CA.crt:/usr/local/share/ca-certificates/MY-CA.crt -p 8888:8888/tcp -e UPDATE_CA_CERTIFICATES=true -t oxidized/oxidized:latest ``` -## Installing Ruby 2.1.2 using RVM +### Installing Ruby 2.1.2 using RVM Install Ruby 2.1.2 build dependencies @@ -271,7 +275,7 @@ source: Now lets create a file based device database (you might want to switch to SQLite later on). Put your routers in `~/.config/oxidized/router.db` (file format is compatible with rancid). Simply add an item per line: -``` +```text router01.example.com:ios switch01.example.com:procurve router02.example.com:ios @@ -285,7 +289,7 @@ Run `oxidized` again to take the first backups. The init script assumes that you have a used named 'oxidized' and that oxidized is in one of the following paths: -``` +```text /sbin /bin /usr/sbin -- cgit v1.2.3 From 1d4e44f28fab2567f3f2692b281c4163c0e9f6ba Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Wed, 14 Mar 2018 22:00:25 +0100 Subject: Document the process of extending models --- README.md | 5 ++-- docs/Extending-Models.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 76 insertions(+), 2 deletions(-) create mode 100644 docs/Extending-Models.md (limited to 'README.md') diff --git a/README.md b/README.md index 1d75611..b3c1912 100644 --- a/README.md +++ b/README.md @@ -48,8 +48,9 @@ Oxidized is a network device configuration backup tool. It's a RANCID replacemen * [Advanced Configuration](docs/Configuration.md#advanced-configuration) * [Advanced Group Configuration](docs/Configuration.md#advanced-group-configuration) * [Hooks](docs/Hooks.md) -5. [Help](#help) -6. [Ruby API](docs/Ruby-API.md#ruby-api) +5. [Extending Models](docs/Extending-Models.md) +6. [Help](#help) +7. [Ruby API](docs/Ruby-API.md#ruby-api) * [Input](docs/Ruby-API.md#input) * [Output](docs/Ruby-API.md#output) * [Source](docs/Ruby-API.md#source) diff --git a/docs/Extending-Models.md b/docs/Extending-Models.md new file mode 100644 index 0000000..4f59f69 --- /dev/null +++ b/docs/Extending-Models.md @@ -0,0 +1,73 @@ +# Extending and Customizing Oxidized Models + +Oxidized supports a growing list of [operating system types](Supported-Os-Types.md). Out of the box, most model implementations collect configuration data. Some implementations also include a conservative set of additional commands that collect basic device information (device make and model, software version, licensing information, ...) which are appended to the configuration as comments. + +A user may wish to extend an existing model to collect the output of additional commands. Oxidized offers smart loading of models in order to facilitate this with ease, without the need to introduce changes to the upstream source code. + +## Extending an existing model with a new command + +The example below can be used to extend the `JunOS` model to collect the output of `show interfaces diagnostics optics` and append the output to the configuration file as a comment. This command retrieves DOM information on pluggable optics present in a `JunOS`-powered chassis. + +Create the file `~/.config/oxidized/model/junos.rb` with the following contents: + +```ruby +require 'oxidized/mode/junos.rb' + + +class JunOS + + + cmd 'show interfaces diagnostics optics' do |cfg| + comment cfg + end + + +end +``` + +Due to smart loading, the user-supplied `~/.config/oxidized/model/junos.rb` file will take precedence over the model with the same name included in Oxidized. The code then uses `require` to load the included model, and extends the class defined therein with an additional command. + +Intuitively, it is also possible to: + +* Completely re-define an existing model by creating a file in `~/.config/oxidized/model/` with the same name as an existing model, but not `require`-ing the upstream model file. +* Create a named variation of an existing model, by creating a file with a new name (such as `~/.config/oxidized/model/junos-extra.rb`), Then `require` the original model and extend its base class as in the above example. The named variation can then be specified as an OS type for some devices but not others when defining sources. +* Create a completely new model, with a new name, for a new operating system type. + +## Advanced features + +The loosely-coupled architecture of Oxidized allows for easy extensibility in more advanced use cases as well. + +The example below extends the functionality of the `JunOS` model further to collect `display set` formatted configuration from the device, and utilizes the multi-output functionality of the `git` output to place the returned configuration in a separate file within a git repository. + +It is possible to configure the `git` output to create new subdirectories under an existing repository instead of creating new repositories for each new defined output type (the default) by including the following configuration in the `~/.config/oxidized/config` file: + +```yaml +output: + git: + type_as_directory: true +``` + +Then, `~/.config/oxidized/model/junos.rb` is adapted as following: + +```ruby +require 'oxidized/mode/junos.rb' + + +class JunOS + + + cmd 'show interface diagnostic optics' do |cfg| + comment cfg + end + + cmd 'show configuration | display set' do |cfg| + cfg.type = "junos-set" + cfg.name = "set" + cfg + end + + +end +``` + +The output of the `show configuration | display set` command is marked with a new arbitrary alternative output type, `junos-set`. The `git` output will use the output type to create a new subdirectory by the same name. In this subdirectory, the `git` output will create files with the name `--set` that will contain the output of this command for each device. \ No newline at end of file -- cgit v1.2.3 From f1048f9b9616a2307d0de6c53847d52a16458bb8 Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Wed, 14 Mar 2018 22:14:38 +0100 Subject: rename extending to creating models and correct typos --- README.md | 2 +- docs/Creating-Models.md | 73 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/Extending-Models.md | 73 ------------------------------------------------ 3 files changed, 74 insertions(+), 74 deletions(-) create mode 100644 docs/Creating-Models.md delete mode 100644 docs/Extending-Models.md (limited to 'README.md') diff --git a/README.md b/README.md index b3c1912..336c05a 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ Oxidized is a network device configuration backup tool. It's a RANCID replacemen * [Advanced Configuration](docs/Configuration.md#advanced-configuration) * [Advanced Group Configuration](docs/Configuration.md#advanced-group-configuration) * [Hooks](docs/Hooks.md) -5. [Extending Models](docs/Extending-Models.md) +5. [Creating and Extending Models](docs/Creating-Models.md) 6. [Help](#help) 7. [Ruby API](docs/Ruby-API.md#ruby-api) * [Input](docs/Ruby-API.md#input) diff --git a/docs/Creating-Models.md b/docs/Creating-Models.md new file mode 100644 index 0000000..3c343e6 --- /dev/null +++ b/docs/Creating-Models.md @@ -0,0 +1,73 @@ +# Creating and Extending Oxidized Models + +Oxidized supports a growing list of [operating system types](Supported-OS-Types.md). Out of the box, most model implementations collect configuration data. Some implementations also include a conservative set of additional commands that collect basic device information (device make and model, software version, licensing information, ...) which are appended to the configuration as comments. + +A user may wish to extend an existing model to collect the output of additional commands. Oxidized offers smart loading of models in order to facilitate this with ease, without the need to introduce changes to the upstream source code. + +## Extending an existing model with a new command + +The example below can be used to extend the `JunOS` model to collect the output of `show interfaces diagnostics optics` and append the output to the configuration file as a comment. This command retrieves DOM information on pluggable optics present in a `JunOS`-powered chassis. + +Create the file `~/.config/oxidized/model/junos.rb` with the following contents: + +```ruby +require 'oxidized/model/junos.rb' + + +class JunOS + + + cmd 'show interfaces diagnostics optics' do |cfg| + comment cfg + end + + +end +``` + +Due to smart loading, the user-supplied `~/.config/oxidized/model/junos.rb` file will take precedence over the model with the same name included in Oxidized. The code then uses `require` to load the included model, and extends the class defined therein with an additional command. + +Intuitively, it is also possible to: + +* Completely re-define an existing model by creating a file in `~/.config/oxidized/model/` with the same name as an existing model, but not `require`-ing the upstream model file. +* Create a named variation of an existing model, by creating a file with a new name (such as `~/.config/oxidized/model/junos-extra.rb`), Then `require` the original model and extend its base class as in the above example. The named variation can then be specified as an OS type for some devices but not others when defining sources. +* Create a completely new model, with a new name, for a new operating system type. + +## Advanced features + +The loosely-coupled architecture of Oxidized allows for easy extensibility in more advanced use cases as well. + +The example below extends the functionality of the `JunOS` model further to collect `display set` formatted configuration from the device, and utilizes the multi-output functionality of the `git` output to place the returned configuration in a separate file within a git repository. + +It is possible to configure the `git` output to create new subdirectories under an existing repository instead of creating new repositories for each new defined output type (the default) by including the following configuration in the `~/.config/oxidized/config` file: + +```yaml +output: + git: + type_as_directory: true +``` + +Then, `~/.config/oxidized/model/junos.rb` is adapted as following: + +```ruby +require 'oxidized/model/junos.rb' + + +class JunOS + + + cmd 'show interface diagnostic optics' do |cfg| + comment cfg + end + + cmd 'show configuration | display set' do |cfg| + cfg.type = "junos-set" + cfg.name = "set" + cfg + end + + +end +``` + +The output of the `show configuration | display set` command is marked with a new arbitrary alternative output type, `junos-set`. The `git` output will use the output type to create a new subdirectory by the same name. In this subdirectory, the `git` output will create files with the name `--set` that will contain the output of this command for each device. \ No newline at end of file diff --git a/docs/Extending-Models.md b/docs/Extending-Models.md deleted file mode 100644 index 0707157..0000000 --- a/docs/Extending-Models.md +++ /dev/null @@ -1,73 +0,0 @@ -# Extending and Customizing Oxidized Models - -Oxidized supports a growing list of [operating system types](Supported-OS-Types.md). Out of the box, most model implementations collect configuration data. Some implementations also include a conservative set of additional commands that collect basic device information (device make and model, software version, licensing information, ...) which are appended to the configuration as comments. - -A user may wish to extend an existing model to collect the output of additional commands. Oxidized offers smart loading of models in order to facilitate this with ease, without the need to introduce changes to the upstream source code. - -## Extending an existing model with a new command - -The example below can be used to extend the `JunOS` model to collect the output of `show interfaces diagnostics optics` and append the output to the configuration file as a comment. This command retrieves DOM information on pluggable optics present in a `JunOS`-powered chassis. - -Create the file `~/.config/oxidized/model/junos.rb` with the following contents: - -```ruby -require 'oxidized/mode/junos.rb' - - -class JunOS - - - cmd 'show interfaces diagnostics optics' do |cfg| - comment cfg - end - - -end -``` - -Due to smart loading, the user-supplied `~/.config/oxidized/model/junos.rb` file will take precedence over the model with the same name included in Oxidized. The code then uses `require` to load the included model, and extends the class defined therein with an additional command. - -Intuitively, it is also possible to: - -* Completely re-define an existing model by creating a file in `~/.config/oxidized/model/` with the same name as an existing model, but not `require`-ing the upstream model file. -* Create a named variation of an existing model, by creating a file with a new name (such as `~/.config/oxidized/model/junos-extra.rb`), Then `require` the original model and extend its base class as in the above example. The named variation can then be specified as an OS type for some devices but not others when defining sources. -* Create a completely new model, with a new name, for a new operating system type. - -## Advanced features - -The loosely-coupled architecture of Oxidized allows for easy extensibility in more advanced use cases as well. - -The example below extends the functionality of the `JunOS` model further to collect `display set` formatted configuration from the device, and utilizes the multi-output functionality of the `git` output to place the returned configuration in a separate file within a git repository. - -It is possible to configure the `git` output to create new subdirectories under an existing repository instead of creating new repositories for each new defined output type (the default) by including the following configuration in the `~/.config/oxidized/config` file: - -```yaml -output: - git: - type_as_directory: true -``` - -Then, `~/.config/oxidized/model/junos.rb` is adapted as following: - -```ruby -require 'oxidized/mode/junos.rb' - - -class JunOS - - - cmd 'show interface diagnostic optics' do |cfg| - comment cfg - end - - cmd 'show configuration | display set' do |cfg| - cfg.type = "junos-set" - cfg.name = "set" - cfg - end - - -end -``` - -The output of the `show configuration | display set` command is marked with a new arbitrary alternative output type, `junos-set`. The `git` output will use the output type to create a new subdirectory by the same name. In this subdirectory, the `git` output will create files with the name `--set` that will contain the output of this command for each device. \ No newline at end of file -- cgit v1.2.3 From ce0216fde8cdf562be4cc9d39aba2cf003d3c7f6 Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Fri, 16 Mar 2018 16:19:21 +0100 Subject: documentation touch-ups and issue #1218 --- README.md | 20 ++++++++++++-------- docs/Creating-Models.md | 2 +- docs/Model-Notes/VRP-Huawei.md | 2 ++ 3 files changed, 15 insertions(+), 9 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 336c05a..09929af 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,26 @@ # Oxidized [![Build Status](https://travis-ci.org/Shopify/oxidized.svg)](https://travis-ci.org/Shopify/oxidized) [![Gem Version](https://badge.fury.io/rb/oxidized.svg)](http://badge.fury.io/rb/oxidized) [![Join the chat at https://gitter.im/oxidized/Lobby](https://badges.gitter.im/oxidized/Lobby.svg)](https://gitter.im/oxidized/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) -> Is your company using Oxidized and has Ruby developers on staff? I'd love help from an extra maintainer! +Oxidized is a network device configuration backup tool. It's a RANCID replacement! -[WANTED: MAINTAINER](#help-needed) +Light and extensible, Oxidized supports over 90 operating system types. -Oxidized is a network device configuration backup tool. It's a RANCID replacement! +Feature highlights: * Automatically adds/removes threads to meet configured retrieval interval -* Restful API to move node immediately to head-of-queue (GET/POST /node/next/[NODE]) -* Syslog udp+file example to catch config change event (ios/junos) and trigger config fetch - * Will signal ios/junos user who made change, which output modules can use (via POST) - * The git output module uses this info - 'git blame' will for each line show who made the change and when +* Restful API to a move node immediately to head-of-queue (GET/POST /node/next/[NODE]) +* Syslog udp+file example to catch config change events (IOS/JunOS) and trigger a config fetch + * Will signal which IOS/JunOS user made the change, can then be used by output modules (via POST) + * The `git` output module uses this info - 'git blame' will show who changed each line, and when * Restful API to reload list of nodes (GET /reload) * Restful API to fetch configurations (/node/fetch/[NODE] or /node/fetch/group/[NODE]) * Restful API to show list of nodes (GET /nodes) * Restful API to show list of version for a node (/node/version[NODE]) and diffs -[Youtube Video: Oxidized TREX 2014 presentation](http://youtu.be/kBQ_CTUuqeU#t=3h) +Check out the [Oxidized TREX 2014 presentation](http://youtu.be/kBQ_CTUuqeU#t=3h) video on YouTube! + +> :warning: [Maintainer Wanted!](#help-needed) :warning: +> +> Is your company using Oxidized and has Ruby developers on staff? I'd love help from an extra maintainer! ## Index diff --git a/docs/Creating-Models.md b/docs/Creating-Models.md index 3c343e6..d7a8155 100644 --- a/docs/Creating-Models.md +++ b/docs/Creating-Models.md @@ -1,4 +1,4 @@ -# Creating and Extending Oxidized Models +# Creating and Extending Models Oxidized supports a growing list of [operating system types](Supported-OS-Types.md). Out of the box, most model implementations collect configuration data. Some implementations also include a conservative set of additional commands that collect basic device information (device make and model, software version, licensing information, ...) which are appended to the configuration as comments. diff --git a/docs/Model-Notes/VRP-Huawei.md b/docs/Model-Notes/VRP-Huawei.md index e68a959..a5c0c99 100644 --- a/docs/Model-Notes/VRP-Huawei.md +++ b/docs/Model-Notes/VRP-Huawei.md @@ -30,4 +30,6 @@ Command 2 and 3 can be executed without issues, but 1 and 4 are only available f Oxidized can now retrieve your configuration! +Caveat: Some versions of VRP default to appending a timestamp prior to the output of each `display` command, which will lead to superfluous updates. The configuration statement `timestamp disable` can be used to disable this functionality. (Issue #1218) + Back to [Model-Notes](README.md) -- cgit v1.2.3 From 720facc6f80d2b977d73b944c81c63b6d95e768b Mon Sep 17 00:00:00 2001 From: Wild Kat Date: Fri, 16 Mar 2018 20:31:09 +0100 Subject: improve spelling in docs --- README.md | 4 ++-- docs/Configuration.md | 2 +- docs/Hooks.md | 4 ++-- docs/Model-Notes/AireOS.md | 2 +- docs/Model-Notes/Comware.md | 2 +- docs/Model-Notes/README.md | 4 ++-- docs/Model-Notes/VRP-Huawei.md | 2 +- docs/Sources.md | 4 ++-- 8 files changed, 12 insertions(+), 12 deletions(-) (limited to 'README.md') diff --git a/README.md b/README.md index 09929af..076c4d5 100644 --- a/README.md +++ b/README.md @@ -116,7 +116,7 @@ gem install pkg/*.gem ### Running with Docker -Currently, Docker Hub automatcally builds the master branch as [oxidized/oxidized](https://hub.docker.com/r/oxidized/oxidized/), you can make use of this container or build your own. +Currently, Docker Hub automatically builds the master branch as [oxidized/oxidized](https://hub.docker.com/r/oxidized/oxidized/), you can make use of this container or build your own. To build your own, clone git repo: @@ -165,7 +165,7 @@ oxidized: - /etc/oxidized:/root/.config/oxidized ``` -Create the `/etc/oxidized/router.db` (see [CSV Source](docs/Sources.md#source-csv) for futher info): +Create the `/etc/oxidized/router.db` (see [CSV Source](docs/Sources.md#source-csv) for further info): ```shell vim /etc/oxidized/router.db diff --git a/docs/Configuration.md b/docs/Configuration.md index 59e3f6d..6bbbb61 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -54,7 +54,7 @@ The above strips out snmp community strings from your saved configs. ## Disabling SSH exec channels -Oxidized uses exec channels to make information extraction simpler, but there are some situations where this doesn't work well, e.g. configuring devices. This feature can be turned off by setting the `ssh_no_exec` +Oxidized uses exec channels to make information extraction simpler, but there are some situations where this doesn't work well, e.g. configuring devices. This feature can be turned off by setting the `ssh_no_exec` variable. ```yaml diff --git a/docs/Hooks.md b/docs/Hooks.md index 1d263fb..8a0a8b9 100644 --- a/docs/Hooks.md +++ b/docs/Hooks.md @@ -11,7 +11,7 @@ Following configuration keys need to be defined for all hooks: ### Events -* `node_success`: triggered when configuration is succesfully pulled from a node and right before storing the configuration. +* `node_success`: triggered when configuration is successfully pulled from a node and right before storing the configuration. * `node_fail`: triggered after `retries` amount of failed node pulls. * `post_store`: triggered after node configuration is stored (this is executed only when the configuration has changed). * `nodes_done`: triggered after finished fetching all nodes. @@ -62,7 +62,7 @@ hooks: ### Hook type: githubrepo -This hook configures the repository `remote` and _push_ the code when the specified event is triggerd. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. +This hook configures the repository `remote` and _push_ the code when the specified event is triggered. If the `username` and `password` are not provided, the `Rugged::Credentials::SshKeyFromAgent` will be used. `githubrepo` hook recognizes following configuration keys: diff --git a/docs/Model-Notes/AireOS.md b/docs/Model-Notes/AireOS.md index 9962f31..5674ae2 100644 --- a/docs/Model-Notes/AireOS.md +++ b/docs/Model-Notes/AireOS.md @@ -1,7 +1,7 @@ Cisco WLC Configuration ======================= -Create a user with read-write privilege : +Create a user with read-write privilege: ```text mgmtuser add oxidized **** read-write diff --git a/docs/Model-Notes/Comware.md b/docs/Model-Notes/Comware.md index 0da019a..e7a2198 100644 --- a/docs/Model-Notes/Comware.md +++ b/docs/Model-Notes/Comware.md @@ -1,7 +1,7 @@ Comware Configuration ===================== -If you find 3Com comware devices aren't being backed up this may be due to prompt detection not matching because a previous login message is disabled after the first prompt. +If you find 3Com Comware devices aren't being backed up this may be due to prompt detection not matching because a previous login message is disabled after the first prompt. You can disable this on the devices themselves by running this command: diff --git a/docs/Model-Notes/README.md b/docs/Model-Notes/README.md index 8dcabd3..c4b0ed1 100644 --- a/docs/Model-Notes/README.md +++ b/docs/Model-Notes/README.md @@ -1,7 +1,7 @@ Model Notes =========== -This directory contains implemention notes and caveats to assist you in your oxidized deployment. +This directory contains implementation notes and caveats to assist you in your oxidized deployment. Use the table below for more information on the Vendor/Model caveats. @@ -12,6 +12,6 @@ AireOS|[AireOS](AireOS.md)|29 Nov 2017 Arbor Networks|[ArbOS](ArbOS.md)|27 Feb 2018 Huawei|[VRP](VRP-Huawei.md)|17 Nov 2017 Juniper|[MX/QFX/EX/SRX/J Series](JunOS.md)|18 Jan 2018 -Xyzel|[XGS4600 Series](XGS4600-Zyxel.md)|23 Jan 2018 +Zyxel|[XGS4600 Series](XGS4600-Zyxel.md)|23 Jan 2018 If you discover additional caveats or problems please make sure to consult the [GitHub issues for oxidized](https://github.com/ytti/oxidized/issues) known issues. diff --git a/docs/Model-Notes/VRP-Huawei.md b/docs/Model-Notes/VRP-Huawei.md index a5c0c99..ff5426e 100644 --- a/docs/Model-Notes/VRP-Huawei.md +++ b/docs/Model-Notes/VRP-Huawei.md @@ -19,7 +19,7 @@ The commands Oxidized executes are: 3. display device 4. display current-configuration all -Command 2 and 3 can be executed without issues, but 1 and 4 are only available for higher level users. Instead of making Oxidized a read/write user on your device, lower the priviledge-level for commands 1 and 4: +Command 2 and 3 can be executed without issues, but 1 and 4 are only available for higher level users. Instead of making Oxidized a read/write user on your device, lower the privilege-level for commands 1 and 4: ```text system-view diff --git a/docs/Sources.md b/docs/Sources.md index 5599409..6d8e19e 100644 --- a/docs/Sources.md +++ b/docs/Sources.md @@ -2,7 +2,7 @@ ## Source: CSV -One line per device, colon seperated. If `ip` isn't present, a DNS lookup will be done against `name`. For large installations, setting `ip` will dramatically reduce startup time. +One line per device, colon separated. If `ip` isn't present, a DNS lookup will be done against `name`. For large installations, setting `ip` will dramatically reduce startup time. ```yaml source: @@ -105,7 +105,7 @@ source: ## Custom SQL Query Support -You may also implement a custom SQL query to retreive the nodelist using SQL syntax with the `query:` configuration parameter under the `sql:` stanza. +You may also implement a custom SQL query to retrieve the nodelist using SQL syntax with the `query:` configuration parameter under the `sql:` stanza. ### Custom SQL Query Examples -- cgit v1.2.3