Adding a new node using SSH is a simple procedure that involves adding our public key to your SSH authorized keys file or specifying a username/password and supplying host details for your server so that we may scan your server for changes.

Adding

  1. To scan a node via SSH click the Discover subnavigation button under the Discover heading.

    w500

  2. Choose Linux / Unix.

    w500

  3. Click the SSH connection type.

    w500

  4. The following screen will allow you to enter in the details for your SSH node.

    w500

    Field Description
    Display Name An alias for the node. Does not need to be the node hostname, but can be.
    Hostname/IP The internet facing hostname/IP address of the node.
    Username The user that you want UpGuard to scan as.
    Port Defaults to port 22.
    Connection Manager Group Can be left as “Default” to have scans performed by our internal SSH connection manager, or changed to the name of another SSH connection manager.
  5. For our servers to communicate with yours, you need to add our public key to your authorized keys file. You can do this with a simple one line command shown in step 4. Simply copy the command found in the box under step 4 and paste it into the console of your server under the user account you wish UpGuard to connect as. For example, to allow UpGuard to connect to my node under the user UpGuard, I would log into that machine as the UpGuard user and paste the command. This appends our public key to that user’s SSH authorized keys file.

Scanning

You should now be ready to scan your machine. Click Continue and you should now see your machine register with UpGuard and begin scanning. The node scan can take anywhere from 5 seconds to 3 minutes depending on the complexity of your node and the operating system type. Once complete you can click the “View Scan” button to view the finished scan.

Troubleshooting

Connection Refused

There are multiple possible reasons for this. The most common are described below.

  1. Can you SSH into the machine yourself?

    Confirm that you can SSH into your node with the given connection details from your own machine first. This will confirm that the node itself can be connected to before going on to diagnose network or firewall issues. If you can’t connect to the node from one of your own machines then you will need to confirm whether the SSH service or daemon is running on the node, and whether the port is being exposed (the details to which are outside of the scope of this document, but easily located online).

  2. Can you SSH into the machine from the internet?

    If you can connect, then you will need to confirm that you can perform the same action from a machine outside of your node’s network. If your node is in a private network behind a company firewall, a desktop or laptop behind a home router, in a virtual machine running with a custom local network, or a node in the cloud with specific network security settings, then you should consider these issues:

    1. Proper port forwarding from externally exposed ports to the port of your node.
    2. Allowing connections on port 22 to your node, or through your network device or firewall, but only from the white listed IP address provided.

Connection could not be established

This error occurs if an initial connection to your node could not be established after attempting for 30 seconds. This situation is similar to the Connection Refused error, but the server or network device that is preventing a connection isn’t deliberately reporting back to us that the connection is being blocked. Refer to the Connection Refused section for more advice on solving this problem.

SSH Authentication Failed

A network connection could be established to your node, but the SSH session was disallowed. A common cause of this problem is a missing or corrupt UpGuard public key entry in the authorized keys file of the user you specified in the connection details. To confirm the correct SSH public key entry exists, log into your node under the user account you specified in the connection details form. Once logged in, you can confirm a UpGuard public key entry exists in that user’s authorized keys file by running the following command:

$ grep upguard $HOME/.ssh/authorized_keys

If no ssh record is printed to the command prompt, or if you want to confirm that the entry is correct, you can check against the public key presented in the website. This can either be accessed from the Nodes page by clicking Add Node, choosing Linux / Unix, selecting SSH and referring to the SSH key presented in step 4.

CentOS Permissions

If StrictModes is set to “yes” in /etc/ssh/sshd_config (the default) then you’ll need to set the following permissions:

$ chmod 700 ~/.ssh
$ chmod 600 ~/.ssh/authorized_keys

For more information, see the CentOS Securing SSH Wiki.

CentOS 6 / SELinux

There is a bug in CentOS 6 / SELinux that results in all client presented certificates to be ignored when SELinux is set to Enforcing. To fix this simply run this command on the target node:

$ restorecon -R -v /root/.ssh
restorecon reset /root/.ssh context system_u:object_r:ssh_home_t:s0->system_u:object_r:home_ssh_t:s0
restorecon reset /root/.ssh/authorized_keys context unconfined_u:object_r:ssh_home_t:s0->system_u:object_r:home_ssh_t:s0

Hostname invalid or DNS lookup failed

The hostname you specified could not be resolved to an IP address. Sometimes this is a result of a hostname being entered incorrectly. To confirm this, navigate to the Nodes page, then next to the node in the question, use the drop down button on the right of the entry to Edit the node. (This page can also be accessed from the Edit Node button in the top right corner of the website when viewing the details of a specific node.) Under the SSH hostname field, confirm that the value entered correctly. Alternatively, confirm that the hostname is not an internal hostname only available to your local network. For instance, to confirm the hostname can be interpreted from the internet you could run the following command on a machine outside of your local network. Here we are testing if the UpGuard website can be resolved:

$ nslookup app.upguard.com
...
Address: 50.18.168.209

Here app.upguard.com could be successfully resolved to an IP address. If your hostname cannot be resolved to a valid IP address then your output might look something more like this:

$ nslookup nonexistent.upguard.com
...
server can't find nonexistent.upguard.com

A quick solution to this problem is to enter the IP address of the node your are adding rather than the hostname, but confirm that the IP address itself is an internet accessible IP address. Alternatively, you could add appropriate internet accessible DNS records for your node. The steps for this are outside the scope of this document, but many hosting providers provide this functionality.

Further Debugging

Fedora/Centos/RHEL check /var/log/secure for errors. Ubuntu based check /var/log/auth for errors.

SSH Alternative - An agent

If adding a node via SSH is proving difficult with your node, or your security policies do not allow an inbound connection of this type, then we recommend you install the Agent on your node instead. In contrast to SSH mode, which uses inbound connections, the Agent exclusively uses outbound network connections over the common HTTPS port (443). One liner installs can be found in the “Add Node” wizard on the website.

IP Whitelist

For more information about domain and IP whitelisting, click here.

Scanning a node using IPv6

The address must be in square brackets e.g. [fe80::1610:9fff:fed7:83e9%en0].

Tags: ssh