From 825f8f83b20189cc405ffef7007bac7d1e0d8551 Mon Sep 17 00:00:00 2001 From: "Thibault \"bui\" Koechlin" Date: Tue, 15 Dec 2020 17:02:24 +0100 Subject: [PATCH] up doc (#543) --- .github/release-drafter.yml | 6 +++- docs/v1.X/docs/getting_started/upgrades.md | 42 ++++++++++++++++++++++ docs/v1.X/docs/migration.md | 1 + docs/v1.X/mkdocs.yml | 1 + 4 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 docs/v1.X/docs/getting_started/upgrades.md diff --git a/.github/release-drafter.yml b/.github/release-drafter.yml index 5f662f0a8..2f1728749 100644 --- a/.github/release-drafter.yml +++ b/.github/release-drafter.yml @@ -24,4 +24,8 @@ template: | ## Geolite2 notice This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com. - \ No newline at end of file + + ## Upgrading installation + + Take a look at the [upgrade instructions](https://doc.crowdsec.net/Crowdsec/v1/getting_started/upgrades/) or [installation instructions](https://doc.crowdsec.net/Crowdsec/v1/getting_started/installation/). + diff --git a/docs/v1.X/docs/getting_started/upgrades.md b/docs/v1.X/docs/getting_started/upgrades.md new file mode 100644 index 000000000..2c6350e06 --- /dev/null +++ b/docs/v1.X/docs/getting_started/upgrades.md @@ -0,0 +1,42 @@ +# Upgrades + +The wizard is here to help the user in the process of upgrading an existing installation. +Various items need to be kept during the upgrade process: + + - scenarios/parsers/postoverflows : upstream scenarios need to be updated, while local/tainted ones need to be kept as-is + - most configurations must be kept as-is (`acquis.yaml` `*_credentials.yaml` `profiles.yaml` `simulation.yaml` `config.yaml`) + - database (especially if it's a SQLite file) + + +## Patch upgrade + +`wizard.sh --binupgrade` + +When doing a minor/patch upgrade (ie. `1.0.0` to `1.0.1`), the `--binupgrade` feature should be the more appropriate : It will simply upgrade the existing binaries, letting all configurations untouched. + +As any breaking change should lead to a version bump and appropriate warning, this is the safest option. + + +## Minor upgrade + + +`wizard.sh --upgrade` + +When doing a minor upgrade (ie. `1.0.4` to `1.1.0`), the `--upgrade` feature should be used : It will attempt to migrate and upgrade any existing configurations, include tainted/custom ones. The ambition is to be able to upgrade scenarios, parsers etc to the latest version when relevant, while keeping custom/tainted ones untouched. + + + +It's using `cscli config backup`, creating a directory (usually `/tmp/tmp.`) in which it's going to dump all relevant configurations before performing an upgrade : + + - configuration files : `acquis.yaml` `*_credentials.yaml` `profiles.yaml` `simulation.yaml` `config.yaml` + - one directory for **parsers**, **scenarios**, **postoverflows** and **collections**, where it's going to store both reference to upstream configurations, and your custom/tainted ones + +It is then going to cleanup crowdsec configuration, `/etc/crowdsec/` content (except bouncers configuration), before deploying the new binaries. Once this is done, configuration will be restored from our temp directory using `cscli config restore`. + + +## Major upgrade + +For major upgrades (ie. `0.3.X` to `1.0.X`), `wizard` won't do the trick, and you'll have to rely on documentation to do so : + + - Migrating from `0.3.X` to `1.0.X` : [documentation](Crowdsec/v1/migration/) + diff --git a/docs/v1.X/docs/migration.md b/docs/v1.X/docs/migration.md index 6b683b2c5..bde27eda0 100644 --- a/docs/v1.X/docs/migration.md +++ b/docs/v1.X/docs/migration.md @@ -27,6 +27,7 @@ Download latest V1 {{v1X.crowdsec.name}} version [here]({{v1X.crowdsec.download_ tar xvzf crowdsec-release.tgz cd crowdsec-v1*/ sudo ./wizard.sh --uninstall +sudo rm /etc/cron.d/crowdsec_pull sudo ./wizard.sh --bininstall ``` diff --git a/docs/v1.X/mkdocs.yml b/docs/v1.X/mkdocs.yml index 61ef2f034..ee316a7b4 100644 --- a/docs/v1.X/mkdocs.yml +++ b/docs/v1.X/mkdocs.yml @@ -5,6 +5,7 @@ nav: # - Glossary: getting_started/glossary.md - Concepts : getting_started/concepts.md - Install Crowdsec : getting_started/installation.md + - Upgrade Crowdsec: getting_started/upgrades.md - Crowdsec Tour: getting_started/crowdsec-tour.md - User guide: - CLI: user_guide/cscli.md