Merge pull request #7342 from Icinga/feature/docs-rename-client-agent

Docs: Enhance distributed monitoring chapter
This commit is contained in:
Michael Friedrich 2019-07-20 15:21:48 +02:00 committed by GitHub
commit c497679a58
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
30 changed files with 889 additions and 550 deletions

View File

@ -153,7 +153,7 @@
this.lblSetupCompleted.Name = "lblSetupCompleted";
this.lblSetupCompleted.Size = new System.Drawing.Size(259, 13);
this.lblSetupCompleted.TabIndex = 0;
this.lblSetupCompleted.Text = "The Icinga 2 Windows client was set up successfully.";
this.lblSetupCompleted.Text = "The Icinga Windows agent was set up successfully.";
//
// tabConfigure
//
@ -272,7 +272,7 @@
this.introduction1.Name = "introduction1";
this.introduction1.Size = new System.Drawing.Size(269, 13);
this.introduction1.TabIndex = 6;
this.introduction1.Text = "Welcome to the Icinga 2 Windows Client Setup Wizard!";
this.introduction1.Text = "Welcome to the Icinga Windows Agent Setup Wizard!";
//
// groupBox3
//
@ -437,7 +437,7 @@
this.groupBox1.Size = new System.Drawing.Size(601, 110);
this.groupBox1.TabIndex = 1;
this.groupBox1.TabStop = false;
this.groupBox1.Text = "Parent master/satellite instance(s) for this client";
this.groupBox1.Text = "Parent master/satellite instance(s) for this agent";
//
// btnEditEndpoint
//

View File

@ -290,7 +290,7 @@ namespace Icinga
SetConfigureStatus(100, "Finished.");
// Override the completed text
lblSetupCompleted.Text = "The Icinga 2 Windows client was set up successfully.";
lblSetupCompleted.Text = "The Icinga Windows agent was set up successfully.";
// Add a note for the user for ticket-less signing
if (ticket.Length == 0) {

View File

@ -678,7 +678,7 @@ attribute and reference an existing host attribute.
```
object Service "ping4" {
check_command = "ping4"
host_name = "icinga2-client1.localdomain"
host_name = "icinga2-agent1.localdomain"
}
```
@ -1599,7 +1599,7 @@ already provides an example for this question.
Specify the user and groups as nested custom variable on the host object:
```
object Host "icinga2-client1.localdomain" {
object Host "icinga2-agent1.localdomain" {
[...]
vars.notification["mail"] = {
@ -2035,7 +2035,7 @@ If you prefer this being configured at the host instead of the service, modify t
object instead. The runtime macro resolving order is described [here](03-monitoring-basics.md#macro-evaluation-order).
```
object Host "icinga2-client1.localdomain {
object Host "icinga2-agent1.localdomain {
...
vars.ssh_port = 2022
}
@ -2763,7 +2763,7 @@ The script only is executed if the service state is `CRITICAL`. Warning and Unkn
are ignored as they indicate not an immediate failure.
```
[root@icinga2-client1.localdomain /]# vim /usr/lib64/nagios/plugins/restart_service
[root@icinga2-agent1.localdomain /]# vim /usr/lib64/nagios/plugins/restart_service
#!/bin/bash
@ -2794,7 +2794,7 @@ else
fi
fi
[root@icinga2-client1.localdomain /]# chmod +x /usr/lib64/nagios/plugins/restart_service
[root@icinga2-agent1.localdomain /]# chmod +x /usr/lib64/nagios/plugins/restart_service
```
Add a service on the master node which is executed via command endpoint on the client.
@ -2802,15 +2802,15 @@ Set the `event_command` attribute to `restart_service`, the name of the previous
EventCommand object.
```
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client1.localdomain.conf
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-agent1.localdomain.conf
object Service "Process httpd" {
check_command = "procs"
event_command = "restart_service"
max_check_attempts = 4
host_name = "icinga2-client1.localdomain"
command_endpoint = "icinga2-client1.localdomain"
host_name = "icinga2-agent1.localdomain"
command_endpoint = "icinga2-agent1.localdomain"
vars.procs_command = "httpd"
vars.procs_warning = "1:10"
@ -2818,17 +2818,17 @@ object Service "Process httpd" {
}
```
In order to test this configuration just stop the `httpd` on the remote host `icinga2-client1.localdomain`.
In order to test this configuration just stop the `httpd` on the remote host `icinga2-agent1.localdomain`.
```
[root@icinga2-client1.localdomain /]# systemctl stop httpd
[root@icinga2-agent1.localdomain /]# systemctl stop httpd
```
You can enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) and search for the
executed command line.
```
[root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep restart_service
[root@icinga2-agent1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep restart_service
```
#### Use Event Commands to Restart Service Daemon via Command Endpoint on Windows <a id="event-command-restart-service-daemon-command-endpoint-windows"></a>
@ -2904,21 +2904,21 @@ Set the `event_command` attribute to `restart_service-windows`, the name of the
EventCommand object.
```
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-client2.localdomain.conf
[root@icinga2-master1.localdomain /]# vim /etc/icinga2/zones.d/master/icinga2-agent2.localdomain.conf
object Service "Service httpd" {
check_command = "service-windows"
event_command = "restart_service-windows"
max_check_attempts = 4
host_name = "icinga2-client2.localdomain"
command_endpoint = "icinga2-client2.localdomain"
host_name = "icinga2-agent2.localdomain"
command_endpoint = "icinga2-agent2.localdomain"
vars.service_win_service = "httpd"
}
```
In order to test this configuration just stop the `httpd` on the remote host `icinga2-client1.localdomain`.
In order to test this configuration just stop the `httpd` on the remote host `icinga2-agent1.localdomain`.
```
C:> net stop httpd
@ -3024,15 +3024,15 @@ object Host "remote-http-host" {
}
```
In order to test this configuration just stop the `httpd` on the remote host `icinga2-client1.localdomain`.
In order to test this configuration just stop the `httpd` on the remote host `icinga2-agent1.localdomain`.
```
[root@icinga2-client1.localdomain /]# systemctl stop httpd
[root@icinga2-agent1.localdomain /]# systemctl stop httpd
```
You can enable the [debug log](15-troubleshooting.md#troubleshooting-enable-debug-output) and search for the
executed command line.
```
[root@icinga2-client1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep by_ssh
[root@icinga2-agent1.localdomain /]# tail -f /var/log/icinga2/debug.log | grep by_ssh
```

File diff suppressed because it is too large Load Diff

View File

@ -302,7 +302,7 @@ Icinga 2 instances. More details can be found in the [distributed monitoring cha
Example:
```
object Endpoint "icinga2-client1.localdomain" {
object Endpoint "icinga2-agent1.localdomain" {
host = "192.168.56.111"
port = 5665
log_duration = 1d
@ -312,7 +312,7 @@ object Endpoint "icinga2-client1.localdomain" {
Example (disable replay log):
```
object Endpoint "icinga2-client1.localdomain" {
object Endpoint "icinga2-agent1.localdomain" {
host = "192.168.5.111"
port = 5665
log_duration = 0
@ -364,7 +364,7 @@ A host.
Example:
```
object Host "icinga2-client1.localdomain" {
object Host "icinga2-agent1.localdomain" {
display_name = "Linux Client 1"
address = "192.168.56.111"
address6 = "2a00:1450:4001:815::2003"

View File

@ -342,12 +342,12 @@ Icinga 2 (version: v2.11.0)
Once connected you can inspect variables and execute other expressions by entering them at the prompt:
```
<1> => var h = get_host("icinga2-client1.localdomain")
<1> => var h = get_host("icinga2-agent1.localdomain")
null
<2> => h.last_check_result
{
active = true
check_source = "icinga2-client1.localdomain"
check_source = "icinga2-agent1.localdomain"
command = [ "/usr/local/sbin/check_ping", "-H", "127.0.0.1", "-c", "5000,100%", "-w", "3000,80%" ]
execution_end = 1446653527.174983
execution_start = 1446653523.152673
@ -382,10 +382,10 @@ The `--syntax-only` option can be used in combination with `--eval` or `--file`
to check a script for syntax errors. In this mode the script is parsed to identify
syntax errors but not evaluated.
Here's an example that retrieves the command that was used by Icinga to check the `icinga2-client1.localdomain` host:
Here's an example that retrieves the command that was used by Icinga to check the `icinga2-agent1.localdomain` host:
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("icinga2-client1.localdomain").last_check_result.command' | python -m json.tool
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' --eval 'get_host("icinga2-agent1.localdomain").last_check_result.command' | python -m json.tool
[
"/usr/local/sbin/check_ping",
"-H",

View File

@ -1503,12 +1503,12 @@ Example:
```
$ curl -k -s -u root:icinga -H 'Accept: application/json' \
-X POST 'https://localhost:5665/v1/actions/generate-ticket' \
-d '{ "cn": "icinga2-client1.localdomain", "pretty": true }'
-d '{ "cn": "icinga2-agent1.localdomain", "pretty": true }'
{
"results": [
{
"code": 200.0,
"status": "Generated PKI ticket '4f75d2ecd253575fe9180938ebff7cbca262f96e' for common name 'icinga2-client1.localdomain'.",
"status": "Generated PKI ticket '4f75d2ecd253575fe9180938ebff7cbca262f96e' for common name 'icinga2-agent1.localdomain'.",
"ticket": "4f75d2ecd253575fe9180938ebff7cbca262f96e"
}
]

View File

@ -393,10 +393,10 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Over
"results": [
{
"attrs": {
"__name": "icinga2-client1.localdomain!disk",
"__name": "icinga2-agent1.localdomain!disk",
"last_check_result": {
"active": true,
"check_source": "icinga2-client1.localdomain",
"check_source": "icinga2-agent1.localdomain",
...
@ -404,7 +404,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Over
},
"joins": {},
"meta": {},
"name": "icinga2-client1.localdomain!disk",
"name": "icinga2-agent1.localdomain!disk",
"type": "Service"
}
]
@ -415,9 +415,9 @@ Example for using the `icinga2 console` CLI command evaluation functionality:
```
$ ICINGA2_API_PASSWORD=icinga icinga2 console --connect 'https://root@localhost:5665/' \
--eval 'get_service("icinga2-client1.localdomain", "disk").last_check_result.check_source' | python -m json.tool
--eval 'get_service("icinga2-agent1.localdomain", "disk").last_check_result.check_source' | python -m json.tool
"icinga2-client1.localdomain"
"icinga2-agent1.localdomain"
```
@ -475,7 +475,7 @@ in mind when using a different package.
This could happen with [clients as command endpoint execution](06-distributed-monitoring.md#distributed-monitoring-top-down-command-endpoint).
If you have for example a client host `icinga2-client1.localdomain`
If you have for example a client host `icinga2-agent1.localdomain`
and a service `disk` check defined on the master, the warning and
critical thresholds are sometimes to applied and unwanted notification
alerts are raised.
@ -909,7 +909,7 @@ Certificate:
Client public certificate:
```
# openssl x509 -in icinga2-client1.localdomain.crt -text
# openssl x509 -in icinga2-agent1.localdomain.crt -text
Certificate:
Data:
@ -921,7 +921,7 @@ Certificate:
Validity
Not Before: Aug 20 16:20:05 2016 GMT
Not After : Aug 17 16:20:05 2031 GMT
Subject: CN=icinga2-client1.localdomain
Subject: CN=icinga2-agent1.localdomain
Subject Public Key Info:
Public Key Algorithm: rsaEncryption
Public-Key: (4096 bit)
@ -932,7 +932,7 @@ Certificate:
X509v3 Basic Constraints: critical
CA:FALSE
X509v3 Subject Alternative Name:
DNS:icinga2-client1.localdomain
DNS:icinga2-agent1.localdomain
Signature Algorithm: sha256WithRSAEncryption
...
```
@ -944,14 +944,14 @@ both instances are signed by the **same CA**.
# openssl verify -verbose -CAfile /var/lib/icinga2/certs/ca.crt /var/lib/icinga2/certs/icinga2-master1.localdomain.crt
icinga2-master1.localdomain.crt: OK
# openssl verify -verbose -CAfile /var/lib/icinga2/certs/ca.crt /var/lib/icinga2/certs/icinga2-client1.localdomain.crt
icinga2-client1.localdomain.crt: OK
# openssl verify -verbose -CAfile /var/lib/icinga2/certs/ca.crt /var/lib/icinga2/certs/icinga2-agent1.localdomain.crt
icinga2-agent1.localdomain.crt: OK
```
Fetch the `ca.crt` file from the client node and compare it to your master's `ca.crt` file:
```
# scp icinga2-client1:/var/lib/icinga2/certs/ca.crt test-client-ca.crt
# scp icinga2-agent1:/var/lib/icinga2/certs/ca.crt test-client-ca.crt
# diff -ur /var/lib/icinga2/certs/ca.crt test-client-ca.crt
```
@ -1122,7 +1122,7 @@ works (default port is `5665`).
# netstat -tulpen | grep icinga
# nmap icinga2-client1.localdomain
# nmap icinga2-agent1.localdomain
```
### Cluster Troubleshooting SSL Errors <a id="troubleshooting-cluster-ssl-errors"></a>
@ -1136,10 +1136,10 @@ the following
* Verify the `Subject` containing your endpoint's common name (CN)
* Check the validity of the certificate itself
Try to manually connect from `icinga2-client1.localdomain` to the master node `icinga2-master1.localdomain`:
Try to manually connect from `icinga2-agent1.localdomain` to the master node `icinga2-master1.localdomain`:
```
# openssl s_client -CAfile /var/lib/icinga2/certs/ca.crt -cert /var/lib/icinga2/certs/icinga2-client1.localdomain.crt -key /var/lib/icinga2/certs/icinga2-client1.localdomain.key -connect icinga2-master1.localdomain:5665
# openssl s_client -CAfile /var/lib/icinga2/certs/ca.crt -cert /var/lib/icinga2/certs/icinga2-agent1.localdomain.crt -key /var/lib/icinga2/certs/icinga2-agent1.localdomain.key -connect icinga2-master1.localdomain:5665
CONNECTED(00000003)
---
@ -1156,7 +1156,7 @@ Unauthenticated nodes are able to connect. This is required for client setups.
Master:
```
[2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga2-client1.localdomain' (unauthenticated)
[2015-07-13 18:29:25 +0200] information/ApiListener: New client connection for identity 'icinga2-agent1.localdomain' (unauthenticated)
```
Client as command execution bridge:
@ -1247,14 +1247,14 @@ If the client cannot authenticate, it's a more general [problem](15-troubleshoot
The client's endpoint is not configured on nor trusted by the master node:
```
Discarding 'check result' message from 'icinga2-client1.localdomain': Invalid endpoint origin (client not allowed).
Discarding 'check result' message from 'icinga2-agent1.localdomain': Invalid endpoint origin (client not allowed).
```
The check result message sent by the client does not belong to the zone the checkable object is
in on the master:
```
Discarding 'check result' message from 'icinga2-client1.localdomain': Unauthorized access.
Discarding 'check result' message from 'icinga2-agent1.localdomain': Unauthorized access.
```
@ -1297,7 +1297,7 @@ the `NodeName` constant with the FQDN. Ensure this is the same value
as the local endpoint object name.
```
const NodeName = "windows-client1.domain.com"
const NodeName = "windows-agent1.domain.com"
```

View File

@ -534,8 +534,8 @@ The default certificate path was changed from `/etc/icinga2/pki` to
Old Path | New Path
---------------------------------------------------|---------------------------------------------------
`/etc/icinga2/pki/icinga2-client1.localdomain.crt` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.crt`
`/etc/icinga2/pki/icinga2-client1.localdomain.key` | `/var/lib/icinga2/certs/icinga2-client1.localdomain.key`
`/etc/icinga2/pki/icinga2-agent1.localdomain.crt` | `/var/lib/icinga2/certs/icinga2-agent1.localdomain.crt`
`/etc/icinga2/pki/icinga2-agent1.localdomain.key` | `/var/lib/icinga2/certs/icinga2-agent1.localdomain.key`
`/etc/icinga2/pki/ca.crt` | `/var/lib/icinga2/certs/ca.crt`
This applies to Windows clients in the same way: `%ProgramData%\etc\icinga2\pki`
@ -543,8 +543,8 @@ was moved to `%ProgramData%\var\lib\icinga2\certs`.
Old Path | New Path
----------------------------------------------------------------|----------------------------------------------------------------
`%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.crt` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.crt`
`%ProgramData%\etc\icinga2\pki\icinga2-client1.localdomain.key` | `%ProgramData%\var\lib\icinga2\certs\icinga2-client1.localdomain.key`
`%ProgramData%\etc\icinga2\pki\icinga2-agent1.localdomain.crt` | `%ProgramData%\var\lib\icinga2\certs\icinga2-agent1.localdomain.crt`
`%ProgramData%\etc\icinga2\pki\icinga2-agent1.localdomain.key` | `%ProgramData%\var\lib\icinga2\certs\icinga2-agent1.localdomain.key`
`%ProgramData%\etc\icinga2\pki\ca.crt` | `%ProgramData%\var\lib\icinga2\certs\ca.crt`

View File

@ -520,6 +520,16 @@ Service:
## Cluster <a id="technical-concepts-cluster"></a>
This documentation refers to technical roles between cluster
endpoints.
- The `server` or `parent` role accepts incoming connection attempts and handles requests
- The `client` role actively connects to remote endpoints receiving config/commands, requesting certificates, etc.
A client role is not necessarily bound to the Icinga agent.
It may also be a satellite which actively connects to the
master.
### Communication <a id="technical-concepts-cluster-communication"></a>
Icinga 2 uses its own certificate authority (CA) by default. The
@ -565,7 +575,7 @@ signing master.
Icinga 2 v2.8 introduces the possibility to request certificates
from indirectly connected nodes. This is required for multi level
cluster environments with masters, satellites and clients.
cluster environments with masters, satellites and agents.
CSR Signing in general starts with the master setup. This step
ensures that the master is in a working CSR signing state with:
@ -613,7 +623,7 @@ cluster message.
If the child node was not the certificate request origin, it only updates
the cached request for the child node and send another cluster message
down to its child node (e.g. from a satellite to a client).
down to its child node (e.g. from a satellite to an agent).
If no ticket was specified, the signing master waits until the
@ -636,6 +646,10 @@ This mode leaves the node in a semi-configured state. You need
to manually copy the master's public CA key into `/var/lib/icinga2/certs/ca.crt`
on the client before starting Icinga 2.
> **Note**
>
> The `client` in this case can be either a satellite or an agent.
The parent node needs to actively connect to the child node.
Once this connections succeeds, the child node will actively
request a signed certificate.
@ -1028,7 +1042,7 @@ evaluates this in startup and knows on endpoint connect which config zones need
Global zones have a special trust relationship: They are synced to all child zones, be it
a satellite zone or client zone. Since checkable objects such as a Host or a Service object
a satellite zone or agent zone. Since checkable objects such as a Host or a Service object
must have only one endpoint as authority, they cannot be put into a global zone (denied by
the config compiler).
@ -1058,9 +1072,9 @@ is transmitted.
When the master connects to the child zone member(s), this requires more
resources there. Keep this in mind when endpoints are not reachable, the
TCP timeout blocks other resources. Moving a satellite zone in the middle
between masters and agents/clients helps to split the tasks - the master
between masters and agents helps to split the tasks - the master
processes and stores data, deploys configuration and serves the API. The
satellites schedule the checks, connect to the agents/clients and receive
satellites schedule the checks, connect to the agents and receive
check results.
Agents/Clients can also connect to the parent endpoints - be it a master or

Binary file not shown.

Before

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 90 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 74 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 87 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 134 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 144 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 124 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 117 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 24 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 60 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 16 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 19 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 125 KiB

After

Width:  |  Height:  |  Size: 102 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 21 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

View File

@ -92,9 +92,9 @@ int NodeWizardCommand::Run(const boost::program_options::variables_map& vm,
*/
std::string answer;
/* master or satellite/client setup */
/* master or satellite/agent setup */
std::cout << ConsoleColorTag(Console_Bold)
<< "Please specify if this is a satellite/client setup "
<< "Please specify if this is an agent/satellite setup "
<< "('n' installs a master setup)" << ConsoleColorTag(Console_Normal)
<< " [Y/n]: ";
std::getline (std::cin, answer);
@ -110,7 +110,7 @@ int NodeWizardCommand::Run(const boost::program_options::variables_map& vm,
if (choice.Contains("n"))
res = MasterSetup();
else
res = ClientSetup();
res = AgentSatelliteSetup();
if (res != 0)
return res;
@ -127,13 +127,13 @@ int NodeWizardCommand::Run(const boost::program_options::variables_map& vm,
return 0;
}
int NodeWizardCommand::ClientSetup() const
int NodeWizardCommand::AgentSatelliteSetup() const
{
std::string answer;
String choice;
bool connectToParent = false;
std::cout << "Starting the Client/Satellite setup routine...\n\n";
std::cout << "Starting the Agent/Satellite setup routine...\n\n";
/* CN */
std::cout << ConsoleColorTag(Console_Bold)
@ -439,7 +439,7 @@ wizard_ticket:
<< "Reconfiguring Icinga...\n"
<< ConsoleColorTag(Console_Normal);
/* disable the notifications feature on client nodes */
/* disable the notifications feature on agent/satellite nodes */
Log(LogInformation, "cli", "Disabling the Notification feature.");
FeatureUtility::DisableFeatures({ "notification" });
@ -603,7 +603,7 @@ wizard_global_zone_loop_start:
<< ConsoleColorTag(Console_Normal);
}
/* Satellite/Clients should not include the api-users.conf file.
/* Satellite/Agents should not include the api-users.conf file.
* The configuration should instead be managed via config sync or automation tools.
*/
}

View File

@ -27,7 +27,7 @@ public:
boost::program_options::options_description& hiddenDesc) const override;
private:
int ClientSetup() const;
int AgentSatelliteSetup() const;
int MasterSetup() const;
};