diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 12:36:04 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-28 12:36:04 +0000 |
commit | b09c6d56832eb1718c07d74abf3bc6ae3fe4e030 (patch) | |
tree | d2caec2610d4ea887803ec9e9c3cd77136c448ba /doc/06-Migration.md | |
parent | Initial commit. (diff) | |
download | icingadb-b09c6d56832eb1718c07d74abf3bc6ae3fe4e030.tar.xz icingadb-b09c6d56832eb1718c07d74abf3bc6ae3fe4e030.zip |
Adding upstream version 1.1.0.upstream/1.1.0upstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'doc/06-Migration.md')
-rw-r--r-- | doc/06-Migration.md | 102 |
1 files changed, 102 insertions, 0 deletions
diff --git a/doc/06-Migration.md b/doc/06-Migration.md new file mode 100644 index 0000000..5a87e41 --- /dev/null +++ b/doc/06-Migration.md @@ -0,0 +1,102 @@ +# Migration from IDO + +Migrating from the IDO feature to Icinga DB starts by setting up Icinga DB. To +do so, please follow the [installation instructions]. The Icinga DB feature can +be enabled in parallel to the IDO, allowing you to perform the migration while +the IDO is still running. + +After setting up Icinga DB, all Icinga objects and their current state should +already show up in Icinga DB Web as this information is synced from Icinga 2. +At this point, the old host and service history is missing in Icinga DB. If it +is desired to keep it, this information has to be migrated explicitly from the +old IDO database. To do so, follow the instructions below. + +## History + +To migrate history data from the [IDO] database, the Icinga DB Migration +commandline tool is provided. If you have installed Icinga DB from our +packages, it is automatically installed as well. + +### Preparing the Configuration + +Please take the [example configuration] as a starting point and copy it to the +host you will perform the migration on. The following sections will guide you +through how to adjust it for your needs. + +#### Environment ID + +Icinga DB allows writing multiple Icinga environments to the same database. +Thus, you have to tell the migration tool for which environment you want to +migrate the history. On each Icinga 2 node that has the Icinga DB feature +enabled, the environment ID is written to the file +`/var/lib/icinga2/icingadb.env`. Please use the contents of this file for the +`env` option in the section `icinga2`. + +#### Database Connection + +The migration tool needs to access both the IDO and the Icinga DB databases. +Please specify the connection details in the corresponding `ido` and `icingadb` +sections of the configuration. + +Both the IDO and Icinga DB support MySQL and PostgreSQL. You can migrate from +and to both types, including from one type to the other. + +#### Input Time Range + +The migration tool allows you to restrict the time range of the history events +to be migrated. This is controlled by the options `from` and `to` in the `ido` +section of the configuration. Both options can be set to Unix timestamps. + +It is recommended to set the `to` option to a cutoff time at which the history +in the Icinga DB database switches from migrated events to events written +directly by Icinga DB. If you kept running the IDO in parallel to Icinga DB and +do not do this, there will be duplicate events for the time both were running. + +You can query the time of the first history event written by Icinga DB by +running this query in its database: + +``` +SELECT MIN(event_time)/1000 FROM history; +``` + +In case you had trouble setting up Icinga DB or this is not the first time you +are setting up Icinga DB, please make sure to double-check this timestamp and +adjust it accordingly if it is not what you expect. + +!!! tip + + You can convert between Unix timestamps and a human-readable format using the `date` command: + + * Unix timestamp to readable date: `date -d @1667219820` + * Current date/time to Unix timestamp: `date +%s` + * Specific date/time to Unix timestamp: `date -d '2022-01-01 00:00:00' +%s` + * Relative date/time to Unix timestamp: `date -d '-1 year' +%s` + +Similarly, you can use `from` to limit how much old history gets migrated. + +### Cache Directory + +Choose a (not necessarily yet existing) directory for Icinga DB Migration's +internal cache. If either there isn't much to migrate or the migration +process won't be interrupted by a reboot (of the machine +Icinga DB migration/database runs on), `mktemp -d` is enough. + +### Run the Migration + +To start the actual migration, execute the following command: + +```shell +icingadb-migrate -c icingadb-migration.yml -t ~/icingadb-migration.cache +``` + +In case this command was interrupted, you can run it again. It will continue +where it left off and reuse the cache if it is still present. + +!!! tip + + If there is much to migrate, use e.g. tmux to + protect yourself against SSH connection losses. + +[installation instructions]: 02-Installation.md +[IDO]: https://icinga.com/docs/icinga-2/latest/doc/14-features/#ido-database-db-ido +[example configuration]: icingadb-migration.example.yml |