Define remote login account (on GroundWork server)

All of the default SSH-based command definitions in GroundWork use the default username nagios stored in the USER17 macro definition for remote login purposes. Any username can be used. If you wish to define a different username, perform the following steps, otherwise continue to creating a remote login account below.

1. Log in to GroundWork Monitor as a user with the Admin role, e.g., admin/admin.

2. Select Configuration > Nagios Monitoring > Control > Nagios resource macros.

3. From the list of macros, select the USER17 entry, which will cause the main window to be reloaded with the macro value in an edit field at the top of the screen.

4. Change the USER17 value to a desired username value, click Update.

5. After a commit operation (Configuration > Nagios Monitoring > Control > Commit), the new username will be used for all subsequent SSH service definitions that reference the USER17 macro.

Create remote login account (on Remote server)

The SSH username, described above, must have a corresponding user account on each remote server that will be used for monitoring purposes. If the user account does not already exist, it must be created before that system can be accessed by the SSH plugin. User account management routines are platform-specific, you may want to refer to your system documentation for information on how to create a new user. The username assigned to the account must be identical to the username specified in the USER17 macro (the default is nagios), and must also have a home directory to store the .ssh configuration directory and public key. 

1. Login to the Remote server with an administrative account, such as root, (or use sudo).

2. Create the nagios user with the following command, which also makes a home directory:
   

   useradd -m nagios

   CODE

3. Verify the user's home directory is owned by the new user account, and has the user permissions to read, write, and enter the directory. The command below will return similar to drwxr-xr-x 3 nagios nagios 4096 Nov 18 19:57 /home/nagios:

   ls -lad /home/nagios

   CODE

   • Some level of access for the account's primary group are often allowed, and this is typically a matter of local administrative policy. However, some SSH servers are known to prohibit logins for accounts with insufficiently secure home directories (refer to your system's SSHD documentation for details).

   • You may want to assign a password for the user account to allow easier access, although a password is not used by the SSH public key authentication mechanism. For example, the command below is used to assign a password to the default nagios username, which will then prompt for a new user password.
     

     passwd nagios

     It's better not to use passwords at all. Consider using only SSH keys for access to system running SSHD.

4. Now we'll create the SSH directory and set its permissions.

   • Change to the nagios home directory:
     

     cd /home/nagios

     CODE

   • Create the .ssh directory:

     mkdir .ssh

     CODE

   • Change access permissions (owner can read, write and execute):

     chmod 700 .ssh

     CODE

   • Change file ownership and group (e.g., nagios.nagios):

     chown nagios.nagios .ssh

     CODE

5. Once the user account has been created and enabled, verify the user is able to login to the system (with the assigned password), and the user is able to create and edit files in their home directory.

Enable public key authentication (on Remote server)

SSH server configuration mechanisms are system specific, you may need to review your system documentation for more information. Most Linux systems use the open source OpenSSH package, which typically uses a configuration file named /etc/ssh/sshd_config, although its location will often vary by distribution. Most Linux distributions with OpenSSH also have public key authentication enabled by default, however if you need to specifically enable it you can do so by changing or adding a PubkeyAuthentication configuration directive with value of yes.

1. Open a terminal session to the Remote server.

2. Become the root user:

   sudo su -

   CODE

3. Edit the SSHD configuration file:

   vi /etc/ssh/sshd_config

   CODE

4. Locate the entry for PubkeyAuthentication (under # Authentication:) and make sure it's set to yes and not commented out, then save the file:

   PubkeyAuthentication yes

5. Restart the daemon if the directive was modified, for example:

   service sshd restart

   CODE

The public key data in the id_rsa.pub file on the GroundWork server can be copied into the authorized_keys file on the Remote server using any means available. You need to be careful to avoid adding any extra characters such as line feeds or carriage returns. The following is a very simple manual example, and there are many automated systems that handle key distribution which can be used instead. 

Copy public key data (on GroundWork server)

1. Open a terminal session to the GroundWork server.

2. Become the user used to install and run GroundWork (e.g., gwos), and change to the gw8 directory:
   

   sudo su -
   su - gwos
   cd gw8

   CODE

   
   

3. Using the docker cp command, copy the id_rsa.pub public key file to the local directory:

   docker cp dockergw8_nagios_1:/home/nagios/.ssh/id_rsa.pub .

   CODE

4. Listing the contents of the gw8 directory, you should see the id_rsa.pub file:

   ls

   CODE

5. Copy the contents of the file which will be used in the next section, for example, to show the contents on the screen for copy/paste you can use the following command:

   cat id_rsa.pub

   CODE

Paste public key data (to Remote server)

1. Open (or return to) a terminal session to the Remote server.

2. Become the root user, then the nagios user, and change to the .ssh directory:

   sudo su – 
   su – nagios
   cd .ssh

   CODE

3. Edit the authorized_keys file and paste in the previously copied public key from above. You can append it to any existing content (don't overwrite unless you are sure you know it's necessary).

   vi authorized_keys

   CODE

4. Then save the file.

5. Adjust the permissions on the authorized_keys file, as most modern ssh servers require:

   chmod 600 authorized_keys

   CODE

Test SSH login to the Remote server (on GroundWork server)

This process accesses the root shell in the nagios container. Please use Docker commands carefully.

Host key verification is not done from the Nagios container on the GroundWork server, so you do not have to SSH to servers individually and accept the keys. If you want to check the system is set up correctly to run the plugins, you can test as follows:

1. Open (or return to) a terminal session to the GroundWork server.

2. Change to the gw8 directory:

   cd gw8

   CODE

3. Using the docker exec command launch a bash session on the nagios container, you should receive a command prompt as root user on the nagios container (e.g., root@a7ce873cfc8c:/src#):

   docker-compose exec nagios bash

4. Become the nagios user on the nagios container:

   su - nagios

   CODE

5. Enter the command to SSH to the Remote server. You should then be connected to the Remote server from your GroundWork server. To close the connection type exit. You should not be prompted for a password.
   

   ssh <remoteserver>
   exit

   If you set up a different user with the SSH key, just SSH as that user, for example:

   ssh username@remoteserver
   exit

   
   Once the steps above have been successfully completed, the Nagios SSH plugin should be able to seamlessly login to any target host that has the correct username and public key file.

Install plugins (on Remote server)

There are some plugin packages GroundWork supplies for convenience. Please note there are many other packages of Nagios plugins in existence, and you can use them just as well, if not better. Also, it's possible to use the GroundWork Monitor Distributed Agent (GDMA) plugins if GDMA is installed. See the section below Using GDMA Plugins with SSH for more information. 

1. Open a browser to the GroundWork Downloads page, navigate to the section Linux Plugin Packages for SSH Monitoring, and download the installer script and plugins package for your architecture (you will need both files for either 32 or 64 bit).

2. Open a terminal session to your desktop, or where ever the plugin files were downloaded, and copy the downloaded files (each) to the /tmp/ directory on the Remote server.

3. From a terminal session to the Remote server, become the root user:

   sudo su -

   CODE

4. Change to the tmp directory, the location the plugin files were copied to:

   cd /tmp

   CODE

5. Change file permissions, for example:

   chmod +x installplugs64.sh

   CODE

6. Run the script, then verify the files are in the correct directory:
   

   ./installplugs64.sh nagios
   cd /home/nagios/libexec
   ls

   CODE

7. Once all the files have been put into the correct directory on the Remote server, you can verify they will work as expected by logging into the GroundWork server under the configured SSH account, and then providing one of the remote commands as a parameter to an SSH command. This will cause the SSH client to login to the remote host with the user's credentials, execute the specified command, display any output returned and then close the SSH session.
   
   For example, the command check_by_ssh_swap will look at the amount of free swap space in use on the Remote host, and generate a warning if there are less than 100 bytes of free swap space, or generate a critical error if there are less than 50 bytes:

   cd gw8 
   docker-compose exec nagios bash
   su - nagios

   If this command completes successfully, the Nagios SSH plugin commands should also be able to work as expected.

   

   The Perl scripts in the libexec directory are configured to use a Perl interpreter that is expected to be located in /usr/local/groundwork/common/bin, however that directory will not exist on the Remote server by default. You may need to update the Perl scripts to use a different interpreter, or create a symbolic link from an existing Perl interpreter to that directory so that one will be located.

Import SSH profile (from GroundWork UI)

Lastly, in the GroundWork Monitor UI, create a new host to be monitored using SSH profiles. First, import the SSH profiles to make available to hosts you want to monitor with SSH. 

1. In GroundWork, select Configuration > Nagios Monitoring > Profiles.

2. Click Profile importer > Import > SSH.

3. Check the box for service-profile-ssh-unix.xml, and click Import.

4. Then create a new host by selecting Configuration > Nagios Monitoring > Hosts > Host wizard.

5. Enter a Host name, Alias, and the IP address.

6. For Host profile, select host-profile-ssh-unix., click Next >> four times.

7. Commit the configuration by selecting Configuration > Nagios Monitoring > Control > Commit.

8. That’s it. In the Status dashboard (Dashboards > Status), you should start to see functioning GroundWork SSH profile services for the Remote host and information coming in along with performance data.