Skip to content

Commit

Permalink
DOC: restructure installation documentation
Browse files Browse the repository at this point in the history 
motivated by
https://geekypandatales.wordpress.com/2021/07/22/automating-ioc-gathering-and-processing-with-intel-mq/
  • Loading branch information
Sebastian Wagner committed Sep 20, 2021
1 parent f8f4ede commit 6e0dbd2
Show file tree
Hide file tree
Showing 3 changed files with 92 additions and 119 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ CHANGELOG

### Documentation
- Feeds: Add documentation for newly supported dataplane feeds, see above (PR#2102 by Mikk Margus Möll).
- Installation: Restructured the whole document to make it clearer and straight-forward (PR#2023 by Sebastian Wagner).

### Packaging

Expand Down
2 changes: 2 additions & 0 deletions docs/user/configuration-management.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,6 +36,8 @@ You need to enable and start Redis if not already done. Using systemd it can be
Configuration
*************

.. _configuration-paths:

/opt and LSB paths
==================

Expand Down
208 changes: 89 additions & 119 deletions docs/user/installation.rst
View file
Original file line number Diff line number Diff line change
@@ -1,189 +1,164 @@
..
SPDX-FileCopyrightText: 2017 Sebastian Wagner
SPDX-FileCopyrightText: 2017-2021 Sebastian Wagner
SPDX-License-Identifier: AGPL-3.0-or-later
Installation
============

.. contents::

Please report any errors you encounter at https://github.com/certtools/intelmq/issues
Please report any errors an suggest improvements at `IntelMQ Issues <https://github.com/certtools/intelmq/issues>`_. Thanks!

For upgrade instructions, see :doc:`upgrade`.
For setting up a development environment see the :doc:`../dev/guide` section *Development Environment*.
For testing pre-releases see also the :doc:`../dev/guide` section *Testing Pre-releases*.
For testing pre-releases see also :ref:`testing`.

Following any one of the installation methods will setup the IntelMQ base.
Some bots may have additional special dependencies which are mentioned in their :doc:`own documentation <bots>`.

The following installation methods are available:

* native `.deb`/`.rpm` packages
* Docker, with and without docker-compose
* Python package from PyPI
* From the git-repository, see :ref:`development environment`

Requirements
------------

Base Requirements
-----------------

The following instructions assume the following requirements. Python versions >= 3.6 are supported.

Supported and recommended operating systems are:

* CentOS 7 and 8
* Debian 10 Buster and 11 Bullseye
* openSUSE Leap 15.2, 15.13
* openSUSE Leap 15.2, 15.13 and Tumbleweed
* Ubuntu: 18.04, 20.04
* Docker Engine: 18.x and higher
* For the Docker-installation: Docker Engine: 18.x and higher

Other distributions which are (most probably) supported include RHEL, Fedora, openSUSE Tumbleweed and FreeBSD 12.
Other distributions which are (most probably) supported include RHEL, Fedora and FreeBSD 12.

A short guide on hardware requirements can be found on the page :doc:`hardware-requirements`.

Install Dependencies
--------------------

**If you are using native packages, you skip this section as all dependencies are installed automatically.**

Ubuntu / Debian
^^^^^^^^^^^^^^^
Native deb/rpm packages
-----------------------

.. code-block:: bash
These are the operating systems which are currently supported by packages:

apt install python3-pip python3-dnspython python3-psutil python3-redis python3-requests python3-termstyle python3-tz python3-dateutil
apt install redis-server
* **CentOS 7** (run ``yum install epel-release`` first)
* **CentOS 8** (run ``dnf install epel-release`` first)
* **Debian 10** Buster
* **Debian 11** Bullseye
* **Fedora 33**
* **Fedora 34**
* **openSUSE Leap 15.2**
* **openSUSE Leap 15.3** (make sure the ``openSUSE:Backports:SLE-15-SP3`` repository is enabled)
* **openSUSE Tumbleweed**
* **Ubuntu 18.04** Bionic Beaver (enable the universe repositories by appending ``universe`` in ``/etc/apt/sources.list`` to ``deb http://[...].archive.ubuntu.com/ubuntu/ bionic main`` first)
* **Ubuntu 20.04** Focal Fossa (enable the universe repositories by appending ``universe`` in ``/etc/apt/sources.list`` to ``deb http://[...].archive.ubuntu.com/ubuntu/ focal main`` first)

Optional dependencies:
Get the installation instructions for your operating system here: `Installation Native Packages <https://software.opensuse.org/download.html?project=home:sebix:intelmq&package=intelmq>`_.
The instructions show how to add the repository and install the `intelmq` package. You can also install the `intelmq-manager` package to get the `Web-Frontend IntelMQ Manager <https://github.com/certtools/intelmq-manager/>`_.

.. code-block:: bash

apt install bash-completion jq
apt install python3-pymongo python3-psycopg2
Docker
------

CentOS 7 / RHEL 7
^^^^^^^^^^^^^^^^^
Attention: Currently you can't manage your botnet via :doc:`intelmqctl`. You need to use `IntelMQ-Manager <https://github.com/certtools/intelmq-manager>`_ currently!

.. code-block:: bash
The latest IntelMQ image is hosted on `Docker Hub <https://hub.docker.com/r/certat/intelmq-full>`_ and the image build instructions are in our `intelmq-docker repository <https://github.com/certat/intelmq-docker>`.

yum install epel-release
yum install python36 python36-devel python36-requests
yum install gcc gcc-c++
yum install redis
Follow `Docker Install <https://docs.docker.com/engine/install/>`_ and
`Docker-Compose Install <https://docs.docker.com/compose/install/>`_ instructions.

CentOS 8
^^^^^^^^
Before you start using docker-compose or any docker related tools, make sure docker is running:

.. code-block:: bash
dnf install epel-release
dnf install python3-dateutil python3-dns python3-pip python3-psutil python3-pytz python3-redis python3-requests redis
# To start the docker daemon
systemctl start docker.service
# To enable the docker daemon for the future
systemctl enable docker.service
Optional dependencies:
Now we can download IntelMQ and start the containers.
Navigate to your preferred installation directory and run the following commands:

.. code-block:: bash
dnf install bash-completion jq
dnf install python3-psycopg2 python3-pymongo
openSUSE 15.2 / 15.3
^^^^^^^^^^^^^^^^^^^^
git clone https://github.com/certat/intelmq-docker.git --recursive
cd intelmq-docker
sudo docker-compose pull
sudo docker-compose up
.. code-block:: bash
Your installation should be successful now. You're now able to visit ``http://127.0.0.1:1337/`` to access the intelmq-manager.
You have to login with the username ``intelmq`` and the password ``intelmq``, if you want to change the username or password,
you can do this by adding the environment variables ``INTELMQ_API_USER`` for the username and ``INTELMQ_API_PASS`` for the
password.

zypper install python3-dateutil python3-dnspython python3-psutil python3-pytz python3-redis python3-requests python3-python-termstyle
zypper install redis
NOTE: If you get an `Permission denied`, you should use ``chown -R $USER:$USER example_config``.

Optional dependencies:

.. code-block:: bash
With pip from PyPI
------------------

zypper in bash-completion jq
zypper in python3-psycopg2 python3-pymongo
Requirements
^^^^^^^^^^^^

Docker (beta)
^^^^^^^^^^^^^
Ubuntu / Debian

**ATTENTION** Currently you can't manage your botnet via :doc:`intelmqctl`. You need to use `IntelMQ-Manager <https://github.com/certtools/intelmq-manager>`_ currently!
.. code-block:: bash
Follow `Docker Install <https://docs.docker.com/engine/install/>`_ and
`Docker-Compose Install <https://docs.docker.com/compose/install/>`_ instructions.
apt install python3-pip python3-dnspython python3-psutil python3-redis python3-requests python3-termstyle python3-tz python3-dateutil redis-server bash-completion jq
# optional dependencies
apt install python3-pymongo python3-psycopg2
The latest image is hosted on `Docker Hub <https://hub.docker.com/r/certat/intelmq-full>`_
CentOS 7 / RHEL 7:

Installation
------------
.. code-block:: bash
Installation methods available:
yum install epel-release
yum install python36 python36-dns python36-pytz python36-requests python3-setuptools redis bash-completion jq
yum install gcc gcc-c++ python36-devel
# optional dependencies
yum install python3-psycopg2
* native packages (`.deb`, `.rpm`)
* PyPi (latest releases as python package)
CentOS 8:

**Note:** installation for development purposes must follow the instructions available on :ref:`development environment`.
.. code-block:: bash
Native Packages
^^^^^^^^^^^^^^^
dnf install epel-release
dnf install python3-dateutil python3-dns python3-pip python3-psutil python3-pytz python3-redis python3-requests redis bash-completion jq
# optional dependencies
dnf install python3-psycopg2 python3-pymongo
These are the operating systems which are currently supported by packages:
openSUSE:

* **CentOS 7** (run `yum install epel-release` first)
* **CentOS 8** (run `dnf install epel-release` first)
* **Debian 10** Buster
* **Debian 11** Bullseye
* **Fedora 33**
* **Fedora 34**
* **openSUSE Leap 15.2**
* **openSUSE Leap 15.3** (make sure the ``openSUSE:Backports:SLE-15-SP3`` repository is enabled)
* **openSUSE Tumbleweed**
* **Ubuntu 18.04** (enable the universe repositories by appending `universe` in `/etc/apt/sources.list` to `deb http://[...].archive.ubuntu.com/ubuntu/ bionic main` first)
* **Ubuntu 20.04** (enable the universe repositories by appending `universe` in `/etc/apt/sources.list` to `deb http://[...].archive.ubuntu.com/ubuntu/ focal main` first)
.. code-block:: bash
Get the installation instructions for your operating system here: `Installation Native Packages <https://software.opensuse.org/download.html?project=home:sebix:intelmq&package=intelmq>`_.
The instructions show how to add the repository and install the `intelmq` package. You can also install the `intelmq-manager` package to get the `Web-Frontend IntelMQ Manager <https://github.com/certtools/intelmq-manager/>`_.
zypper install python3-dateutil python3-dnspython python3-psutil python3-pytz python3-redis python3-requests python3-python-termstyle redis bash-completion jq
# optional dependencies
zypper in python3-psycopg2 python3-pymongo
Please report any errors or improvements at `IntelMQ Issues <https://github.com/certtools/intelmq/issues>`_. Thanks!
Installation
^^^^^^^^^^^^

PyPi
^^^^
The base directory is ``/opt/intelmq/``, if the environment variable ``INTELMQ_ROOT_DIR`` is not set to something else, see :ref:`configuration-paths` for more information.

.. code-block:: bash
sudo -i
pip3 install intelmq
useradd -d /opt/intelmq -U -s /bin/bash intelmq
sudo intelmqsetup
`intelmqsetup` will create all necessary directories, provides a default configuration for new setups. See the :ref:`configuration` for more information on them and how to influence them.

Docker **with** docker-compose (recommended)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Navigate to your preferred installation directory and run the following commands.

**NOTE** If not already installed, please install `Docker <https://docs.docker.com/get-docker/>`_

Before you start using docker-compose or any docker related tools, make sure docker is running

.. code-block:: bash
# To start the docker daemon
systemctl start docker.service
# To enable the docker daemon for the future
systemctl enable docker.service
.. code-block:: bash
git clone https://github.com/certat/intelmq-docker.git --recursive
cd intelmq-docker
sudo docker-compose pull
sudo docker-compose up
Your installation should be successful now. You're now able to visit ``http://127.0.0.1:1337/`` to access the intelmq-manager.
You have to login with the username ``intelmq`` and the password ``intelmq``, if you want to change the username or password,
you can do this by adding the environment variables ``INTELMQ_API_USER`` for the username and ``INTELMQ_API_PASS`` for the
password.

NOTE: If you get an `Permission denied`, you should use `chown -R $USER:$USER example_config`

Docker without docker-compose
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------

**NOTE** If not already installed, please install `Docker <https://docs.docker.com/get-docker/>`_
If not already installed, please install `Docker <https://docs.docker.com/get-docker/>`_.

Navigate to your preferred installation directory and run ``git clone https://github.com/certat/intelmq-docker.git --recursive``.

Expand Down Expand Up @@ -236,8 +211,3 @@ If you want to use another username and password for the intelmq-manager / api l
-e INTELMQ_API_USER: "your username"
-e INTELMQ_API_PASS: "your password"
Additional Information
^^^^^^^^^^^^^^^^^^^^^^

Following any one of the installation methods mentioned before, will setup the IntelMQ base. However, some bots may have additional dependencies which are mentioned in their :doc:`own documentation <bots>`).

0 comments on commit 6e0dbd2

Please sign in to comment.