README.md in oxidized-0.19.0 vs README.md in oxidized-0.20.0

- old
+ new

@@ -17,10 +17,11 @@ #### Index 1. [Supported OS Types](#supported-os-types) 2. [Installation](#installation) * [Debian](#debian) * [CentOS, Oracle Linux, Red Hat Linux](#centos-oracle-linux-red-hat-linux) + * [BSD](#freebsd) 3. [Initial Configuration](#configuration) 4. [Installing Ruby 2.1.2 using RVM](#installing-ruby-2.1.2-using-rvm) 5. [Running with Docker](#running-with-docker) 6. [Cookbook](#cookbook) * [Debugging](#debugging) @@ -30,10 +31,11 @@ * [Source: SQL](#source-sql) * [Source: SQLite](#source-sqlite) * [Source: Mysql](#source-mysql) * [Source: HTTP](#source-http) * [Output: GIT](#output-git) + * [Output: GIT-Crypt](#output-git-crypt) * [Output: HTTP](#output-http) * [Output: File](#output-file) * [Output types](#output-types) * [Advanced Configuration](#advanced-configuration) * [Advanced Group Configuration](#advanced-group-configuration) @@ -62,10 +64,12 @@ * [EOS](lib/oxidized/model/eos.rb) * Arris * [C4CMTS](lib/oxidized/model/c4cmts.rb) * Aruba * [AOSW](lib/oxidized/model/aosw.rb) + * Avaya + * [VOSS](lib/oxidized/model/voss.rb) * Brocade * [FabricOS](lib/oxidized/model/fabricos.rb) * [Ironware](lib/oxidized/model/ironware.rb) * [NOS (Network Operating System)](lib/oxidized/model/nos.rb) * [Vyatta](lib/oxidized/model/vyatta.rb) @@ -73,17 +77,18 @@ * Casa * [Casa](lib/oxidized/model/casa.rb) * Check Point * [GaiaOS](lib/oxidized/model/gaiaos.rb) * Ciena - * [SOAS](lib/oxidized/model/saos.rb) + * [SAOS](lib/oxidized/model/saos.rb) * Cisco * [AireOS](lib/oxidized/model/aireos.rb) * [ASA](lib/oxidized/model/asa.rb) * [CatOS](lib/oxidized/model/catos.rb) * [IOS](lib/oxidized/model/ios.rb) * [IOSXR](lib/oxidized/model/iosxr.rb) + * [NGA](lib/oxidized/model/cisconga.rb) * [NXOS](lib/oxidized/model/nxos.rb) * [SMB (Nikola series)](lib/oxidized/model/ciscosmb.rb) * Citrix * [NetScaler (Virtual Applicance)](lib/oxidized/model/netscaler.rb) * Coriant (former Tellabs) @@ -123,39 +128,50 @@ * Juniper * [JunOS](lib/oxidized/model/junos.rb) * [ScreenOS (Netscreen)](lib/oxidized/model/screenos.rb) * Mellanox * [MLNX-OS](lib/oxidized/model/mlnxos.rb) + * [Voltaire](lib/oxidized/model/voltaire.rb) * Mikrotik * [RouterOS](lib/oxidized/model/routeros.rb) * Motorola * [RFS](lib/oxidized/model/mtrlrfs.rb) * MRV * [MasterOS](lib/oxidized/model/masteros.rb) * [FiberDriver](lib/oxidized/model/fiberdriver.rb) + * Netgear + * [Netgear](lib/oxidized/model/netgear.rb) * Netonix * [WISP Switch (As Netonix)](lib/oxidized/model/netonix.rb) * Nokia (formerly TiMetra, Alcatel, Alcatel-Lucent) * [SR OS (TiMOS)](lib/oxidized/model/timos.rb) + * OneAccess + * [OneOS](lib/oxidized/model/oneos.rb) * Opengear * [Opengear](lib/oxidized/model/opengear.rb) * Palo Alto * [PANOS](lib/oxidized/model/panos.rb) * [PLANET SG/SGS Switches](lib/oxidized/model/planet.rb) * [pfSense](lib/oxidized/model/pfsense.rb) * Quanta * [Quanta / VxWorks 6.6 (1.1.0.8)](lib/oxidized/model/quantaos.rb) + * Siklu + * [EtherHaul](lib/oxidized/model/siklu.rb) * Supermicro * [Supermicro](lib/oxidized/model/supermicro.rb) * Trango Systems * [Trango](lib/oxidized/model/trango.rb) + * TPLink + * [TPLink](lib/oxidized/model/tplink.rb) * Ubiquiti * [AirOS](lib/oxidized/model/airos.rb) * [Edgeos](lib/oxidized/model/edgeos.rb) * [EdgeSwitch](lib/oxidized/model/edgeswitch.rb) * Watchguard * [Fireware OS](lib/oxidized/model/firewareos.rb) + * Zhone + * [Zhone (OLT and MX)](lib/oxidized/model/zhoneolt.rb) * Zyxel * [ZyNOS](lib/oxidized/model/zynos.rb) # Installation @@ -184,10 +200,31 @@ ```shell gem install oxidized gem install oxidized-script oxidized-web ``` +## FreeBSD +Use RVM to install Ruby v2.1.2 + +Install all required packages and gems. + +```shell +pkg install cmake pkgconf +gem install oxidized +gem install oxidized-script oxidized-web +``` + + + +## Build from Git +```shell +git clone https://github.com/ytti/oxidized.git +cd oxidized/ +gem build *.gemspec +gem install pkg/*.gem +``` + # 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: @@ -219,11 +256,11 @@ Oxidized supports ```CSV```, ```SQLite``` and ```HTTP``` as source backends. The CSV backend reads nodes from a rancid compatible router.db file. The SQLite backend will fire queries against a database and map certain fields to model items. The HTTP backend will fire queries against a http/https url. Take a look at the [Cookbook](#cookbook) for more details. ## Outputs -Possible outputs are either ```file``` or ```git```. The file backend takes a destination directory as argument and will keep a file per device, with most recent running version of a device. The GIT backend (recommended) will initialize an empty GIT repository in the specified path and create a new commit on every configuration change. Take a look at the [Cookbook](#cookbook) for more details. +Possible outputs are either ```file```, ```git``` or ```git-crypt```. The file backend takes a destination directory as argument and will keep a file per device, with most recent running version of a device. The GIT backend (recommended) will initialize an empty GIT repository in the specified path and create a new commit on every configuration change. The GIT-Crypt backend will also initialize a GIT repository but every configuration push to it will be encrypted on the fly by using ```git-crypt``` tool. Take a look at the [Cookbook](#cookbook) for more details. 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. ``` @@ -231,16 +268,19 @@ 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: +Note: If gpg is set to anything other than false it will attempt to decrypt the file contents ``` source: default: csv csv: file: ~/.config/oxidized/router.db delimiter: !ruby/regexp /:/ + gpg: false + gpg_password: 'password' map: name: 0 model: 1 ``` @@ -342,20 +382,30 @@ ``` 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) + +``` +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 +``` + ## Cookbook ### Debugging -In case a model plugin doesn't work correctly (ios, procurve, etc.), you can enable live debugging of SSH/Telnet sessions. Just add a ```debug``` option, specifying a log file destination to the ```input``` section. +In case a model plugin doesn't work correctly (ios, procurve, etc.), you can enable live debugging of SSH/Telnet sessions. Just add a ```debug``` option containing the value true to the ```input``` section. The log files will be created depending on the parent directory of the logfile option. -The following example will log an active ssh session to ```/home/fisakytt/.config/oxidized/log_input-ssh``` and telnet to ```log_input-telnet```. The file will be truncated on each consecutive ssh/telnet session, so you need to put a ```tailf``` or ```tail -f``` on that file! +The following example will log an active ssh/telnet session ```/home/oxidized/.config/oxidized/log/<IP-Adress>-<PROTOCOL>```. The file will be truncated on each consecutive ssh/telnet session, so you need to put a ```tailf``` or ```tail -f``` on that file! ``` +log: /home/oxidized/.config/oxidized/log + +... + input: default: ssh, telnet - debug: /tmp/oxidized_log_input + debug: true ssh: secure: false ``` ### Privileged mode @@ -401,25 +451,26 @@ ssh_no_exec: true ``` ### Source: CSV -One line per device, colon seperated. +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. ``` source: default: csv csv: file: /var/lib/oxidized/router.db delimiter: !ruby/regexp /:/ map: name: 0 - model: 1 - username: 2 - password: 3 + ip: 1 + model: 2 + username: 3 + password: 4 vars_map: - enable: 4 + enable: 5 ``` ### SSH Proxy Command Oxidized can `ssh` through a proxy as well. To do so we just need to set `ssh_proxy` variable. @@ -579,10 +630,76 @@ single_repo: true repo: "/var/lib/oxidized/devices.git" ``` +### Output: Git-Crypt + +This uses the gem git and system git-crypt interfaces. Have a look at [GIT-Crypt](https://www.agwa.name/projects/git-crypt/) documentation to know how to install it. +Additionally to user and email informations, you have to provide the users ID that can be a key ID, a full fingerprint, an email address, or anything else that uniquely identifies a public key to GPG (see "HOW TO SPECIFY A USER ID" in the gpg man page). + + +For a single repositories for all devices: + +``` yaml +output: + default: gitcrypt + gitcrypt: + user: Oxidized + email: o@example.com + repo: "/var/lib/oxidized/devices" + users: + - "0x0123456789ABCDEF" + - "<user@example.com>" +``` + +And for groups repositories: + +``` yaml +output: + default: gitcrypt + gitcrypt: + user: Oxidized + email: o@example.com + repo: "/var/lib/oxidized/git-repos/default" + users: + - "0xABCDEF0123456789" + - "0x0123456789ABCDEF" +``` + +Oxidized will create a repository for each group in the same directory as the `default`. For +example: + +``` csv +host1:ios:first +host2:nxos:second +``` + +This will generate the following repositories: + +``` bash +$ ls /var/lib/oxidized/git-repos + +default.git first.git second.git +``` + +If you would like to use groups and a single repository, you can force this with the `single_repo` config. + +``` yaml +output: + default: gitcrypt + gitcrypt: + single_repo: true + repo: "/var/lib/oxidized/devices" + users: + - "0xABCDEF0123456789" + - "0x0123456789ABCDEF" + +``` + +Please note that user list is only updated once at creation. + ### Output: Http POST a config to the specified URL ``` @@ -722,11 +839,37 @@ map: model: 0 name: 1 group: 2 ``` +For model specific credentials +``` +models: + junos: + username: admin + password: password + ironware: + username: admin + password: password + vars: + enable: enablepassword + apc_aos: + username: apc + password: password +``` + +### Triggered backups + +A node can be moved to head-of-queue via the REST API `GET/POST /node/next/[NODE]`. + +In the default configuration this node will be processed when the next job worker becomes available, it could take some time if existing backups are in progress. To execute moved jobs immediately a new job can be added: + +``` +next_adds_job: true +``` + # Hooks You can define arbitrary number of hooks that subscribe different events. The hook system is modular and different kind of hook types can be enabled. ## Configuration Following configuration keys need to be defined for all hooks: @@ -746,10 +889,11 @@ Command is executed with the following environment: ``` OX_EVENT OX_NODE_NAME +OX_NODE_IP OX_NODE_FROM OX_NODE_MSG OX_NODE_GROUP OX_JOB_STATUS OX_JOB_TIME @@ -841,9 +985,60 @@ * `region`: AWS Region name * `topic_arn`: ASN Topic reference Your AWS credentials should be stored in `~/.aws/credentials`. + +## Hook type: slackdiff + +The `slackdiff` hook posts colorized config diffs to a [Slack](http://www.slack.com) channel of your choice. It only triggers for `post_store` events. + +You will need to manually install the `slack-api` gem on your system: + +``` +gem install slack-api +``` + +Configuration example: + +``` yaml +hooks: + slack: + type: slackdiff + events: [post_store] + token: SLACK_BOT_TOKEN + channel: "#network-changes" +``` + +# Extra + +## 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: + +``` +/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/ + +``` +mkdir /var/run/oxidized +chown oxidized:oxidized /var/run/oxidized +``` + +3.)Make oxidized start on boot + +``` +update-rc.d oxidized deafults +``` + +Note the channel name must be in quotes. # Ruby API The following objects exist in Oxidized.