Skip to content

Commit

Permalink
Lint and standardize markdown documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@wk
wk committed Mar 12, 2018
1 parent 34cdbeb commit 87600b1
Show file tree
Hide file tree
Showing 16 changed files with 736 additions and 658 deletions.
610 changes: 324 additions & 286 deletions CHANGELOG.md
View file

Large diffs are not rendered by default.

83 changes: 47 additions & 36 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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.
Expand All @@ -96,46 +100,49 @@ 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/
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:
Expand All @@ -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
Expand All @@ -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
```

Expand All @@ -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
Expand All @@ -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:
Expand All @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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 <[email protected]>
2013-2015 Samer Abdel-Hafez <[email protected]>


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
Expand Down
52 changes: 29 additions & 23 deletions TODO.md
View file
Original file line number Diff line number Diff line change
@@ -1,23 +1,29 @@
# refactor core
* move state from memory to disk, sqlite probably
* allows us to retain stats etc over restart
* simplifies code
* keep only running nodes in memory
* negligible I/O cost, as majority is I/O wait getting config

# separate login to owon package
* oxidized-script is not only use-case
* it would be good to have minimal package used to login to routers
* oxidized just one consumer of that functionality
* what to do with models, we need model to know how to login. Should models be separated to another package? oxidized-core, oxidized-models and oxidized-login?
* how can we allow interactive login in oxidized-login? With functional VTY etc? REPL loop in input/ssh and input/telnet?

# thread number
* think about algo
* if job ended later than now-iteration have rand(node.size) == 0 to add thread
* if now is less than job_ended+iteration same chance to remove thread?
* should we try to avoid max threads from being hit? (like maybe non-success thread is pulling average?)

# docs, testing
* yard docs
* minitest tests
# To Do

## refactor core

* move state from memory to disk, sqlite probably
* allows us to retain stats etc over restart
* simplifies code
* keep only running nodes in memory
* negligible I/O cost, as majority is I/O wait getting config

## separate login to own package

* oxidized-script is not only use-case
* it would be good to have minimal package used to login to routers
* oxidized just one consumer of that functionality
* what to do with models, we need model to know how to login. Should models be separated to another package? oxidized-core, oxidized-models and oxidized-login?
* how can we allow interactive login in oxidized-login? With functional VTY etc? REPL loop in input/ssh and input/telnet?

## thread number

* think about algo
* if job ended later than now-iteration have rand(node.size) == 0 to add thread
* if now is less than job_ended+iteration same chance to remove thread?
* should we try to avoid max threads from being hit? (like maybe non-success thread is pulling average?)

## docs, testing

* yard docs
* minitest tests
Loading

0 comments on commit 87600b1

Please sign in to comment.