You are viewing documentation for the development version, it may be incomplete.
Join our translation project and help translate Zabbix documentation into your native language.

9 SSH checks

Overview

SSH checks are performed as agent-less monitoring. Zabbix agent is not needed for SSH checks.

To perform SSH checks Zabbix server must be initially configured with SSH2 support (libssh or libssh2). See also: Requirements.

Starting with RHEL 8, only libssh is supported. For other distributions, libssh is suggested over libssh2.

Configuration

Passphrase authentication

SSH checks provide two authentication methods - a user/password pair and key-file based.

If you do not intend to use keys, no additional configuration is required, besides linking libssh or libssh2 to Zabbix, if you're building from source.

Key file authentication

To use key based authentication for SSH items, certain changes to the server configuration are required.

Open the Zabbix server configuration file (zabbix_server.conf) as root and look for the following line:

# SSHKeyLocation=

Uncomment it and set the full path to the folder where the public and private keys will be located:

SSHKeyLocation=/home/zabbix/.ssh

Save the file and restart Zabbix server afterwards.

The path /home/zabbix here is the home directory for the zabbix user account, and .ssh is a directory where by default public and private keys will be generated by an ssh-keygen command inside the home directory.

Usually installation packages of Zabbix server from different OS distributions create the zabbix user account with a home directory elsewhere, for example, /var/lib/zabbix (as for system accounts).

Before generating the keys, you could reallocate the home directory to /home/zabbix, so that it corresponds with the SSHKeyLocation Zabbix server configuration parameter mentioned above.

The following steps can be skipped if zabbix account has been added manually according to the installation section. In such a case the home directory for the zabbix account is most likely already /home/zabbix.

To change the home directory of the zabbix user account, all working processes which are using it have to be stopped:

systemctl stop zabbix-agent
       systemctl stop zabbix-server

To change the home directory location with an attempt to move it (if it exists) the following command should be executed:

usermod -m -d /home/zabbix zabbix

It is also possible that a home directory did not exist in the old location, so it should be created at the new location. A safe attempt to do that is:

test -d /home/zabbix || mkdir /home/zabbix

To be sure that all is secure, additional commands could be executed to set permissions to the home directory:

chown zabbix:zabbix /home/zabbix
       chmod 700 /home/zabbix

Previously stopped processes can now be started again:

systemctl start zabbix-agent
       systemctl start zabbix-server

Now, the steps to generate the public and private keys can be performed with the following commands (for better readability, command prompts are commented out):

sudo -u zabbix ssh-keygen -t rsa
       # Generating public/private rsa key pair.
       # Enter file in which to save the key (/home/zabbix/.ssh/id_rsa):
       /home/zabbix/.ssh/id_rsa
       # Enter passphrase (empty for no passphrase):
       <Leave empty>
       # Enter same passphrase again: 
       <Leave empty>
       # Your identification has been saved in /home/zabbix/.ssh/id_rsa.
       # Your public key has been saved in /home/zabbix/.ssh/id_rsa.pub.
       # The key fingerprint is:
       # 90:af:e4:c7:e3:f0:2e:5a:8d:ab:48:a2:0c:92:30:b9 zabbix@it0
       # The key's randomart image is:
       # +--[ RSA 2048]----+
       # |                 |
       # |       .         |
       # |      o          |
       # | .     o         |
       # |+     . S        |
       # |.+   o =         |
       # |E .   * =        |
       # |=o . ..* .       |
       # |... oo.o+        |
       # +-----------------+

The public and private keys (id_rsa.pub and id_rsa) have been generated by default in the /home/zabbix/.ssh directory, which corresponds to the Zabbix server SSHKeyLocation configuration parameter.

Key types other than "rsa" may be supported by the ssh-keygen tool and SSH servers but they may not be supported by libssh2 used by Zabbix.

Shell configuration form

This step should be performed only once for every host that will be monitored by SSH checks.

By using the following commands, the public key file can be installed on a remote host 10.10.10.10, so that the SSH checks can be performed with a root account (for better readability, command prompts are commented out):

sudo -u zabbix ssh-copy-id [email protected]
       # The authenticity of host '10.10.10.10 (10.10.10.10)' can't be established.
       # RSA key fingerprint is 38:ba:f2:a4:b5:d9:8f:52:00:09:f7:1f:75:cc:0b:46.
       # Are you sure you want to continue connecting (yes/no)?
       yes
       # Warning: Permanently added '10.10.10.10' (RSA) to the list of known hosts.
       # [email protected]'s password:
       <Enter root password>
       # Now try logging into the machine, with "ssh '[email protected]'",
       # and check to make sure that only the key(s) you wanted were added.

Now it is possible to check the SSH login using the default private key (/home/zabbix/.ssh/id_rsa) for the zabbix user account:

sudo -u zabbix ssh [email protected]

If the login is successful, then the configuration part in the shell is finished and the remote SSH session can be closed.

Item configuration

Actual command(s) to be executed must be placed in the Executed script field in the item configuration. Multiple commands can be executed one after another by placing them on a new line. In this case returned values will also be formatted as multilined.

All mandatory input fields are marked with a red asterisk.

The fields that require specific information for SSH items are:

Parameter Description Comments
Type Select SSH agent here.
Key Unique (per host) item key in the format ssh.run[unique short description,<ip>,<port>,<encoding>,<ssh options>] unique short description is required and should be unique for each SSH item per host.

Default port is 22, not the port specified in the interface to which this item is assigned.

ssh options allow to pass additional SSH options in the format key1=value1;key2=value2,value3. Multiple values for one key can be passed separated by comma (in this case, the parameter must be quoted); multiple option keys can be passed separated by semicolon.

The following option keys are supported: KexAlgorithms, HostkeyAlgorithms, Ciphers, MACs, PubkeyAcceptedKeyTypes. Option key and value support depends on the SSH library (for example, PubkeyAcceptedKeyTypes is supported only with libssh); if an option is not supported, an error will be returned, and the item will become unsupported.

Note that "+" sign for appending cipher settings and "!" for disabling specific cipher settings (as in GnuTLS and OpenSSL) are not supported.

Examples:
=> ssh.run[KexAlgorithms,127.0.0.1,,,Ciphers=aes128-ctr]
=> ssh.run[KexAlgorithms,,,,"KexAlgorithms=diffie-hellman-group1-sha1;HostkeyAlgorithms=ssh-rsa,ssh-dss,ecdh-sha2-nistp256"]
=> ssh.run[PubkeyAcceptedKeyTypes,127.0.0.1,,,PubkeyAcceptedKeyTypes=ssh-rsa]
Authentication method One of the "Password" or "Public key".
User name User name (up to 255 characters) to authenticate on remote host. Required.
Public key file File name of public key if Authentication method is "Public key". Required. Example: id_rsa.pub - default public key file name generated by a command ssh-keygen.
Private key file File name of private key if Authentication method is "Public key". Required. Example: id_rsa - default private key file name.
Password or
Key passphrase
Password (up to 255 characters) to authenticate or
Passphrase if it was used for the private key.
Leave the Key passphrase field empty if passphrase was not used.
See also known issues regarding passphrase usage.
Executed script Executed shell command(s) using SSH remote session. The return value of the executed shell command(s) is limited to 16MB (including trailing whitespace that is truncated); database limits also apply.

Note that the libssh2 library may truncate executable scripts to ~32kB.

Examples:
date +%s
systemctl status mysql-server
ps auxww | grep httpd | wc -l