From 17ad9de738f31f14c7951dc77ecf1a3efb206975 Mon Sep 17 00:00:00 2001 From: "Thibault \"bui\" Koechlin" Date: Fri, 12 Mar 2021 11:16:17 +0100 Subject: [PATCH] up installation documentation (#678) * up installation documentation --- docker/README.md | 18 --- docs/v1.X/docs/docker/README.md | 129 ------------------ .../v1.X/docs/getting_started/installation.md | 89 +++++++++++- docs/v1.X/mkdocs.yml | 1 - 4 files changed, 87 insertions(+), 150 deletions(-) delete mode 100644 docs/v1.X/docs/docker/README.md diff --git a/docker/README.md b/docker/README.md index 651c76901..3730a6e7e 100644 --- a/docker/README.md +++ b/docker/README.md @@ -6,24 +6,6 @@ Crowdsec - An open-source, lightweight agent to detect and respond to bad behavi Before starting using docker image, we suggest you to read our documentation to understand all [crowdsec concepts](https://docs.crowdsec.net/). -### Prerequisities - - -In order to run this container you'll need docker installed. - -* [Windows](https://docs.docker.com/windows/started) -* [OS X](https://docs.docker.com/mac/started/) -* [Linux](https://docs.docker.com/linux/started/) - -### How to use ? - -#### Build - -```shell -git clone https://github.com/crowdsecurity/crowdsec.git && cd crowdsec -docker build -t crowdsec . -``` - #### Run The container is built with specific docker [configuration](https://github.com/crowdsecurity/crowdsec/blob/master/docker/config.yaml) : diff --git a/docs/v1.X/docs/docker/README.md b/docs/v1.X/docs/docker/README.md deleted file mode 100644 index 651c76901..000000000 --- a/docs/v1.X/docs/docker/README.md +++ /dev/null @@ -1,129 +0,0 @@ -# Crowdsec - -Crowdsec - An open-source, lightweight agent to detect and respond to bad behaviours. It also automatically benefits from our global community-wide IP reputation database. - -## Getting Started - -Before starting using docker image, we suggest you to read our documentation to understand all [crowdsec concepts](https://docs.crowdsec.net/). - -### Prerequisities - - -In order to run this container you'll need docker installed. - -* [Windows](https://docs.docker.com/windows/started) -* [OS X](https://docs.docker.com/mac/started/) -* [Linux](https://docs.docker.com/linux/started/) - -### How to use ? - -#### Build - -```shell -git clone https://github.com/crowdsecurity/crowdsec.git && cd crowdsec -docker build -t crowdsec . -``` - -#### Run - -The container is built with specific docker [configuration](https://github.com/crowdsecurity/crowdsec/blob/master/docker/config.yaml) : - -You should apply following configuration before starting it : - -* Specify collections|scenarios|parsers/postoverflows to install via the environment variables (by default [`crowdsecurity/linux`](https://hub.crowdsec.net/author/crowdsecurity/collections/linux) is installed) -* Mount volumes to specify your log files that should be ingested by crowdsec (set up in acquis.yaml) -* Mount other volumes : if you want to share the database for example - -```shell -docker run -d -v acquis.yaml:/etc/crowdsec/acquis.yaml \ - -e COLLECTIONS="crowdsecurity/sshd" - -v /var/log/auth.log:/var/log/auth.log \ - -v /path/mycustom.log:/var/log/mycustom.log \ - --name crowdsec crowdsecurity/crowdsec -``` - -#### Example - -I have my own configuration : -```shell -user@cs ~/crowdsec/config $ ls -acquis.yaml config.yaml -``` - -Here is my acquis.yaml file: -```shell -filenames: - - /logs/auth.log - - /logs/syslog -labels: - type: syslog ---- -filename: /logs/apache2/*.log -labels: - type: apache2 -``` - -So, I want to run crowdsec with : - -* My configuration files -* Ingested my path logs specified in acquis.yaml -* Share the crowdsec sqlite database with my host (You need to create empty file first, otherwise docker will create a directory instead of simple file) -* Expose local API through host (listen by default on `8080`) -* Expose prometheus handler through host (listen by default on `6060`) - -```shell -touch /path/myDatabase.db -docker run -d -v config.yaml:/etc/crowdsec/config.yaml \ - -v acquis.yaml:/etc/crowdsec/acquis.yaml \ - -v /var/log/auth.log:/logs/auth.log \ - -v /var/log/syslog.log:/logs/syslog.log \ - -v /var/log/apache:/logs/apache \ - -v /path/myDatabase.db:/var/lib/crowdsec/data/crowdsec.db \ - -e COLLECTIONS="crowdsecurity/apache2 crowdsecurity/sshd" \ - -p 8080:8080 -p 6060:6060 \ - --name crowdsec crowdsecurity/crowdsec -``` - -If you want to be able to restart/stop your container and keep the same DB `-v /path/myDatabase.db:/var/lib/crowdsec/data/crowdsec.db` you need to add a volume on local_api_credentials.yaml `-v /path/local_api_credentials.yaml:/etc/crowdsec/local_api_credentials.yaml`. - -### Environment Variables - -* `COLLECTIONS` - Collections to install from the [hub](https://hub.crowdsec.net/browse/#collections), separated by space : `-e COLLECTIONS="crowdsecurity/linux crowdsecurity/apache2"` -* `SCENARIOS` - Scenarios to install from the [hub](https://hub.crowdsec.net/browse/#configurations), separated by space : `-e SCENARIOS="crowdsecurity/http-bad-user-agent crowdsecurity/http-xss-probing"` -* `PARSERS` - Parsers to install from the [hub](https://hub.crowdsec.net/browse/#configurations), separated by space : `-e PARSERS="crowdsecurity/http-logs crowdsecurity/modsecurity"` -* `POSTOVERFLOWS` - Postoverflows to install from the [hub](https://hub.crowdsec.net/browse/#configurations), separated by space : `-e POSTOVERFLOWS="crowdsecurity/cdn-whitelist"` -* `CONFIG_FILE` - Configuration file (default: `/etc/crowdsec/config.yaml`) : `-e CONFIG_FILE=""` -* `FILE_PATH` - Process a single file in time-machine : `-e FILE_PATH=""` -* `JOURNALCTL_FILTER` - Process a single journalctl output in time-machine : `-e JOURNALCTL_FILTER=""` -* `TYPE` - [`Labels.type`](https://https://docs.crowdsec.net/Crowdsec/v1/references/acquisition/) for file in time-machine : `-e TYPE=""` -* `TEST_MODE` - Only test configs (default: `false`) : `-e TEST_MODE=""` -* `DISABLE_AGENT` - Only test configs (default: `false`) : `-e DISABLE_AGENT=""` -* `DISABLE_LOCAL_API` - Disable local API (default: `false`) : `-e DISABLE_API=""` -* `DISABLE_ONLINE_API` - Disable Online API registration for signal sharing (default: `false`) : `-e DISABLE_ONLINE_API=""` -* `LEVEL_TRACE` - Trace-level (VERY verbose) on stdout (default: `false`) : `-e LEVEL_TRACE=""` -* `LEVEL_DEBUG` - Debug-level on stdout (default: `false`) : `-e LEVEL_DEBUG=""` -* `LEVEL_INFO` - Info-level on stdout (default: `false`) : `-e LEVEL_INFO=""` - -### Volumes - -* `/var/lib/crowdsec/data/` - Directory where all crowdsec data (Databases) is located - -* `/etc/crowdsec/` - Directory where all crowdsec configurations are located - -#### Useful File Locations - -* `/usr/local/bin/crowdsec` - Crowdsec binary - -* `/usr/local/bin/cscli` - Crowdsec CLI binary to interact with crowdsec - -## Find Us - -* [GitHub](https://github.com/crowdsecurity/crowdsec) - -## Contributing - -Please read [contributing](https://docs.crowdsec.net/Crowdsec/v1/contributing/) for details on our code of conduct, and the process for submitting pull requests to us. - -## License - -This project is licensed under the MIT License - see the [LICENSE](https://github.com/crowdsecurity/crowdsec/blob/master/LICENSE) file for details. \ No newline at end of file diff --git a/docs/v1.X/docs/getting_started/installation.md b/docs/v1.X/docs/getting_started/installation.md index 133f3083e..49bc4e2da 100644 --- a/docs/v1.X/docs/getting_started/installation.md +++ b/docs/v1.X/docs/getting_started/installation.md @@ -1,4 +1,80 @@ -# Installation + +# Installation methods + +You can install crowdsec in different ways : + + - Most users [set up crowdsec's repositories](/Crowdsec/v1/getting_started/installation/#install-using-crowdsec-repository) and install from them, for ease of installation and upgrade + - Some users [use debian's official crowdsec packages](/Crowdsec/v1/getting_started/installation/#install-using-debian-official-packages) + - Some users download the DEB package directly and [install it manually](/Crowdsec/v1/getting_started/installation/#manually-install-the-debian-package) + - Some users download the tarball directly and [install it manually](/Crowdsec/v1/getting_started/installation/#install-from-release-tarball) + - Some users use the [docker hub image](https://hub.docker.com/r/crowdsecurity/crowdsec) + - And the most adventurous might want to [build & install from source](/Crowdsec/v1/getting_started/installation/#install-from-source) + - And some might even want to [build their own docker image](/Crowdsec/v1/getting_started/installation/#build-docker-image) + - Or use it with [docker-compose](https://github.com/crowdsecurity/example-docker-compose) + + +!!! info + Packaging for FreeBSD and RedHat/CentOS are WIP at the time of writing. Documentation will be updated once those packages are published & functional. + +# Install using crowdsec repository + +Crowdsec distributes their own pragmatic debian packages that closely follow the development stream (packages are automatically published on release), and are suitable for those that want to keep up with the latest changes of crowdsec. + +## setup the repository + +
+ pre-requisites to add custom repositories on debian +```bash +sudo apt install software-properties-common +``` +
+ +```bash +wget -qO - https://s3-eu-west-1.amazonaws.com/crowdsec.debian.pragmatic/crowdsec.asc |sudo apt-key add - && sudo apt-add-repository "https://s3-eu-west-1.amazonaws.com/crowdsec.debian.pragmatic/$(lsb_release -cs) $(lsb_release -cs) main" +sudo apt-get update +``` + +The following debian suites / architectures are available : + +## install crowdsec + +```bash +sudo apt-get install crowdsec +``` + +## compatibility matrix + +
+ +| Suite | Architecture | +| :------------- | :----------: | +| bionic | amd64, arm64, i386 | +| bullseye | amd64, i386 | +| buster | amd64, arm64, i386 | +| focal | amd64, arm64, i386 | +| sid | amd64, i386 | +| stretch | amd64, arm64, i386 | +| xenial | amd64, arm64, i386 | + +
+ +# Manually install the debian package + +Fetch your package from the [public repository](https://s3-eu-west-1.amazonaws.com/crowdsec.debian.pragmatic/), and install it manually : + +```bash +sudo dpkg -i ./crowdsec_1.0.7-4_amd64.deb +``` + +# Install using debian official packages + +Crowdsec is available for [bullseye & sid](https://packages.debian.org/search?searchon=names&keywords=crowdsec) and can be installed simply : + +```bash +sudo apt-get install crowdsec +``` + +# Install from the release tarball Fetch {{v1X.crowdsec.name}}'s latest version [here]({{v1X.crowdsec.download_url}}). @@ -60,7 +136,7 @@ If your setup is standard and you've walked through the default installation wit This mode will emulate the interactive mode of the wizard where you answer **yes** to everything and stick with the default options. -## From source +# Install from source !!! warning "Requirements" @@ -79,3 +155,12 @@ make release This will create you a directory (`crowdsec-vXXX/`) and an archive (`crowdsec-release.tgz`) that are release built from your local code source. Now, you can install either with [interactive wizard](#using-the-interactive-wizard) or the [unattended mode](#using-unattended-mode). + +# Build docker image + +Crowdsec provides a docker image and can simply built like this : + +```bash +git clone https://github.com/crowdsecurity/crowdsec.git && cd crowdsec +docker build -t crowdsec . +``` diff --git a/docs/v1.X/mkdocs.yml b/docs/v1.X/mkdocs.yml index fc0be5670..0b0ef58b3 100644 --- a/docs/v1.X/mkdocs.yml +++ b/docs/v1.X/mkdocs.yml @@ -21,7 +21,6 @@ nav: - Simulation Management: user_guide/simulation_mode.md - Crowdsec forensic mode: user_guide/forensic_mode.md - Debugging: user_guide/debugging_configs.md - - Docker: docker/README.md - CLI: - Cscli: cscli/cscli.md - Alerts: cscli/cscli_alerts.md