Improves documentation for Framework installation

doc/02-Installation.md

@@ -8,6 +8,7 @@ Instructions
 
 * Install the Icinga PowerShell Framework with the [Kickstart Script](installation/01-Kickstart-Script.md)
 * Install the Icinga PowerShell Framework [manually](installation/02-Manual-Installation.md)
+* Install the Icinga PowerShell Framework with [PowerShell Gallery](installation/03-PowerShell-Gallery-Installation.md)
 
 Testing the installation
 ---
@@ -20,8 +21,15 @@ Use-Icinga
 
 This command will initialise the entire Icinga PowerShell Framework and load all available Cmdlets.
 
+*Note:* Starting with Icinga PowerShell Framework `1.2.0` you can simply use `icinga` to open a Icinga PowerShell Framework shell.
+
 Whenever you intend to use specific Cmdlets of the framework for Icinga Plugins, Testing or configuration you will require to run this command for each new PowerShell instance to initialise the framework.
 
+Icinga Agent installation wizard
+---
+
+Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.
+
 Service Installation
 ---
 

doc/installation/01-Kickstart-Script.md

@@ -1,12 +1,10 @@
-Install the framework with the Kickstart Script
+# Install the Framework with the Kickstart Script
-===
 
 The easiest way to install the framework is by using the Kickstart Script provided from [this repository](https://github.com/Icinga/icinga-powershell-kickstart).
 
 The code provided there will ask questions on where to install the framework and where the framework files are provided from. The code below is a straight copy of the initial required code-block. Simply open a PowerShell instance as administrator and copy the following code block into it:
 
-Getting Started
+## Getting Started
----
 
 ```powershell
 [Net.ServicePointManager]::SecurityProtocol = "tls12, tls11";
@@ -25,9 +23,95 @@ What this block will do is to download the PowerShell Script from the repository
 The ServicePointManager part will ensure communication is possible to GitHub for example, as by default PowerShell will be unable to open a secure connection otherwise.
 Last but not least we will set the progress preference to `SilentlyContinue`, ensuring the PowerShell progress bar will not slow down our installation.
 
-Next Steps
+The Script file from `https://raw.githubusercontent.com/Icinga/icinga-powershell-kickstart/master/script/icinga-powershell-kickstart.ps1` will be downloaded and executed within your current PowerShell instance. It will ask a bunch of questions on where the Icinga PowerShell Framework should be downloaded from and where it should be installed.
----
 
-Once the above step is completed, simply follow the instructions and answer the questions the wizard will ask you. Once the framework is installed, the wizard will ask you if you wish to continue with the Agent installation wizard.
+Once completed, the kickstart will ask if you want to continue with the Icinga Agent installation wizard.
 
-The entire purpose is to offer a fluent and seamless installation experience.
+## Offline Installation
+
+Of course you can also use the kickstart script file for offline installation in case you have no access to the internet. For this you will have to download the script file manually once and place it either on an internal web server from which the kickstart script can fetch the `.ps1` file or provide it by a network share or local drive.
+
+### Offline Internal Web-Server
+
+If you are using an internal web server for the kickstart script you simply have to modify the line
+
+```powershell
+$global:IcingaFrameworkKickstartSource = 'https://raw.githubusercontent.com/Icinga/icinga-powershell-kickstart/master/script/icinga-powershell-kickstart.ps1';
+```
+
+from the script above to match your internal web server location. This could for example be:
+
+```powershell
+$global:IcingaFrameworkKickstartSource = 'https://example.com/icinga-kickstart/icinga-powershell-kickstart.ps1';
+```
+
+Once you copy the modified script block into your PowerShell, it will download the kickstart from your internal ressource and execute the code in the same way as before - just without requiring an internet connection.
+
+### Offline Network Share/Local Location
+
+To use the kickstart script from a local file ressource like a network share or on a local drive on your machine, you can run this code snippet to load it from there. Just replace the path to the kickstart file with the actual path in your enrivonment:
+
+```powershell
+$global:IcingaFrameworkKickstartSource = 'C:\icinga\kickstart\icinga-powershell-kickstart.ps1';
+
+$Script = Get-Content -Path $global:IcingaFrameworkKickstartSource -Raw;
+$Script += "`r`n`r`n Start-IcingaFrameworkWizard;";
+
+Invoke-Command -ScriptBlock ([Scriptblock]::Create($Script));
+```
+
+As with the web installation process, the kickstart wizard will then guide you through the installation.
+
+## Note on Start-IcingaFrameworkWizard and automation
+
+Every example above contains the following code part:
+
+```powershell
+$Script += "`r`n`r`n Start-IcingaFrameworkWizard;";
+```
+
+This snippet will ensure that once the kickstart script is downloaded it will be executed and asks a bunch of questions:
+
+* Where to download the Icinga PowerShell Framework from
+* Where to install the Icinga PowerShell Framework to
+* Are updates of the Framework allowed
+* Should the Icinga Agent installation and configuration wizard be started afterwards
+
+### Automation with the Kickstart-Script
+
+To automate the entire process once the kickstart script is executed, you can add aditional arguments to the call to manage the configuration.  The following arguments are supported
+
+| Argument         | Type   | Description |
+| ---              | ---    | ---         |
+| -RepositoryUrl   | String | A web, local or network path path pointing the Icinga PowerShell Framework .zip file |
+| -ModuleDirectory | String | The target on which the Icinga PowerShell Framework will be installed into |
+| -AllowUpdate     | Bool   | Defines if an existing version of the Framework should be upgraded/downgraded |
+| -SkipWizard      | Switch | Defines if the Icinga Agent installation wizard should be skipped |
+
+You can simply update the line
+
+```powershell
+$Script += "`r`n`r`n Start-IcingaFrameworkWizard;";
+```
+
+to match your configuration properly.
+
+#### Automation Example 1: Use local web server for Framework download
+
+We will download the Icinga PowerShell Framework from a local web server and install it in the recommended module directory. In addition we want to allow updates and do not want to start the Icinga Agent wizard afterwards:
+
+```powershell
+$Script += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'https://example.com/icingaforwindows/icinga-powershell-framework.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
+```
+
+#### Automation Example 2: Use local/network path for Framework "download"
+
+We will use a local drive or a network share to fetch the Icinga PowerShell Framework from and install it in the recommended module directory. In addition we want to allow updates and do not want to start the Icinga Agent wizard afterwards:
+
+```powershell
+$Script += "`r`n`r`n Start-IcingaFrameworkWizard -RepositoryUrl 'C:\icinga\icinga-powershell-framework.zip' -ModuleDirectory 'C:\Program Files\WindowsPowerShell\modules\' -AllowUpdate 1 -SkipWizard;";
+```
+
+## Execute the Icinga Agent installation wizard
+
+Depending on how you used the kickstart script above, you are either directly asked if you want to continue with the Icinga Agent installation wizard or not. Even if you hit `no`, you are still able to execute it afterwards. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.

doc/installation/02-Manual-Installation.md

@@ -1,10 +1,8 @@
-Install the framework manually
+# Install the Framework manually
-===
 
 To install the module manually we will at first fetch information on where we can actually install the module into. PowerShell provides some default directories, which can however also extended manually.
 
-Getting Started
+## Getting Started
----
 
 To do this, we can run the following command within PowerShell
 
@@ -30,8 +28,7 @@ Get-Module -ListAvailable -Name icinga-powershell-framework
 
 If you receive an output stating that the module is installed, you are fine to continue.
 
-Execution Policies and File Blocking
+## Execution Policies and File Blocking
----
 
 In order to be able to run the module on certain Windows Hosts, it might be required to either update the execution policies and/or unblock the module script files.
 
@@ -43,14 +40,6 @@ Get-ChildItem -Path 'C:\Program Files\WindowsPowershell\Modules\icinga-powershel
 
 Once done, please try again if you are now able to run the module on your host. If you are still not able to run the module and/or its scripts, please have a look at the Microsoft documentation for the [Set-Execution-Policy](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy?view=powershell-6) Cmdlet to modify the Execution Policy for running PowerShell modules on your host, matching your internal guidelines.
 
-Start the Installation Wizard
+## Execute the Icinga Agent installation wizard
----
 
-Once the entire Framework is installed and the module is runnable, you can start the installation wizard of the Agent:
+Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.
-
-```powershell
-Use-Icinga;
-Start-IcingaAgentInstallWizard;
-```
-
-The wizard will then guide you through the entire configuration and installation. Once completed, you will receive a configuration string with all your configured settings to easily run the same command on another machine or for automated installation.

doc/installation/03-PowerShell-Gallery-Installation.md

@@ -0,0 +1,17 @@
+# Install the Framework with PowerShell Gallery
+
+PowerShell Gallery provides a collection of PowerShell modules and scripts which can easily be intalled on target machines. For a further description, please have a look on the [PowerShell Gallery website](https://www.powershellgallery.com/).
+
+## Getting Started
+
+Icinga is providing PowerShell Gallery packages within the [Icinga Profile](https://www.powershellgallery.com/profiles/Icinga) for the Framework itself and other related components.
+
+To install the Icinga PowerShell Framework you can simpy use `Install-Module` in case it is available and configured on your system:
+
+```powershell
+Install-Module -Name icinga-powershell-framework;
+```
+
+## Execute the Icinga Agent installation wizard
+
+Once the entire Framework is installed and the module is runnable, you can start the Icinga Agent installation wizard. Please follow the [Icinga Agent Wizard](04-Icinga-Agent-Wizard.md) guide for examples and usage.

doc/installation/04-Icinga-Agent-Wizard.md

@@ -0,0 +1,95 @@
+# Icinga Agent installation wizard
+
+It doesn't matter if you installed the Icinga PowerShell Framework with he [Kickstart Script](01-Kickstart-Script.md) or [Manually](02-Manual-Installation.md). In the and you can use the Icinga Agent installation wizard to configure the system additional, to install the Agent and deploy plugins as well install the Icinga PowerShell Service.
+
+## Start the Icinga Agent wizard
+
+To start the Icinga Agent installation wizard you will have to open a PowerShell as Administrator first and enter
+
+```powershell
+Use-Icinga
+```
+
+*Note:* Starting with Icinga PowerShell Framework `1.2.0` you can simply type `icinga` to open an Icinga PowerShell Framework shell,
+
+Once the command is executed, the Framework and all required components are loaded. To get started, we can now run
+
+```powershell
+Start-IcingaAgentInstallWizard;
+```
+
+The wizard will ask a bunch of questions, for example if you are using the semi-automated Director Self-Service API or if you configure everything by yourself.
+
+Depending on how you configure the system, there might different questions occure. The goal of the wizard is to cover most of the possible configurations available for the Icinga Agent. This includes
+
+* How your certificates are generated
+* If you Icinga Agent or the Master/Satellites are establishing the connection
+* Definition of the service user the Icinga Agent will run with
+* Ensuring that the Icinga Agent with the provided configuration and settings is able to start and everyhing is valid
+
+Once you completed the wizard you are asked if the configuration is correct and if you want to execute the configuration. In any way, you are always printed the configuration command with your configured settings. 
+This command can be executed on `any` Windows machine which has the Icinga PowerShell Framework installed. It contains the entire configuration for the system. Of course you can modify the values to match certain network zones or requirements.
+
+## Configuration Command Examples
+
+Below you will find some examples for different kind of configuration commands which can be executed to configure the Icinga Agent and to install plugins.
+
+**Important Note:**
+
+### Config Example 1: Director Self-Service
+
+This example will use the Icinga Director Self-Service API and use a host template key to register the current machine within the Icinga Director and fetch the correct configuration for the host. In addition we will not override any provided variables and convert our Icinga endpoint configuration to actual IPs. For example if our Icinga parent node is registered with address `icinga2-master.example.com` the FQDN will automatically be translated to the refering IP address. This is important as in case of a DNS failure we want to ensure the monitoring is still working properly. In addition we leave the Ticket handling empty as the Self-Service will take care of it and we neihter want to install the Plugins nor the Icinga PowerShell Service.
+
+Last but not least we want to directly run the installer.
+
+```powershell
+Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://sales-net-icinga2a.int.netways.de/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
+```
+
+### Config Example 2: Director Self-Service with Argument override
+
+This is the same example as above, but this time we will override our `CAEndpoint` for the Icinga certificate authority:
+
+```powershell
+Start-IcingaAgentInstallWizard -SelfServiceAPIKey '56756378658n56t85679765n97649m7649m76' -UseDirectorSelfService 1 -DirectorUrl 'https://sales-net-icinga2a.int.netways.de/icingaweb2/director/' -OverrideDirectorVars 0 -ConvertEndpointIPConfig 1 -Ticket '' -EmptyTicket 1 -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -CAEndpoint 'icinga2-ca.example.com' -RunInstaller;
+```
+
+### Config Example 3: Configure Icinga Agent to connect to Parents and use Cert-Proxy
+
+This example will configure the Icinga Agent to use the local hostname including the FQDN as lower case, download the latest stable version of the Icinga Agent from packages.icinga.com and connect to the parent nodes. As we are not providing a `Ticket` with the installation, we will later have to sign the request on our Icinga master with `icinga2 ca sign <request>` (to get all pending requests you can use `icinga2 ca list` on your Icinga master).
+
+Like before, we are not installing the Icinga PowerShell Service or the plugins in this step.
+
+```powershell
+Start-IcingaAgentInstallWizard -UseDirectorSelfService 0 -AutoUseFQDN 1 -AutoUseHostname 0 -LowerCase 1 -UpperCase 0 -AllowVersionChanges 1 -UpdateAgent 1 -AgentVersion 'release' -PackageSource 'https://packages.icinga.com/windows/' -Endpoints icinga2a,icinga2b -CAPort 5665 -AcceptConnections 0 -AddFirewallRule 0 -ConvertEndpointIPConfig 1 -EndpointConnections 192.168.0.1,192.168.0.2 -ParentZone master -AddDirectorGlobal 1 -AddGlobalTemplates 1 -GlobalZones @() -CAEndpoint 192.168.0.1 -Ticket '' -EmptyTicket 1 -ServiceUser 'NT Authority\NetworkService' -InstallFrameworkPlugins 0 -InstallFrameworkService 0 -RunInstaller;
+```
+
+### Config Example 4: Install the Icinga PowerShell Service during wizard run
+
+Of course you can install the Icinga PowerShell Service directly during the runtime of the wizard. To do so, take the above examples and `replace` the argument `-InstallFrameworkService 0` with:
+
+```powershell
+-InstallFrameworkService 1 -FrameworkServiceUrl 'https://github.com/Icinga/icinga-powershell-service/releases/download/v1.1.0/icinga-service-v1.1.0.zip' -ServiceDirectory 'C:\Program Files\icinga-framework-service\'
+```
+
+**Explanation:**
+
+The argument `FrameworkServiceUrl` is asking for a path pointing to the `.zip` file which contains the service binary. The file can either be located on a web ressource or a local/network share. The `ServiceDirectory` argument will point to the target on where the `.exe` file itself is being extracted to. This location is then being used to register the Windows Service object to which is later executed. In general there is an additional argument `ServiceBin` available which will define the direct path to the service binary. This can be left empty how ever of the official `.zip` file of Icinga for the service package is used.
+
+### Config Example 5: Install the Icinga Plugins during wizard run
+
+Just like the service you can also directly run the installation of the plugins during the wizard runtime. For this you will have to replace `-InstallFrameworkPlugins 0` of the above mentioned examples with:
+
+```powershell
+-InstallFrameworkPlugins 1 -PluginsUrl 'https://github.com/Icinga/icinga-powershell-plugins/archive/master.zip'
+```
+
+Just like the service binary, you can specify a different path to the `.zip` file of the plugins. This can either be a web ressource or a local/network share path.
+
+## Install Icinga PowerShell Components
+
+Besides installing the Icinga PowerShell Plugins during the installation, you can also install them with a dedicated Cmdlet: `Install-IcingaFrameworkComponent`
+
+This Cmdlet is using a namespace to ensure that the location is handled and each ressource can be accessed properly. As with the above mentiond service binary and plugin repository, you can specify a custom location for the `.zip` file include the name of of the repository.
+
+For more details please have a look on the [Icinga Plugin Installation Guide](https://icinga.com/docs/windows/latest/plugins/doc/02-Installation/). This does also apply to every other Icinga Framework Component in the future.