Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

proposal for a refactoring of the README.rst file #357

Merged
merged 2 commits into from

2 participants

@tvtue

No description provided.

@naparuba
Owner

Looks great, Thanks! :)

@naparuba naparuba merged commit c289638 into naparuba:master
@tvtue
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 119 additions and 84 deletions.
  1. +119 −84 README.rst
View
203 README.rst
@@ -15,7 +15,24 @@ and plug-ins. It works on any operating system and architecture that
supports Python, which includes Windows and GNU/Linux.
Requirements
-=========================
+============
+
+Basically you have three methods of how to install shinken. These three
+methods are described below, but always keep in mind that you should never
+mix the methods. Thus if you installed with the first way, you have to use
+that method too when you update or remove your installation.
+
+The "install script" method (first described and recommended way) tries to
+do all the necessary steps for you. You can choose that one if your OS is
+compatible with it. So if you choose that one, you can skip
+skim over the requirements section and may come back later if something goes wrong.
+
+However you can also check any requirement manually just to make sure that
+it should work.
+
+
+Common Requirements
+-------------------
`shinken` requires
@@ -28,6 +45,12 @@ Requirements
__ http://www.python.org/download/
__ http://pypi.python.org/pypi/multiprocessing/
+* python-devel Package
+
+
+Conditional Requirements
+------------------------
+
If (and only if) you plan to use the `livestatus` module or the web interface, you will also
need
@@ -40,11 +63,16 @@ __ http://pypi.python.org/pypi/ujson/
__ http://code.google.com/p/pysqlite/
-Just untar and launch `python setup.py install` (and be sure to have
-installed the `python-devel` package too).
+Installing/Checking Common Requirements on Linux
+================================================
-For Python, it should be okay with almost all distributions.
+Python
+------
+For Python itself, the version which comes with almost all distributions
+should be okay.
+Pyro
+----
Under ubuntu, you can grab the Pyro module with::
sudo apt-get install pyro
@@ -59,42 +87,27 @@ And if you do not find it, you can install it from PyPI::
How to install Shinken
-=========================
+=======================
-You just need to add a shinken user (in the shinken group) on your
-system::
- useradd --user-group shinken
- usermod --lock shinken
+Preliminary Steps
+-----------------
-First way: all in a directory (ugly but quick way ;)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+* Download and untar shinken.
-Then move the shinken directory and give it to the shinken user::
+* Create a user account and a group for shinken on your system (not necessary if using install script)::
- mv shinken /usr/local
- chown -R shinken:shinken /usr/local/shinken
-
-Second way: district directory (clean way)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-You can install really the application by using the `setup.py` script.
-It will install the shinken library in the python path, create the
-`/etc/shinken` and `/var/lib/shinken` directory (you can change them in
-the `setup.cfg` file before launching `setup.py`). You will
-need the `python-setuptools` package for it. Then just run::
-
- sudo python setup.py install --install-scripts=/usr/bin/
-
-For the compilation part in both way it's easy: there is no
-compilation!
+ useradd --user-group shinken
+ usermod --lock shinken
-Third way: install script
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Important Note:: NEVER EVER MIX THE DIFFERENTS INSTALLATION METHODS. THIS WILL RUN YOU IN BIG TROUBLES. CHOOSE ONE AND UNINSTALL BEFORE TRYING THE OTHER.
-Note : NEVER EVER MIX THE DIFFERENTS INSTALLATION METHODS. THIS WILL RUN YOU IN BIG TROUBLES. CHOOSE ONE AND UNINSTALL BEFORE TRYING THE OTHER.
+First way: install script (recommended for end users)
+=====================================================
-You can use the install utility script located at the root of the shinken sources.
+Install
+-------
+You can use the install script utility located at the root of the shinken sources.
The script creates the user and group, installs all dependencies and then it installs shinken. It is compatible with Debian, Ubuntu, Centos/Redhat 5.x and 6.x
The only requirement is an internet connection for the server on which you want to install shinken. It also allows to modify the installation folder in a configuration file.
@@ -104,15 +117,8 @@ If you want shinken installed in seconds (default in /usr/local/shinken), just r
see install.d/README file for further information.
-
-How to update
-=========================
-
-If you used the setup.py way, launch ::
- sudo python setup.py update --install-scripts=/usr/bin/
-
-If you used the install script method :
-
+Update
+------
1 - grab the latest shinken archive and extract its content
2 - cd into the resulting folder
@@ -125,7 +131,7 @@ If you used the install script method :
./install -u
-5 - install shinken::
+5 - install the new version::
./install -i
@@ -134,40 +140,46 @@ If you used the install script method :
./install -r backupid
-Where is the configuration?
-================================
-
-The configuration is where you put the etc directory (in
-`/usr/local/shinken/etc` for a quick and dirty install, `/etc/shinken`
-for a clean one).
-
-The `nagios.cfg` file is meant to be shared with Nagios. All Shinken
-specific objects (like links to daemons or realms) are in the file
-`shinken-specific.cfg`.
+Remove
+-------
+cd into shinken source folder and run::
+ ./install -u
+Running
+-------
+The install script also installs some `init.d` scripts, enables them at boot time and starts them right after the install process ends.
-Do I need to change my existing Nagios configuration?
-===================================================
-No, there is no need to change the existing configuration - unless
-you want to add some new hosts and services. Once you are comfortable
-with Shinken you can start to use its unique and powerful features.
+Second way: district directory (clean way)
+=====================================================
-How to run Shinken
-================================
+Install
+-------
+In fact you can install the application by using the `setup.py` script.
+No compilation is needed!
+`setup.py` will install the shinken library in the python path, create the
+`/etc/shinken` and `/var/lib/shinken` directory (you can change them in
+the `setup.cfg` file before launching `setup.py`). You will
+need the `python-setuptools` package for it. Then just run::
-Quick and dirty way
-~~~~~~~~~~~~~~~~~~~~
+ sudo python setup.py install --install-scripts=/usr/bin/
-It's easy, there is a already launch script for you::
+Update
+------
- shinken/bin/launch_all.sh
+For this way you can launch ::
+ sudo python setup.py update --install-scripts=/usr/bin/
-Clean way
-~~~~~~~~~~~~~~~~~~~~
+Remove
+------
+There is a script called clean.sh in the source directory for this task.
+It contains relative paths so it should be run from within the source dir.
+Beware, it will delete all Shinken related files!
-The `setup.py` install some `init.d` scripts, let's use them::
+Running
+-------
+The `setup.py` installs some `init.d` scripts, let's use them::
/etc/init.d/shinken-scheduler start
/etc/init.d/shinken-poller start
@@ -175,32 +187,55 @@ The `setup.py` install some `init.d` scripts, let's use them::
/etc/init.d/shinken-broker start
/etc/init.d/shinken-arbiter start
-Install script
-~~~~~~~~~~~~~~~~~~~~
-The install script also install some `init.d` scripts and enable them at boot time and start them right after install process end.
-Known bugs
-================================
+Third way: all in a directory (ugly but quick way ;)
+=====================================================
-None that we know of. :)
+Install
+-------
+After unpacking the tarball move the shinken directory to the desired destination
+and give it to the shinken user::
-If you find one, please post it to the bug and issue tracker :
-https://github.com/naparuba/shinken/issues
+ mv shinken /usr/local
+ chown -R shinken:shinken /usr/local/shinken
+Upadate/Remove
+--------------
+Should be easy here.
-How to run uninstall Shinken
-================================
+Running
+-------
+It's easy, there is already a launch script for you::
-Clean all :)
-~~~~~~~~~~~~~~~~~~~~
+ shinken/bin/launch_all.sh
-There is a script called clean.sh in the source directory for this task.
-Beware, it will supress all Shinken related files!
-If you used install script
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-cd into shinken source folder and run::
- ./install -u
+Where is the configuration?
+===========================
+
+The configuration is where you put the etc directory (in
+`/usr/local/shinken/etc` for a quick and dirty install, `/etc/shinken`
+for a clean one).
+
+The `nagios.cfg` file is meant to be shared with Nagios. All Shinken
+specific objects (like links to daemons or realms) are in the file
+`shinken-specific.cfg`.
+
+
+Do I need to change my existing Nagios configuration?
+=====================================================
+
+No, there is no need to change the existing configuration - unless
+you want to add some new hosts and services. Once you are comfortable
+with Shinken you can start to use its unique and powerful features.
+
+Known bugs
+================================
+
+None that we know of. :)
+
+If you find one, please post it to the bug and issue tracker :
+https://github.com/naparuba/shinken/issues
Something went wrong with that request. Please try again.