1<a id="Upgrading"></a>Upgrading 2=============================== 3 4Icinga Director is very upgrade-friendly. We never had any complaint referring 5data loss on upgrade. But to be on the safe side, please always [backup](#backup-first) 6your database before running an upgrade. 7 8Then drop the new version to your Icinga Web 2 module folder and you're all done. 9In case you make use of the [Job Runner](79-Jobs.md), you should restart it's 10service. Eventually refresh the page in your browser<sup>[[1]](#footnote1)</sup>, 11and you are ready to go. 12 13Should there any other actions be required (like [schema migrations](#schema-migrations)), 14you will be told so in your frontend. 15 16Please read more about: 17 18* [Database Backup](#backup-first) 19* [Upgrading to 1.6.x](#upgrade-to-1.6.x) 20* [Upgrading to 1.5.x](#upgrade-to-1.5.x) 21* [Upgrading to 1.4.x](#upgrade-to-1.4.x) 22* [Upgrading to 1.3.0](#upgrade-to-1.3.0) 23* [Upgrading to 1.2.0](#upgrade-to-1.2.0) 24* [Upgrading to 1.1.0](#upgrade-to-1.1.0) 25* [How to work with the latest GIT master](#git-master) 26* [Database schema upgrades](#schema-migrations) 27* [Job Runner restart](#restart-jobrunner) 28* [Downgrading](#downgrade) 29 30And last but not least, having a look at our [Changelog](82-Changelog.md) is 31usually a good idea before applying an upgrade. 32 33<a name="backup-first"></a>Always take a backup first 34----------------------------------------------------- 35 36All you need for backing up your Director is a snapshot of your database. Please 37use the tools provided by your database backend, like `mysqldump` or `pg_dump`. 38Restoring from a backup is trivial, and Director will always be able to apply 39pending database migrations to an imported old database snapshot. 40 41<a name="upgrade-to-1.6.x"></a>Upgrading to 1.6.x 42------------------------------------------------- 43 44There is nothing special to take care of. In case you are running 1.5.x or any 45GIT master since then, all you need is to replace the Director module folder 46with the new one. Or to run git checkout v1.6.0 in case you installed Director 47from GIT. 48 49As always, you'll then be prompted to apply pending Database Migrations. 50 51<a name="upgrade-to-1.5.x"></a>Upgrading to 1.5.x 52------------------------------------------------- 53 54There is nothing special to take care of. In case you are running 1.4.x or any 55GIT master since then, all you need is to replace the Director module folder 56with the new one. Or to run git checkout v1.5.0 in case you installed Director 57from GIT. 58 59As always, you'll then be prompted to apply pending Database Migrations. 60 61<a name="upgrade-to-1.4.x"></a>Upgrading to 1.4.x 62------------------------------------------------- 63 64Since v1.4.0 Icinga Director requires at least PHP 5.4. Apart from this, there 65is nothing special to take care of. In case you are running 1.3.x or any GIT 66master since then, all you need is to replace the Director module folder with 67the new one. Or to run `git checkout v1.4.x` in case you installed Director 68from GIT. 69 70<a name="upgrade-to-1.3.x"></a>Upgrading to 1.3.x 71------------------------------------------------- 72 73In case you are running 1.2.0 or any GIT master since then, all you need is to 74replace the Director module folder with the new one. Or to run `git checkout v1.3.x` 75in case you installed Director from GIT. 76 77When running Director since 1.1.0 or earlier on PostgreSQL, you might not yet 78have the PostgreSQL crypto extension installed (Package: `postgresql-contrib`) and 79enabled: 80 81 psql -q -c "CREATE EXTENSION pgcrypto;" 82 83 84<a name="upgrade-to-1.2.0"></a>Upgrading to 1.2.0 85------------------------------------------------- 86 87There is nothing special to take care of. In case you are running 1.1.0 or any 88GIT master since then, all you need is to replace the Director module folder with 89the new one. Or to run `git checkout v1.2.0` in case you installed Director from 90GIT. 91 92<a name="upgrade-to-1.1.0"></a>Upgrading to 1.1.0 93------------------------------------------------- 94 95There is nothing special to take care of. In case you are running 1.0.0 or any 96GIT master since then, all you need is to replace the Director module folder with 97the new one. Or to run `git checkout v1.1.0` in case you installed Director from 98GIT. 99 100<a name="git-master"></a>Work with the latest GIT master 101-------------------------------------------------------- 102 103Icinga Director is still a very young project. Lots of changes are going on, 104a lot of improvements, bug fixes and new features are still being added every 105month. People living on the bleeding edge might prefer to use all of them as 106soon as possible. 107 108So here is the good news: this is no problem at all. It's absolutely legal and 109encouraged to run Director as a pure GIT clone, installed as such: 110 111```sh 112ICINGAWEB_MODULES=/usr/share/icingaweb2/modules 113DIRECTOR_GIT=https://github.com/Icinga/icingaweb2-module-director.git 114git clone $DIRECTOR_GIT $ICINGAWEB_MODULES/director 115``` 116 117Don't worry about schema upgrades. Once they made it into our GIT master there 118will always be a clean upgrade path for you, no manual interaction should ever 119be required. Like every human being, we are not infallible. So, while our strict 120policy says that the master should never break, this might of course happen. 121 122In that case, please [let us know](https://github.com/Icinga/icingaweb2-module-director/issues). 123We'll try to fix your issue as soon as possible. 124 125<a name="schema-migrations"></a>Database schema migrations 126---------------------------------------------------------- 127 128In case there are any DB schema upgrades (and that's still often the case) this 129is no problem at all. They will pop up on your Director Dashboard and can be 130applied with a single click. And if your Director is deployed automatically by 131and automation tool like Puppet, also schema upgrades can easily be handled 132that way. Just follow the [related examples](03-Automation.md) in our documentation. 133 134<a name="schema-migrations"></a>Manual schema migrations 135---------------------------------------------------------- 136 137Please *do not* manually apply our schema migration files. We are very strict 138about our connection settings, encodings and SQL modes. Client encoding MUST be 139UTF-8, for MySQL and MariaDB we are using the following SQL Mode: 140 141```sql 142SET SESSION SQL_MODE='STRICT_ALL_TABLES,NO_ZERO_IN_DATE,NO_ZERO_DATE, 143ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,ANSI_QUOTES,PIPES_AS_CONCAT, 144NO_ENGINE_SUBSTITUTION'; 145``` 146 147Our migration files are written based on the assumption that those rules are 148strictly followed, and there may be other ones in future. So please use one 149of the supported migration methods either on the web or on command line and 150stay away from directly interfering with the schema. 151 152<a name="restart-jobrunner"></a>Restart the Job Runner service 153-------------------------------------------------------------- 154 155The Job Runner forks it's jobs, so usually a changed code base will take effect 156immediately. However, there might be (schema or code) changes involving the Runner 157process itself. To be on the safe side please always restart it after an upgrade, 158even when it's just a quick `git pull`: 159 160```sh 161systemctl restart director-jobs.service 162``` 163 164<a name="downgrade"></a>Downgrading 165----------------------------------- 166 167Downgrading is **not supported**. Most parts of the code will even refuse to 168work in case there are new fields in their database tables. Migrations are 169intentionally provided for upgrades only. In case you want to travel back in 170time please restore a matching former [Database Backup](#backup-first). 171 172<a name="footnote1">[1]</a>: 173Future Icinga Web 2 version will also take care of this step. We want to be 174able to have the latest JavaScript and CSS for any active module to be shipped 175silently without manual interaction to any connected browser within less then 17615 seconds after the latest module has been installed, enabled or upgraded. 177