Adds repository management

Author: LordHepipud

doc/07-Repository-Manager.md

@@ -0,0 +1,17 @@
+# Repository Manager
+
+Starting with Icinga for Windows v1.6.0, we provide a full feature-set to manage repositories for all components which are developed for Icinga for Windows. This includes all resources like framework, plugins the service binary and the Icinga Agent itself.
+
+Below you will find a detailed description for core areas of the repository management, explaining on how to work with repositories.
+
+## Basic Usage
+
+* [Add existing repositories](repositorymanager/01-Add-Existing-Repositories.md)
+* [Sync repositories](repositorymanager/02-Sync-Repositories.md)
+* [Enable/Disable/Remove Repositories](repositorymanager/03-Enable-Disable-Remove-Repositories.md)
+* [Search Repository for Components](repositorymanager/04-Search-Repository-For-Components.md)
+* [Lock/Unlock Components](repositorymanager/05-Lock-Unlock-Components.md)
+* [Install Components](repositorymanager/06-Install-Components.md)
+* [Create Own Repositories](repositorymanager/07-Create-Own-Repositories.md)
+
+## Example Configurations

doc/31-Changelog.md

@@ -22,6 +22,7 @@ Released closed milestones can be found on [GitHub](https://github.com/Icinga/ic
 * [#303](https://github.com/Icinga/icinga-powershell-framework/pull/303) Adds support to parse arrays to Icinga Check thresholds functions like `WarnOutOfRange` and adds two new functions `WarnDateTime` and `CritDateTime`, for easier comparing of time stamps.
 * [#305](https://github.com/Icinga/icinga-powershell-framework/pull/305) Adds a new Cmdlet to test if functions with `Add-Type` are already present inside the current scope of the shell
 * [#306](https://github.com/Icinga/icinga-powershell-framework/pull/306) Adds new Cmdlet `Exit-IcingaThrowCritical` to throw critical exit with a custom message, either by force or by using string filtering and adds storing of plugin exit codes internally
+* [#310](https://github.com/Icinga/icinga-powershell-framework/pull/310) Adds repository management to install components very easily from one or multiple defined source locations
 * [#314](https://github.com/Icinga/icinga-powershell-framework/pull/314) Adds support to configure on which address TCP sockets are created on, defaults to `loopback` interface
 * [#316](https://github.com/Icinga/icinga-powershell-framework/pull/316) The reconfigure menu was previously present inside the Icinga Agent sub-menu and is now moved to the main installation menu for the Management Console
 * [#318](https://github.com/Icinga/icinga-powershell-framework/pull/318) We always enforce the Icinga Framework Code caching now and ship a plain file to build the cache on first loading

doc/knowledgebase/IWKB000009.md

@@ -32,8 +32,8 @@ if ($null -ne $IcingaService) {
         return;
     }
 
-    Uninstall-IcingaFrameworkService;
-    Install-IcingaFrameworkService -Path $IfWPath -User $IfWUser;
+    Uninstall-IcingaForWindowsService;
+    Install-IcingaForWindowsService -Path $IfWPath -User $IfWUser;
 }
 ```
 

doc/repositorymanager/01-Add-Existing-Repositories.md

@@ -0,0 +1,44 @@
+# Add Existing Repositories
+
+The easiest way to extend the functionality of Icinga for Windows, is by installing new components. Components are delivered by repositories you can add to your environment. This includes external repositories but also internal ones.
+
+Each repository inherits a file called `ifw.repo.json` on the root level, which contains all informations for available packages, versions and where they can be downloaded from.
+
+**Note:** Each repository requires to use a unique name on the system. You can add multiple repositories, with different resources and components provided. The name has be unique and has no impact on the installation. It should be a short summary on where the repository is located.
+
+## Adding Default Repositories
+
+The best way to demonstrate on how to add new repositories, you can use the default Icinga for Windows repositories. To add an already existing repository, you can use `Add-IcingaRepository`
+
+### Available Arguments
+
+| Argument   | Type   | Description                                                                     |
+| ---        |---     | ---                                                                             |
+| Name       | String | The unique name of the repository. This name can only exist once on your system |
+| RemotePath | String | The path pointing to the location on where the repository is located at. It can either point to the root directory of the folder containing the `ifw.repo.json` or directly to this file. Accepts web, local or network share path. |
+
+### Icinga for Windows Stable
+
+The URL pointing to the stable releases is `http://packages.icinga.com/IcingaForWindows/stable`.
+
+```powershell
+Add-IcingaRepository `
+    -Name 'Icinga Stable' `
+    -RemotePath 'http://packages.icinga.com/IcingaForWindows/stable';
+```
+
+### Icinga for Windows Snapshot
+
+The URL pointing to the snapshot releases is `http://packages.icinga.com/IcingaForWindows/snapshot`.
+
+```powershell
+Add-IcingaRepository `
+    -Name 'Icinga Snapshot' `
+    -RemotePath 'http://packages.icinga.com/IcingaForWindows/snapshot';
+```
+
+## Using Repositories
+
+Once you added one or more repositories, they will be connected to once you want to install or update your components. The available components and versions will be accessed on runtime, during installation/updates and files downloaded directly when required.
+
+In case you can only access the internet or some internal repositories on certain times only, you can also [sync existing repositories](02-Sync-Repositories.md).

doc/repositorymanager/02-Sync-Repositories.md

@@ -0,0 +1,142 @@
+# Sync Repositories
+
+In case you require local copies of repositories to frequently access them or to make a public repository available for systems unable to access public spaces, you can use `Sync-IcingaRepository`.
+
+Like with [adding existing repositories](01-Add-Existing-Repositories.md), each synced repositories require a unique name you can set with `-Name`. The name will not interfere on how the sync works.
+
+## Available Arguments
+
+| Argument   | Type   | Description                                                                     |
+| ---        |---     | ---                                                                             |
+| Name       | String | The unique name of the repository. This name can only exist once on your system |
+| Path       | String | The location on where the files from the remote repository will be synced to. This can either be a local path, a network share or a Linux path, including user and hostname like `[email protected]:/vaw/www/icingarepo/`
+| RemotePath | String | The path pointing to the location Icinga for Windows tries to lookup all your files. You can either replicate the `Path` variable for network shares for example, or use a web url which is made available based on `Path` to fetch and download files from. If left empty, it will default to the `Path` variable content |
+| Source     | String | The source from where the repository will be synced from. This can either be pointing directly to the `ifw.repo.json` or the root directory, as long as the file is fetch able from this point. A source can be a web, local or network share |
+| UseSCP     | Switch | If you set `Path` to a Linux path as mentioned in the first example, you will have to enable this switch to use SCP to copy files from the source to the Linux system. Requires `scp` and `ssh` being installed on the system |
+| Force      | Switch | This will force the creation of the repository, even if the name of the repository is already assigned. Should be used with caution |
+| ForceTrust | Switch | By default repositories are validated with a hash, based on all files present inside the repository. If a repository is not providing a hash, it will be disabled after the sync for security reasons. In case the hash does not match with all files synced afterwards, the repository files will be deleted and the sync aborted. You can use this flag to ignore both states and always add the repository, regardless if the hash matches or the hash is not given |
+
+## Sync Public Repository
+
+You can use the sync command to clone an existing public repository for example and fetch all files to a local space.
+
+### Local Disk Example
+
+```powershell
+Sync-IcingaRepository `
+    -Name 'Icinga Stable Local' `
+    -Path 'C:\icinga\icinga_stable' `
+    -Source 'http://packages.icinga.com/IcingaForWindows/stable';
+```
+
+This will sync all files from the public Icinga repository into `C:\icinga\icinga_stable`. As `RemotePath` is not set, it will default to `C:\icinga\icinga_stable` and all files will be fetched from this location.
+
+### Shared Folder Example
+
+```powershell
+Sync-IcingaRepository `
+    -Name 'Icinga Stable Local' `
+    -Path 'C:\icinga\icinga_stable' `
+    -RemotePath '\\myhost.example.com\icingastable' `
+    -Source 'http://packages.icinga.com/IcingaForWindows/stable';
+```
+
+We can for example use file sharing, to make certain folders available in our network. This example will download all files into `C:\icinga\icinga_stable`, but tell Icinga for Windows to use your shared network drive `\\myhost.example.com\icingastable` to fetch them from.
+
+You can now add the repository on different machines with
+
+```powershell
+Add-IcingaRepository `
+    -Name 'Icinga Stable Local' `
+    -RemotePath '\\myhost.example.com\icingastable';
+```
+
+Every file will then be fetched over this network share to the local machines.
+
+### Linux Webserver Example
+
+```powershell
+Sync-IcingaRepository `
+    -Name 'Icinga Stable Internal Web' `
+    -Path '[email protected]:/var/www/icingastable/' `
+    -RemotePath 'https://icingarepo.example.com/icingastable' `
+    -Source 'http://packages.icinga.com/IcingaForWindows/stable' `
+    -UseSCP;
+```
+
+In this example we will sync all files to a Linux machine at `/var/www/icingastable/`. If we are running a local Apache or Nginx, we can create a web resource for this path and make it available in our network. We have to use `-UseSCP`, to tell Icinga for Windows to copy them to the Linux machine over `scp`. Please note that both, `scp` and `ssh` have to be installed  on the system.
+
+On different machines, you can then use 
+
+```powershell
+Add-IcingaRepository `
+    -Name 'Icinga Stable Internal Web' `
+    -RemotePath 'https://icingarepo.example.com/icingastable';
+```
+
+to make the repository available.
+
+### Sync from a Sync Example
+
+Last but not least we have the method to sync repositories from a sync source, allowing us to distribute all Icinga for Windows files around or network on different zones as example.
+
+Clone the repository to a local path:
+
+```powershell
+Sync-IcingaRepository `
+    -Name 'Icinga Stable Local' `
+    -Path 'C:\icinga\icinga_stable' `
+    -Source 'http://packages.icinga.com/IcingaForWindows/stable';
+```
+
+Clone this repository to our internal web space:
+
+```powershell
+Sync-IcingaRepository `
+    -Name 'Icinga Stable Internal Web' `
+    -Path '[email protected]:/var/www/icingastable/' `
+    -RemotePath 'https://icingarepo.example.com/icingastable' `
+    -Source 'C:\icinga\icinga_stable' `
+    -UseSCP;
+```
+
+## Update Sync Repositories
+
+To update synced repositories, you can use `Update-IcingaRepository`. You can either update a specific repository by using the `-Name` argument or update all by leaving it empty.
+
+### Available Arguments
+
+| Argument   | Type   | Description                                                                     |
+| ---        |---     | ---                                                                             |
+| Name       | String | The name of the repository to update. Leave empty to update all configured repositories |
+| ForceTrust | Switch | By default repositories are validated with a hash, based on all files present inside the repository. If a repository is not providing a hash, it will be disabled after the sync for security reasons. In case the hash does not match with all files synced afterwards, the repository files will be deleted and the sync aborted. You can use this flag to ignore both states and always add the repository, regardless if the hash matches or the hash is not given |
+
+### Update All Repositories
+
+Updating all synced repositories is very easy, with a simple command call:
+
+```powershell
+Update-IcingaRepository;
+```
+
+Once run, all files will be downloaded from the source and validated. In case validation fails or the source is not containing a repository hash, you can use `-ForceTrust` to ignore this and enable it regardless.
+
+```powershell
+Update-IcingaRepository -ForceTrust;
+```
+
+### Update Specific Repository
+
+You can update a specific repository, by simply providing it's name:
+
+```powershell
+Update-IcingaRepository -Name 'Icinga Stable Internal Web';
+```
+
+Like other methods, `-ForceTrust` will work here as well.
+
+## Updating Linux Repositories
+
+There is no special mechanic required, as the entire configuration for the repository is stored inside the Icinga for Windows configuration.
+
+For easier usage, it is however advised to use SSH keys, as otherwise each sync and update task will require you to enter your SSH password multiple times.

doc/repositorymanager/03-Enable-Disable-Remove-Repositories.md

@@ -0,0 +1,33 @@
+# Enable/Disable/Remove Repositories
+
+Besides [adding](01-Add-Existing-Repositories.md) and [syncing])(02-Sync-Repositories.md) of repositories, you can also `enable`, `disable` and `remove` repositories from your local machine.
+
+Please note that **removing** a repository will only remove the Icinga for Windows configuration and **not** the files on the disk. You have to do this step manually.
+
+## Enabling Repositories
+
+In case a repository is disabled, you can enable it with `Enable-IcingaRepository`.
+
+```powershell
+Enable-IcingaRepository -Name 'Icinga Stable Internal Web';
+```
+
+## Disabling Repositories
+
+You can also disable enabled repositories with `Disable-IcingaRepository`.
+
+```powershell
+Disable-IcingaRepository -Name 'Icinga Stable Internal Web';
+```
+
+Please note that disabled Icinga repositories will be fully ignored during installation/update tasks and no files from these will be fetched.
+
+## Removing Repositories
+
+If you no longer require a certain repository, you can remove it with `Remove-IcingaRepository`.
+
+```powershell
+Remove-IcingaRepository -Name 'Icinga Stable Internal Web';
+```
+
+**Note:** This will only remove the repository from the configuration. All possible available files for sync runs or anything related will remain on the disk until you remove them manually.

doc/repositorymanager/04-Search-Repository-For-Components.md

@@ -0,0 +1,33 @@
+# Search Repository For Components
+
+Once you [added](01-Add-Existing-Repositories.md) and/or [synced])(02-Sync-Repositories.md) your repositories, you can search them for available components.
+
+We can do this with the command `Search-IcingaRepository` and filter for a component `Name`, it's `Version` and if we want to include `Release` or `Snapshot` packages.
+
+## List Everything available
+
+At the beginning we can have a full search over all repositories and lookup all components made available by our repositories.
+
+```powershell
+Search-IcingaRepository -Name '*' -Release -Snapshot;
+```
+
+This will print all components including the version, the repository, the source of the repository and the component name.
+
+**Note:** Disabled repositories are not included inside the search and results.
+
+## List Certain Release Component
+
+You can only include certain components for a release branch by using the `Name` and `Release` argument:
+
+```powershell
+Search-IcingaRepository -Name 'agent' -Release;
+```
+
+## Search For Specific Version
+
+If you want to check if a certain `Release` version for a component is available inside your repositories, you can specify it with `Version`:
+
+```powershell
+Search-IcingaRepository -Name 'agent' -Version '2.12.5' -Release;
+```

doc/repositorymanager/05-Lock-Unlock-Components.md

@@ -0,0 +1,38 @@
+# Lock/Unlock Components
+
+Sometimes you might require to `lock` certain components to a specific version. This means regardless of any version available, this component will not be updated or touched, unless the version it is locked to is not yet installed.
+
+A lock will override the version suggested by any repository or the user input and always force the version specified.
+
+If for example you lock the [Icinga Plugins](https://icinga.com/docs/icinga-for-windows/latest/plugins/doc/01-Introduction/) to version 1.6.0, they will not get upgraded to any other version.
+
+## Locking Commponents
+
+You can lock any Icinga component with `Lock-IcingaComponent` by simply providing the name of the component and the target version.
+
+For example we can look our plugins to version 1.6.0:
+
+```powershell
+Lock-IcingaComponent `
+    -Name 'plugins' `
+    -Version '1.6.0';
+```
+
+Now the only version being installed for the plugins is 1.6.0, while all other versions are skipped. You can directly replace the lock for a different version later on, like 1.6.1:
+
+```powershell
+Lock-IcingaComponent `
+    -Name 'plugins' `
+    -Version '1.6.1';
+```
+
+## Unlocking Components
+
+You can release a lock for a component by using `Unlock-IcingaComponent`. Unlike the locking mechanism, you only require to specify the component name for unlocking it, as each component only accepts one version lock at the time.
+
+```powershell
+Unlock-IcingaComponent `
+    -Name 'plugins';
+```
+
+Once the lock is removed, updates will be applied again for this component.

doc/repositorymanager/06-Install-Components.md

@@ -0,0 +1,60 @@
+# Install Components
+
+Once you [added](01-Add-Existing-Repositories.md) and/or [synced])(02-Sync-Repositories.md) your repositories and configured - if required - your [locks](05-Lock-Unlock-Components.md), we can start installing components.
+
+For this we will use `Install-IcingaComponent`.
+
+**Note:** When the install component is looking up available versions, *all* defined repositories will be searched and the latest version available used by default. If a specific version is set, it will stop once this version is found in one of the repositories and go with this package.
+
+## Available Arguments
+
+| Argument   | Type   | Description                                                                     |
+| ---        |---     | ---                                                                             |
+| Name       | String | The name of the component you want to install |
+| Version    | String | Specifies to install a specific version of the component, instead of the latest one found. Is ignored in case you added a [lock](05-Lock-Unlock-Components.md) to this component |
+| Release    | Switch | Includes release versions only if set. If neither Release nor Snapshot is defined, it will enforce release |
+| Snapshot   | Switch | Includes snapshots versions only if set. If neither Release nor Snapshot is defined, it will enforce release |
+| Confirm    | Switch | Skips the message asking you if you want to install this component |
+| Force      | Switch | In case the same version is already installed, it will be skipped by default. Use this switch to install the same version again |
+
+## Install Release Components
+
+You can install release components either by adding the `-Release` switch or by not adding `-Release` and `-Snapshot` at all, to enforce release versions. If no version is specified, the latest version found will be used. Use `-Confirm` in addition to skip the dialog requiring an approval to install it.
+
+```powershell
+Install-IcingaComponent `
+    -Name 'agent' `
+    -Confirm;
+```
+
+## Install Specific Component Version
+
+If your repository contains multiple versions, you can specify which version will be installed:
+
+```powershell
+Install-IcingaComponent `
+    -Name 'agent' `
+    -Version '2.11.2' `
+    -Confirm;
+```
+
+## Reinstall Installed Component
+
+If a component with a specific version is already installed, you can use `-Force` to re-install it.
+
+```powershell
+Install-IcingaComponent `
+    -Name 'agent' `
+    -Version '2.11.5' `
+    -Confirm `
+    -Force;
+```
+
+This also works for auto detected latest versions:
+
+```powershell
+Install-IcingaComponent `
+    -Name 'agent' `
+    -Confirm `
+    -Force;
+```