README.md in oxidized-0.28.0 vs README.md in oxidized-0.29.0
- old
+ new
@@ -1,16 +1,17 @@
# Oxidized
-[](https://travis-ci.com/ytti/oxidized)
+
+[](https://github.com/ytti/oxidized/actions/workflows/ruby.yml)
[](https://codecov.io/gh/ytti/oxidized?branch=master)
[](https://www.codacy.com/app/ytti/oxidized?utm_source=github.com&utm_medium=referral&utm_content=ytti/oxidized&utm_campaign=Badge_Grade)
[](https://codeclimate.com/github/ytti/oxidized)
[](http://badge.fury.io/rb/oxidized)
[](https://gitter.im/oxidized/Lobby?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
Oxidized is a network device configuration backup tool. It's a RANCID replacement!
-Light and extensible, Oxidized supports more than 120 operating system types.
+Light and extensible, Oxidized supports over 130 operating system types.
Feature highlights:
* Automatically adds/removes threads to meet configured retrieval interval
* Restful API to a move node immediately to head-of-queue (GET/POST /node/next/[NODE])
@@ -74,11 +75,11 @@
## Installation
### Debian and Ubuntu
-Debian "buster" or newer and Ubuntu 17.10 (artful) or newer are recommended. On Ubuntu, begin by enabling the `universe`
+Debian "buster" or newer and Ubuntu 17.10 (artful) or newer are recommended. On Ubuntu, begin by enabling the `universe`
repository (required for libssh2-1-dev):
```shell
add-apt-repository universe
```
@@ -96,35 +97,55 @@
gem install oxidized-script oxidized-web # If you don't install oxidized-web, ensure "rest" is removed from your Oxidized config.
```
### CentOS, Oracle Linux, Red Hat Linux
-On CentOS 6 and 7 / RHEL 6 and 7, begin by installing Ruby 2.3 or greater. This can be accomplished in one of two ways:
+On CentOS 6 and 7 / RHEL 6 and 7, begin by installing Ruby 2.3 or greater. This can be accomplished in one of several ways:
Install Ruby 2.3 from [SCL](https://www.softwarecollections.org/en/scls/rhscl/rh-ruby23/):
```shell
yum install centos-release-scl
-yum install rh-ruby23 rh-ruby23-ruby-devel
-scl enable rh-ruby23 bash
+yum install rh-ruby30 rh-ruby30-ruby-devel
+scl enable rh-ruby30 bash
```
The following additional packages will be required to build the dependencies:
```shell
yum install make cmake which sqlite-devel openssl-devel libssh2-devel ruby gcc ruby-devel libicu-devel gcc-c++
```
-Alternatively, install Ruby 2.3 by following the instructions at [Installing Ruby 2.3 using RVM](#installing-ruby-23-using-rvm).
+Alternatively, install Ruby 2.6 via RVM by following the instructions:
-Finally, install oxidized via Rubygems:
+Make sure you dont have any leftover ruby:
+```yum erase ruby```
+Then, install gpg key and rvm
+
```shell
-gem install oxidized
-gem install oxidized-script oxidized-web # if you don't install oxidized-web, make sure you remove "rest" from your config
+sudo gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
+curl -sSL https://get.rvm.io | bash -s stable
+source /etc/profile.d/rvm.sh
+rvm requirements run
+rvm install 3.0
+rvm use 3.0
```
+Install oxidized requirements:
+```yum install make cmake which sqlite-devel openssl-devel libssh2-devel gcc libicu-devel gcc-c++```
+
+Install the gems:
+```gem install oxidized oxidized-web```
+
+You need to wrap the gem and reference the wrap in the systemctl service file:
+```rvm wrapper oxidized```
+
+You can see where the wrapped gem is via
+```rvm wrapper show oxidized```
+Use that path in the oxidized.service file, restart the systemctl daemon, run oxidized by hand once, edit config file, start service.
+
### FreeBSD
[Use RVM to install Ruby v2.3](#installing-ruby-23-using-rvm), then install all required packages and gems:
```shell
@@ -175,30 +196,38 @@
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
+docker run --rm -v /etc/oxidized:/home/oxidized/.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` 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)
Alternatively, you can use docker-compose to launch the oxidized container:
```yaml
# docker-compose.yml
# docker-compose file example for oxidized that will start along with docker daemon
-oxidized:
- restart: always
- image: oxidized/oxidized:latest
- ports:
- - 8888:8888/tcp
- environment:
- CONFIG_RELOAD_INTERVAL: 600
- volumes:
- - /etc/oxidized:/root/.config/oxidized
+---
+version: "3"
+services:
+ oxidized:
+ restart: always
+ image: oxidized/oxidized:latest
+ ports:
+ - 8888:8888/tcp
+ environment:
+ CONFIG_RELOAD_INTERVAL: 600
+ volumes:
+ - config:/home/oxidized/.config/oxidized/config
+ - router.db:/home/oxidized/.config/oxidized/router.db
+ - model:/home/oxidized/.config/oxidized/model
+ # if git is use as input
+ - data:/home/oxidized/.config/oxidized/backupcfg/
+
```
Create the `/etc/oxidized/router.db` (see [CSV Source](docs/Sources.md#source-csv) for further info):
```shell
@@ -206,11 +235,11 @@
```
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
+docker run -v /etc/oxidized:/home/oxidized/.config/oxidized -p 8888:8888/tcp -t oxidized/oxidized:latest
oxidized[1]: Oxidized starting, running as pid 1
oxidized[1]: Loaded 1 nodes
Puma 2.13.4 starting...
* Min threads: 0, max threads: 16
* Environment: development
@@ -218,17 +247,17 @@
```
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
+docker run -v /etc/oxidized:/home/oxidized/.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
+docker run -v /etc/oxidized:/home/oxidized/.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.3 using RVM
Install Ruby 2.3 build dependencies
@@ -258,11 +287,11 @@
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
+useradd -s /bin/bash -m oxidized
```
> It is recommended __not__ to run Oxidized as root.
To initialize a default configuration in your home directory `~/.config/oxidized/config`, simply run `oxidized` once. If you don't further configure anything from the output and source sections, it'll extend the examples on a subsequent `oxidized` execution. This is useful to see what options for a specific source or output backend are available.
@@ -322,34 +351,39 @@
Run `oxidized` again to take the first backups.
## Extra
-### Ubuntu SystemV init setup
+### Ubuntu init setup
-The init script assumes that you have a user named 'oxidized' and that oxidized is in one of the following paths:
+The systemd service assumes that you have a user named 'oxidized' and that oxidized is in one of the following paths:
```text
/sbin
/bin
/usr/sbin
/usr/bin
/usr/local/bin
```
-1. Copy init script from extra/ folder to /etc/init.d/oxidized
-2. Setup /var/run/
+1. Copy systemd service file from extra/ folder to /etc/systemd/system
```shell
-mkdir /var/run/oxidized
-chown oxidized:oxidized /var/run/oxidized
+sudo cp extra/oxidized.service /etc/systemd/system
```
+2. Setup `/var/run/`
+
+```shell
+mkdir /run/oxidized
+chown oxidized:oxidized /run/oxidized
+```
+
3. Make oxidized start on boot
```shell
-update-rc.d oxidized defaults
+sudo systemctl enable oxidized.service
```
## Help
If you need help with Oxidized then we have a few methods you can use to get in touch.
@@ -383,10 +417,10 @@
* Rework the core infrastructure
* Permission from your employer to contribute to open source projects
## YES, I WANT TO HELP
-Awesome! Simply send an email to Saku Ytti <saku@ytti.fi>.
+Awesome! Simply send an e-mail to Saku Ytti at <saku@ytti.fi>.
## Further reading
Brian Anderson (from Rust fame) wrote an [excellent
post](http://brson.github.io/2017/04/05/minimally-nice-maintainer) on what it