Merge pull request #11 from CitoEngine/v1.0.0

Release 1.0.0
CitoEngine · Jun 21, 2015 · 754c611 · 754c611
2 parents 5fdfb21 + 127f2e1
commit 754c611
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 100 deletions.
diff --git a/source/installcitoengine.rst b/source/installcitoengine.rst
@@ -2,9 +2,9 @@ Installing CitoEngine
 =====================
 
 The following guide shows installation steps on ``Ubuntu 12.04 x86_64``. Theoretically application dependencies can be fulfilled on any
-linux distribution viz. Redhat, ArchLinux, etc. In future, we will try to include installation steps for other distributions as well.
+linux distribution i.e. Redhat, ArchLinux, etc. In future, we will try to include installation steps for other distributions as well.
 Python module dependencies are installed using `pip`_ rather than system installer, this gives us more control towards using modules of specific versions.
-The following steps assume that you will be installing in ``/opt/cito`` directory.
+The following steps assume that you will be installing in ``/opt/citoengine`` directory.
 
 .. _pip: http://www.pip-installer.org/
 
@@ -17,128 +17,84 @@ Installation
 
 
     # Installing MySQL and Python development packages
-    sudo apt-get install libmysqlclient-dev python-dev python-pip
+    sudo apt-get install libmysqlclient-dev python-dev python-pip git
     sudo pip install virtualenv
-    # If you are going to use ldap authentication, then install the following as well
-    sudo apt-get install libldap2-dev libsasl2-dev libssl-dev
 
-**MySQL Installation and Configuration**
-
-
-.. code-block:: bash
+.. note:: If you are going to use ldap authentication, then install the following as well  ``sudo apt-get install libldap2-dev libsasl2-dev libssl-dev``
 
-    # Install mysql server
-    sudo apt-get install mysql-server mysql-client
-
-    # Setup mysql root password
-    sudo dpkg-reconfigure mysql-server-5.5
-    # Create a new database 'cito'
-    sudo mysqladmin -uroot -p create cito
-    # Create a new mysql user
-    /usr/bin/mysql -uroot -p -e "GRANT ALL PRIVILEGES ON cito.* TO 'cito_user'@'localhost' IDENTIFIED BY 'MINISTRYOFSILLYWALKS' with GRANT OPTION"
 
-**Setup python virtualenv**
+**Downloading and installing the code**
 
 We recommend you use ``virtualenv`` for running citoengine, this will help you manage dependencies better. Download the latest build
 
 .. code-block:: bash
 
+    cd /tmp
+    git clone https://github.com/CitoEngine/cito_engine
+    cd /tmp/cito_engine
+    python setup.py install
     cd /opt/
-    git clone https://github.com/CitoEngine/cito_engine /opt/cito
+    virtualenv /opt/citoengine
+    source /opt/citoengine/bin/activate
+    pip install -r /tmp/cito_engine/requirements.txt
+
+
+**MySQL Installation and Configuration**
 
 
 .. code-block:: bash
 
-    sudo mkdir -p /opt/virtualenvs && sudo chown $USER /opt/virtualenvs/ && cd /opt/virtualenvs
-    virtualenv --no-site-packages /opt/virtualenvs/citovenv
-    source /opt/virtualenvs/citovenv/bin/activate
-    pip install -q --upgrade setuptools
-    pip install -r /opt/cito/requirements.txt
+    # Install mysql server
+    sudo apt-get install mysql-server mysql-client
 
+    # Setup mysql root password
+    sudo dpkg-reconfigure mysql-server-5.5
 
-**Edit default settings:**  ``/opt/cito/cito/settings/production.py``
+    # Create a new database 'citoengine'
+    sudo mysqladmin -uroot -p create citoengine
+    # Create a new mysql user
+    /usr/bin/mysql -uroot -p -e "GRANT ALL PRIVILEGES ON citoengine.* TO 'citoengine_user'@'localhost' IDENTIFIED BY 'MINISTRYOFSILLYWALKS' with GRANT OPTION"
 
-**Message Queue Configuration:**
 
-CitoEngine can be run on Amazon Web Services (AWS) cloud or onpremise.  
+**Setting up RabbitMQ (Optional):**
 
-If you are running CitoEngine on AWS, use AWS:SQS or if running onpremise, setup RabbitMQ as your message queue. Edit either of these configuration blocks and make sure
-you select ``QUEUE_TYPE`` to be either ``SQS`` or ``RABBITMQ``
+If you are planning to use RabbitMQ, the following three lines should get you started.
 
-.. code-block:: python
+.. code-block:: bash
 
-    ##################################
-    # AWS::SQS Configuration settings
-    ##################################
-    AWS_CONF = dict()
-    AWS_CONF['region'] = 'us-east-1'
-    AWS_CONF['awskey'] = ''
-    AWS_CONF['awssecret'] = ''
-    AWS_CONF['sqsqueue'] = 'citoq'
+    sudo rabbitmqctl add_user citoengine_user citoengine_pass
+    sudo rabbitmqctl add_vhost /citoengine_event_listener
+    sudo rabbitmqctl set_permissions -p /citoengine_event_listener citoengine_user ".*" ".*" ".*"
 
 
-    ##################################
-    # RabbitMQ Configuration settings
-    ##################################
-    RABBITMQ_CONF = dict()
-    RABBITMQ_CONF['host'] = 'localhost'
-    RABBITMQ_CONF['port'] = 5672
-    RABBITMQ_CONF['username'] = 'cito_user'
-    RABBITMQ_CONF['password'] = 'CHANGEME!'
-    RABBITMQ_CONF['ssl'] = False
-    RABBITMQ_CONF['exchange'] = ''
-    RABBITMQ_CONF['vhost'] = '/cito_event_listener'
-    RABBITMQ_CONF['queue'] = 'cito_commonq'
 
-    ##############################
-    # Queue type: SQS or RABBITMQ
-    ##############################
-    QUEUE_TYPE = 'RABBITMQ'
+**Edit default settings:**  Copy the sample ``/opt/citoengine/conf/citoengine.conf-example`` to ``/opt/citoengine/conf/citoengine.conf``
+and edit it accordingly.
 
-.. note:: Avoid editing ``/opt/cito/cito/settings/base.py`` unless you know what you are doing.
 
-**Setting up RabbitMQ (Optional):**
+**Message Queue Configuration:**
 
-If you are planning to use RabbitMQ, the following three lines should get you started.
+Edit the ``DATABASE`` configuration settings and change the settings. If you are running CitoEngine on AWS,
+use AWS:SQS or if running onpremise, setup RabbitMQ as your message queue. Edit either of these configuration blocks and make sure you select ``QUEUE_TYPE`` to be either ``SQS`` or ``RABBITMQ``.
 
-.. code-block:: bash
 
-    sudo rabbitmqctl add_user cito_user cito_pass
-    sudo rabbitmqctl add_vhost /cito_event_listener
-    sudo rabbitmqctl set_permissions -p /cito_event_listener cito_user ".*" ".*" ".*"
-
-**Database Configuration:**
-
-.. code-block:: python
-
-    #Database config
-    DATABASES = {
-        'default': {
-            'ENGINE': 'django.db.backends.mysql',   # Add 'postgresql_psycopg2', 'mysql', 'sqlite3' or 'oracle'.
-            'NAME': 'cito',                         # Or path to database file if using sqlite3.
-            'USER': '',                             # Not used with sqlite3.
-            'PASSWORD': '',                         # Not used with sqlite3.
-            'HOST': '',                             # Set to empty string for localhost. Not used with sqlite3.
-            'PORT': '',                             # Set to empty string for default. Not used with sqlite3.
-            'OPTIONS': {
-                'init_command': 'SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED'
-            }
-        }
-    }
+.. note:: Amazon SQS does not support message sequencing i.e. it does not guarantee first in, first out for message delivery. See http://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/Welcome.html
+
 
 **Initializing the tables and creating an admin account.**
 
 .. code-block:: bash
 
-    cd /opt/cito
+    source /opt/citoengine/bin/activate
+    cd /opt/citoengine/app
 
     # Populate the database
-    python manage.py syncdb --noinput --migrate
+    python manage.py migrate
 
     # Update django secret (for csrf)
     # If you are using the webapp on multiple nodes behind a load balancer,
     # make sure th secret_key.py file is same on all nodes.
-    sudo sh -c '/opt/cito/bin/create-django-secret.py > /opt/cito/cito/settings/secret_key.py'
+    sudo sh -c '/opt/citoengine/bin/create-django-secret.py > /opt/citoengine/app/settings/secret_key.py'
 
     # Create your first CitoEngine superuser!
     python manage.py createsuperuser
@@ -151,31 +107,24 @@ If you are planning to use RabbitMQ, the following three lines should get you st
 Starting the services
 ---------------------
 
-CitoEngine is divided into three components, ``poller``, ``listener`` and ``webapp``. You will have to start services of all three components.
-You can either run the helper scripts in the ``/opt/cito/bin`` directory, or you can run the using ``manage.py <command>``
+CitoEngine is divided into two components, ``webapp`` and ``poller``. You can run these two components using the helper
+scripts ``/opt/citoengine/bin/citoengine-poller.sh`` and ``/opt/citoengine/bin/citoengine-webapp.sh``. If you are on Ubuntu,
+you can configure to run them as upstart services using ``/opt/citoengine/bin/upstart/configure-upstart.sh``.
 
 
 **Start CitoEngine SQS Poller service**
 
 .. code-block:: bash
 
-    /opt/cito/bin/cito-poller.sh
-
-**Start CitoEngine Event Listener service**
-
-.. code-block:: bash
-
-    /opt/cito/bin/cito-listener.sh
+    /opt/citoengine/bin/citoengine-poller.sh
 
 
-**Start CitoEngine Webapp**
+**Start CitoEngine Engine**
 
-We would recommended that you execute above commands with lower privileges. Have a look at ``bin/cito-webapp.sh``
-for more information.
 
 .. code-block:: bash
 
-    /opt/cito/bin/cito-webapp.sh
+    /opt/citoengine/bin/citoengine-webapp.sh
 
 
 Open your browser and access http://<hostname or IP>:8000 to login to CitoEngine with the admin account you created earlier.
diff --git a/source/integrations.rst b/source/integrations.rst
@@ -83,5 +83,5 @@ Save this locally and have a quick look at it to confirm everything is in order.
 LDAP Authentication
 -------------------
 
-To enable LDAP authentication, simply uncomment the lines in file ``cito/settings/ldap_auth.py``. This file contains the sample LDAP bindings for
+To enable LDAP authentication, simply uncomment the lines in file ``app/settings/ldap_auth.py``. This file contains the sample LDAP bindings for
 Active Directory. You can modify the bindings based on your LDAP settings.
diff --git a/source/overview.rst b/source/overview.rst
@@ -36,7 +36,7 @@ Now that you know what CitoEngine is, we will walk you through how you can use i
 CitoEngine is built on open source technologies and designed to run on Linux. It's built on the following components
 
 * Python 2.7+ 
-* Django 1.6.x / Twisted / other dependencies
+* Django 1.8+
 * MariaDB / MySQL 5.5.x (PostgreSQL support coming soon)
 * RabbitMQ and AWS SQS (for queue)
 
@@ -54,7 +54,7 @@ Architecture
 The entire system is divided in two groups: ``event_listener``, ``queue``, ``poller`` and ``engine`` fall in the CitoEngine group whereas
 ``plugin_server`` is a standalone service called CitoPluginServer.
 
-All alerts enter the system via the ``event_listener`` and are sent over to the ``queue``. A ``poller`` reading this
+All alerts enter the system via the ``event_listener`` api call and are sent over to the ``queue``. A ``poller`` reading this
 ``queue`` fetches these events and begins to parse them. If a given event matches a definition in the system, it is accepted as
 an *Incident*. Each *Event* has one or more user-defined *EventActions*. The ``engine`` checks the threshold in real-time and
 fires the *EventAction*. Thresholds, at the moment, are limited to a conditional match of ``X events in Y seconds``.
@@ -112,3 +112,9 @@ parameters to the remote plugin. CitoEngine comes with a few internal variables
  * ``__EVENTID__`` Engine send the ``event`` ID
  * ``__INCIDENTID__`` Engine send the ``incident`` ID
  * ``__MESSAGE__`` Engine send the ``message`` which came in by the alerting system.
+
+
+.. _suppression:
+
+**Suppression**: CitoEngine allows you to suppress an *event*, an *element* or a combination of both. By suppressing an
+event and/or element, there will not be any eventaction taken against incidents against them.
diff --git a/source/releasenotes.rst b/source/releasenotes.rst
@@ -1,6 +1,29 @@
 Release Notes
 =============
 
+1.0.0
+-----
+
+*Release date 21 Jun 2015*
+
+**New Features**
+
+* event suppression
+
+* better application layout and installation script
+
+* integration of listener within the engine
+
+* use gevent for asynchronous processing of incidents
+
+* supports Django 1.8 (with new migrations)
+
+
+**Bugfixes**
+
+many..
+
+
 0.11.0
 ------