Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: restructure installation documentation #2113

Merged
1 commit merged into from
Sep 21, 2021
Merged

DOC: restructure installation documentation #2113

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Open in desktop
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#2113 by Sebastian Wagner).

### Packaging

Expand Down
2 changes: 2 additions & 0 deletions docs/user/configuration-management.rst
View file
Open in desktop
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
Open in desktop
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>`).