From a76b41c64845e8421dc1fafea7118e5cedc3bf5d Mon Sep 17 00:00:00 2001 From: Thomas Gelf Date: Mon, 7 Mar 2016 00:49:29 +0100 Subject: [PATCH] doc: re-structure, more documentation fixes #11093 --- README.md | 45 +++---------------- doc/{01-Intro.md => 01-Introduction.md} | 0 doc/02-Installation.md | 51 ++++++++++++++++++++++ doc/{30-Automation.md => 03-Automation.md} | 0 doc/04-Getting-started.md | 25 +++++++++++ doc/70-REST-API.md | 4 +- 6 files changed, 84 insertions(+), 41 deletions(-) rename doc/{01-Intro.md => 01-Introduction.md} (100%) create mode 100644 doc/02-Installation.md rename doc/{30-Automation.md => 03-Automation.md} (100%) create mode 100644 doc/04-Getting-started.md diff --git a/README.md b/README.md index 602fa697..06f84f50 100644 --- a/README.md +++ b/README.md @@ -12,44 +12,11 @@ of them at once. ![Icinga Director](https://www.icinga.org/wp-content/uploads/2016/02/director_main_screen.png) -Requirements ------------- +Learn more about the Director in the documentation: -* Icinga 2 (>= 2.4.3) -* Icinga Web 2 (>= 2.2.0) -* A database, MySQL (>= 5.1) or PostgreSQL (>= 9.1) database (MariaDB and other forks are also fine) -* php5-curl - -Installation ------------- - -### Create Icinga Director database - -#### MySQL - - mysql -e "CREATE DATABASE director CHARACTER SET 'utf8'; - GRANT ALL ON director.* TO director@localhost IDENTIFIED BY 'some-password';" - -#### PostgreSQL - - CREATE DATABASE director WITH ENCODING 'UTF8'; - CREATE USER director WITH PASSWORD 'some-password'; - GRANT ALL PRIVILEGES ON DATABASE director TO director; - - -Configure Icinga Web 2 ----------------------- - -As with any Icinga Web 2 module, installation is pretty straight-forward. In -case you're installing it from source all you have to do is to drop the director -module in one of your module paths. Then go to your web frontend, Configuration, -Modules, director - and enable the module. - -In your web frontend please go to System / Configuration / Resources and create -a new database resource pointing to your newly created database. Last but not -least you have to tell the director module to use this newly created database -resource. - -In case you prefer automated or manual installation please learn more about -[automated installations](doc/30-Automation.md) in the related [section](doc/30-Automation.md) of our documentation. +* [Introduction](doc/01-Introduction.md) +* [Installation](doc/02-Installation.md) +* [Automation](doc/03-Automation.md) +* [Getting started](doc/04-Getting-started.md) +* [REST API](doc/70-REST-API.md) diff --git a/doc/01-Intro.md b/doc/01-Introduction.md similarity index 100% rename from doc/01-Intro.md rename to doc/01-Introduction.md diff --git a/doc/02-Installation.md b/doc/02-Installation.md new file mode 100644 index 00000000..8a9ad9a6 --- /dev/null +++ b/doc/02-Installation.md @@ -0,0 +1,51 @@ +Installation +============ + +These are the instructions for manual Director installations. You can +learn moree about how to automate this in the [automation](03-Automation.md) section +of this documentation. + +Requirements +------------ + +* Icinga 2 (>= 2.4.3) +* Icinga Web 2 (>= 2.2.0) +* A database, MySQL (>= 5.1) or PostgreSQL (>= 9.1) database (MariaDB and + other forks are also fine) +* php5-curl + +Database +-------- + +### Create an empty Icinga Director database + +#### MySQL + + mysql -e "CREATE DATABASE director CHARACTER SET 'utf8'; + GRANT ALL ON director.* TO director@localhost IDENTIFIED BY 'some-password';" + +#### PostgreSQL + + + psql -q -c "CREATE DATABASE director WITH ENCODING 'UTF8';" + psql director -q -c "CREATE USER director WITH PASSWORD 'some-password'; + GRANT ALL PRIVILEGES ON DATABASE director TO director;" + + +Configure Icinga Web 2 +---------------------- + +In your web frontend please go to System / Configuration / Resources and create +a new database resource pointing to your newly created database. Please make +sure that you choose `utf8` as an encoding. + +As with any Icinga Web 2 module, installation is pretty straight-forward. In +case you're installing it from source all you have to do is to drop the director +module in one of your module paths. You can examine (and set) the module path(s) +in `Configuration / General`. In a tipical environment you'll probably drop the +module to `/usr/share/icingaweb2/modules/director`. Please note that the directory +name MUST be `director` and not `icingaweb2-module-director` or anything else. + +Now go to your web frontend, Configuration, Modules, director - and enable the +module. Last but not least you have to tell the director module to use this newly +created database resource. diff --git a/doc/30-Automation.md b/doc/03-Automation.md similarity index 100% rename from doc/30-Automation.md rename to doc/03-Automation.md diff --git a/doc/04-Getting-started.md b/doc/04-Getting-started.md new file mode 100644 index 00000000..2f35ddc7 --- /dev/null +++ b/doc/04-Getting-started.md @@ -0,0 +1,25 @@ +Preparing your Icinga 2 environment for the Director +==================================================== + +Create an API user +------------------ + +```icinga2 +object ApiUser "director" { + password = "***" + permissions = [ "*" ] + //client_cn = "" +} +``` + +Start with a new, empty Icinga setup. Director is not allowed to modify +existing configuration in `/etc/icinga2`, and while importing existing +config is possible (happens for examply automacigally at kickstart time) +this is an advanced task you should not tackle at the early beginning. + +Take some time to really understand work with Icinga Director first. + +Working with Agents and Config Zones +==================================== + +Hint: Large: max packet size diff --git a/doc/70-REST-API.md b/doc/70-REST-API.md index d565d5aa..0f122a52 100644 --- a/doc/70-REST-API.md +++ b/doc/70-REST-API.md @@ -37,7 +37,7 @@ provided property. However, you must always be ready to accept new properties. URL scheme and supported methods -------------------------------- -We support GET, POST, PUT and DELETE. +We support GET, POST, PUT and DELETE. | Method | Meaning | ------ | ------------------------------------------------------------ @@ -394,7 +394,7 @@ If merging properties is not what you want, `PUT` comes to the rescue: PUT director/host?name=apitest ``` -{ "vars": { "event": [ "Icinga", "Camp" ] } +{ "vars": { "event": [ "Icinga", "Camp" ] } ``` All other properties vanished, all but name and type: