# 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](/manual/installation/install#from_the_sources) with SSH2
support. 

::: noteimportant
The minimum supported libssh2 library
version is 1.0.0.
:::

#### 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 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](/manual/appendix/config/zabbix_server)) as `root`
and look for the following line:

    # SSHKeyLocation=

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

    SSHKeyLocation=/home/zabbix/.ssh

Save the file and restart zabbix\_server afterwards.

*/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 a [ssh-keygen](http://en.wikipedia.org/wiki/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 in
not very well-known places (as for system accounts). For example, for
CentOS it's */var/lib/zabbix*, for Debian it's */var/run/zabbix*.

Before starting to generate the keys, an approach to reallocate the home
directory to a better known place (intuitively expected) could be
considered. This will correspond with the *SSHKeyLocation* Zabbix server
configuration parameter mentioned above.

These steps can be skipped if *zabbix* account has been added manually
according to the [installation
section](/manual/installation/install#create_user_account) because in
this case most likely the home directory is already located at
*/home/zabbix*.

To change the setting for the *zabbix* user account all working
processes which are using it have to be stopped:

    # service zabbix-agent stop
    # service zabbix-server stop

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

    # usermod -m -d /home/zabbix zabbix

It's absolutely possible that a home directory did not exist in the old
place (in the CentOS for example), so it should be created at the new
place. 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 now can be started again:

    # service zabbix-agent start
    # service zabbix-server start

Now steps to generate public and private keys can be performed by a
command:

    # 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): 
    Created directory '/home/zabbix/.ssh'.
    Enter passphrase (empty for no passphrase): 
    Enter same passphrase again: 
    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+        |
    +-----------------+

Note: public and private keys (*id\_rsa.pub* and *id\_rsa* respectively)
have been generated by default in the */home/zabbix/.ssh* directory
which corresponds to the Zabbix server *SSHKeyLocation* configuration
parameter.

::: noteimportant
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 command the **public** key file can be installed
on a remote host *10.10.10.10* so that then SSH checks can be performed
with a *root* account:

    # sudo -u zabbix ssh-copy-id root@10.10.10.10
    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.
    root@10.10.10.10's password: 
    Now try logging into the machine, with "ssh 'root@10.10.10.10'", and check in:
      .ssh/authorized_keys
    to make sure we haven't added extra keys that you weren't expecting.

Now it's possible to check the SSH login using the default private key
(*/home/zabbix/.ssh/id\_rsa*) for *zabbix* user account:

    # sudo -u zabbix ssh root@10.10.10.10

If the login is successful, then the configuration part in the shell is
finished and 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.<br>
Multiple commands can be executed one after another by placing them on a
new line. In this case returned values also will be formatted as multi
lined.

![](../../../../../assets/en/manual/config/items/itemtypes/ssh_item.png)

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 format **ssh.run\[<unique short description>,<ip>,<port>,<encoding>\]**|<unique short description> is required and should be unique for all SSH items per host<br>Default port is 22, not the port specified in the interface to which this item is assigned|
|*Authentication method*|One of the "Password" or "Public key"|<|
|*User name*|User name to authenticate on remote host.<br>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](http://en.wikipedia.org/wiki/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<br>*Key passphrase*|Password to authenticate or<br>Passphrase **if** it was used for the private key|Leave the *Key passphrase* field empty if passphrase was not used<br>See also [known issues](/manual/installation/known_issues#ssh_checks) regarding passphrase usage|
|*Executed script*|Executed shell command(s) using SSH remote session|Examples:<br>*date +%s*<br>*service mysql-server status*<br>*ps auxww \| grep httpd \| wc -l*|

::: noteimportant
libssh2 library may truncate executable scripts to
\~32kB.
:::