Installing and Configuring an SL1 Collector

Download this manual as a PDF file

This section describes how to download and install an SL1 Collector, and how to establish a connection between the new SL1 Collector and the SL1 Database Server on the SL1 Nodes page.

The Nodes page and the Node Configuration Utility replace functionality previously found in the Web Configuration utility and the Appliance Manager page in versions of SL1 prior to version 11.2.0.

This section includes the following topics:

Prerequisites

Before installing and configuring an SL1 Collector in your ScienceLogic environment, you must:

  • Have SSH access or console access to each Database Server
  • On each ScienceLogic appliance, know the username and password for access to the console.
  • Ensure that the Database Server opens a port for PhoneHome communication. The default port for this is 7705, but you can use other ports if you prefer.

Workflow for Installing and Configuring an SL1 Collector

The typical workflow for installing and configuring an SL1 Collector includes the following steps:

  1. For existing PhoneHome configurations only: Configure the PhoneHome Database Server. Complete this step only if you are currently using PhoneHome communication with your SL1 Collectors, and you are upgrading to SL1 version 11.2.0 or later from an earlier version of SL1.

    NOTE: If you use a proxy in your PhoneHome configuration, perform the steps in the proxy section before configuring the other steps in the PhoneHome configuration. The remaining configuration steps require the proxy for communication.

    For more information about PhoneHome communication, see Configuring SL1 for PhoneHome Communication.

  2. Download the ISO image containing the SL1 Collector. The ISO includes the Database Server, Administration Portal, and Data Collectors.

  3. Use the ISO to install the Database Server and Administration Portal, if they are not already installed.

  4. Use the ISO to install an SL1 Collector.

  5. Configure the Database Server to accept the collector connection, if this is a new SL1 system.

  6. Connect the SL1 Collector with the SL1 Database Server to enable communication.

Configuring the PhoneHome Database Server (for Existing PhoneHome Configurations Only)

If you are using a new SL1 system or a system that has not previously used PhoneHome communication for collectors, you can skip this section.

When upgrading to SL1 version 11.2.0, a pre-upgrade test in the system update procedure checks for existing PhoneHome Database Servers. Specifically, this test looks for PhoneHome token IDs inside the /home/phonehome0/config.json file, and fails if the value of the id field is less than or equal to "0".

In versions of SL1 prior to version 11.2.0, the primary PhoneHome Database Server was not self-registered with a token, causing it to have an id value of "0".

Therefore, if you are currently using a version of SL1 prior to version 11.2.0 and you are using PhoneHome communication with your SL1 Collectors, you or your SL1 administrator must complete the following one-time manual configuration steps prior to upgrading to version 11.2.0 .

For more information and configuration steps, see Configuring SL1 for PhoneHome Communication.

To register a token for your primary PhoneHome Database Server:

  1. Log in to the console of the Database Server or use SSH to access the server.

  2. To determine if your PhoneHome Database Server is registered, type the following command and locate its id value:

    cat /home/phonehome0/config.json

  3. If a PhoneHome Database Server has an id value of "0", type the following command and locate the id of the current appliance:

    phonehome status

  4. Type the following command and locate the PhoneHome token:

    phonehome token <id from step 3>

  5. Type the following command to register the PhoneHome token:

    phonehome register <token from step 4>

  6. Repeat steps 2-5 for all PhoneHome Database Servers that have an id value of "0".

  7. Type the following command to ensure that all of your PhoneHome Database Servers are synced:

    phonehome sync

  8. Repeat step 2 and confirm that all Database Servers have id values greater than "0".

Do not attempt to upgrade to SL1 version 11.2.0 until all pre-upgrade tests are successful on all PhoneHome Database Servers.

After you have downloaded but not yet installed the ISO, you can also go to the System Updates page (System > Tools > Updates) and check the Preupgrade Status column to determine if the upgrade has successfully passed the pre-upgrade test. If the Preupgrade Status is Incomplete, click the magnifying glass icon () to determine which appliance is failing during the pre-upgrade test. Do not install the upgrade until the Preupgrade Status status displays as Complete.

Downloading the ISO Image ContainingtheSL1 Collector

Before you can install an SL1 Collector, you must first download the SL1 ISO image to your local computer.

The following steps do not affect the performance of the SL1 system. ScienceLogic recommends that you perform these steps at least 3 days before upgrading.

To download the ISO image:

  • Log in to ScienceLogic Support using your ScienceLogic customer account and password to access the site.
  • Select the Product Downloads menu and choose Platform. The Platform Downloads page appears.

  • Click the name of the SL1 version you want to download. The Release Version page appears.

  • Click the link for the "Product Image" you want to download and scroll to the bottom of the page. The Release File Details page appears.
  • Click the Download File button for the ISO file to download the file to your local computer.

Installing an SL1 Collector

Before you can install the SL1 Collector, you will need to use the ISO to install the SL1 Database Server if it is not already installed.

After installing the Database Server, you can then install:

  1. The Administration Portal (if applicable)
  2. The Data Collectors
  3. The Message Collectors (if applicable)

You can use the following instructions to build the Administration Portal, and one or more Data Collectors and Message Collectors.

To install an SL1 Collector:

  1. Boot the collector from the SL1 ISO.
  2. Select Install EM7. The Model Type window appears:

  • Select Collector or Message Collector and then select Continue.
  • The Military Unique Deployment window appears. Do not select  [Enable] on this window if you are not using a Military Unique Deployment.
  • After the installer for the collector is loaded, the Network Configuration window appears:

  1. Enter the following information:
  • IP Address. Type the primary IP address of the collector.
  • Netmask. Type the netmask for the primary IP address of the collector.
  • Gateway. Type the IP address for the network gateway.
  • DNS Server. Type the IP address for the primary Nameserver.
  • Hostname. Type the hostname for the collector.

  1. Select Continue. The System Password window appears:

  1. Type the password for the em7admin user on the operating system and select Continue.
  2. Type the password for the em7admin user again and select Continue.
  3. If you are using a VMware instance, after the collector reboots, follow the instructions to install VMware tools.
  4. Go to the next topic to connect the new collector with the SL1 Database Server.

Connecting an SL1 Collector with the SL1 Database Server

After you install an SL1 Collector, use the Add Node wizard on the Nodes page (Manage > Nodes) to register the collector so that it can communicate with the SL1 Database Server to share its collected data. Part of the setup takes place in the Node Configuration Utility, which has its own user interface separate from the SL1 user interface.

The Nodes page and the Node Configuration Utility replace some of the functionality previously found in the Appliance Manager page and the Web Configuration Utility in versions of SL1 prior to version 11.2.0.

Depending on the type of connection you select in the Add Node wizard, communication between the SL1 Collector and the SL1 Database Server works in one of the following ways:

  • The SL1 Collector establishes an SSH tunnel to the SL1 Database Server. Requests originate from edge to core via TCP, using port 7705 by default. Access must be permitted from the trusted to the untrusted network. Each Data Collector is aligned with an SSH account on the Database Server and uses SSH to communicate with the Database Server. Each SSH account on the Database Server is highly restricted, has no login access, and cannot access a shell or execute commands on the Database Server.

    This method was called the "PhoneHome" method in versions of SL1 prior to version 11.2.0. In the Add Node wizard, the "Collector Initiates | System Accepts" and "Collector Initiates | User Accepts" options use this communication method.

  • The SL1 Database Server initiates communication with each SL1 Collector over an open TCP port. The Database Server periodically pushes configuration data to the Data Collectors and Message Collectors and retrieves data from the Data Collectors and Message Collectors. The benefit of this method is that communication to the Database Server is extremely limited, so the Database Server remains as secure as possible.

    This method was called the "traditional" method in previous versions of SL1. In the Add Node wizard, the "Database Initiates | System Accepts" option uses this communication method.

Configuring a New SL1 System for Communication

If you are using a new SL1 system or a system that has not previously used PhoneHome communication for collectors, you or your SL1 administrator will need to configure each Database Server in the SL1 system to accept these connections.

For more information about PhoneHome communication in previous releases, see Configuring SL1 for PhoneHome Communication.

To enable communication between each Database Server and the new collector:

  1. Log in to the console of the Database Server or use SSH to access the server:

    ssh em7admin@<IP address of Database Server>

  2. Run the following command to ensure that the collector can reach the IP address of the Database Server, which typically involves the use of port 7705:

    sudo phonehome setup -a "<IP address of Database Server: port number>" -n "<name of Database Server>"

    If setup succeeds, a message like the following displays: New database with id 2 successfully added.

After configuring communication between a Database Server and a collector, you can run the following commands to view information about your servers and collectors:

  • To view a list of PhoneHome Database Servers, including their device IDs, names, IP addresses, and port numbers, run the command phonehome list. If you have already connected one or more SL1 Collector devices to the Database Servers, information for those collector devices will also appear.
  • To view a list of only the Database Servers, run the command phonehome destination list.
  • To view information about a specific PhoneHome Database Server, run the command phonehome destination list --id <id>, replacing <id> with the Database Server's device ID.
  • To view information about the PhoneHome configuration of a specific Database Server or SL1 Collector, run the command phonehome view <id>, replacing <id> with the device ID of the Database Server or SL1 Collector.
  • To ensure that the PhoneHome service is active on the Database Server and view additional configuration information about the server, run the command systemctl status phd.service.
  • To view the status of the PhoneHome service on the Database Server or SL1 Collector, run the command phonehome status.
  • If the PhoneHome service is disconnected on a Database Server or SL1 Collector and you want to start it, run the command systemctl start phc.

For more information about other PhoneHome-related commands that you can run, see the section on Using the Command-Line Interface.

Connecting an SL1 Collector to the SL1 Database Server

The Add Node wizard lets you configure your new SL1 Collector so that SL1 can register the SL1 Collector, connect it to the SL1 Database Server, and align it to a new or existing Collector Group.

To register and connect an SL1 Collector to the SL1 Database Server:

  1. On the Registered tab on the Nodes page (Manage > Nodes), click Add Nodes. The Choose Connection Type window of the Add Node wizard appears:

    Depending on your user permissions, you might not see all three connection type options on this window.

  2. Select a connection type for the collector. All connection types require a token that SL1 generates as part of the wizard. A token is a JSON web token (JWT) that contains a set of secure data that SL1 uses to establish communication between the new SL1 Collector and the SL1 Database Server.Your options include:

  • Collector Initiates | System Accepts. In this connection type, the collector establishes an SSH tunnel to the SL1 Database Server. Using this connection type, you copy a token generated by SL1 and add it during Step 3 of this wizard. The token is automatically accepted, and it expires after 30 minutes by default. This is the most commonly used method.

  • Collector Initiates | User Accepts. In this connection type, the collector also establishes an SSH tunnel to the SL1 Database Server. However, this connection type uses the Pending tab, where a user with the right access has to accept the connection request before SL1 can establish the connection. The token does not expire.

  • Database Initiates | System Accepts. In this connection type, the SL1 Database Server initiates communication with the collector over an open TCP port. Port 7707 on the collector must be open for data pull requests from the SL1 Database Server. You might also need to add firewall rules to allow the incoming requests. The token does not expire.

  1. Click Next. The Define Collector Properties window appears:

    This window is the same for all three collector types.

  2. Complete the following fields as needed:

  • Collector Name. Type the name the collector used when registering the collector. SL1 will update this value with the collector hostname.

  • Collector IP Address or Hostname. Type the IP address or the hostname of the collector.

    • For "Collector Initiates | System Accepts" and "Collector Initiates | User Accepts" connection types, this information is optional but recommended, as it is used in Step 3 of the wizard to create a link to the collector's Node Configuration Utility, where you will input the token you generate.

    • For a "Database Initiates | System Accepts" connection type, you must type the IP address in this field so the Database Server can connect to the collector.

  • Collector Description. Type a description of the collector. This field is optional.

  • Collector Group. The new collector must be aligned to an SL1 Collector Group. You have the following options for this field: 

    • Select an existing Collector Group from the drop-down.

    • Create a new Collector Group for the collector by clicking the plus icon (+). On the Add Collector Group modal, you can name the new group and choose to make that Collector Group available to all current and future organizations. You can also limit the Collector Group to specific organizations.

      The All current and future organizations toggle is enabled by default. If you want to limit Organization access to the new Collector Group, disable this toggle and select the organization or organizations from the drop-down.

  • Collector Type. Your options include: 

    • Data Collector. This is the most commonly used type. A Data Collector retrieves a specific set of information from monitored devices. A Data Collector can also work as a Message Collector.

    • Message Collector. A Message Collector receives and processes inbound, asynchronous syslog and trap messages from monitored devices.

  1. Click Generate Token. The Configure Collector window appears:

    You can go back to a previous step at any point in the wizard, but when you click the Generate Token button, SL1 always generates a new token. You cannot retrieve this particular token if you close the Add Node wizard.

    The generated token expires after 30 minutes.

  1. Click the Copy icon () to copy the token in the Token field.

  2. Open the Node Configuration Utility by clicking the Open icon () in the Node Configuration Utility field. The login page for the Node Configuration Utility opens in a new browser window.

    If you did not specify an IP address or a hostname in step 2 of this wizard, you will need to open a new browser window and type the IP address or hostname for the collector, followed by ":7700/node-config", such as "https://10.1.1.100:7700/node-config".

    If the node type is not a collector, the Node Configuration Utility will display the following message: "This page will only be visible if you are on a collector."

  3. Log in to the Node Configuration Utility using the same username and password that you used when you installed the collector. After you log in, the collector and the SL1 Database Server attempt to connect. The connection will fail, which is expected. The Connect Collector page appears with an empty Paste token text field:

  4. Paste the token you copied in step 6 in the Paste token field.

    For "Database Initiates | System Accepts" connection types, if the collector and Database Server are not able to connect, make sure that port 7707 is open between the Database Server and the collector.

    If you did not generate a token, you can click Manual Entry, select User Accepted Connection Request, and add the IP addresses for the Database Server or Servers in the text box.

  5. After pasting the token, click Register or Register Database, based on your choices in the previous step. When the connection is made, a Success dialog displays data specific to the connection type you selected:

    • For a "Collector Initiates | System Accepts" connection type, the Success dialog states that the collector was registered and the connection to the database was initiated.

    • For a "Collector Initiates | User Accepts" connection type, the Success dialog contains a six-digit confirmation code. Click the Copy icon () to copy the confirmation code.

    • For a "Database Initiates | System Accepts" connection type, the dialog states that the collector was configured to accept a connection from the Database Server, and that you need to register the collector in SL1 if you have not already done so. Click the link in the Status dialog to get more information about registering a collector.

  6. Click OK on the Success dialog.

    • For a "Collector Initiates | System Accepts" connection type, the Collector Connection Status page displays details about the collector and the Database Server, along with the connection state, which can be "Connected", "Not Connected", or "Unknown". ("Unknown" indicates that SL1 has not yet completed its first check of the connection state; click Refresh Status after a few moments and the status should update to "Connected".)

    • For a "Collector Initiates | User Accepts" connection type, the Collector Connection Status page displays details about the connection request and the same six-digit confirmation code. Go to step 16, below.

    • For a "Database Initiates | System Accepts" connection type, the Connect Collector page appears, with a message stating that the collector can receive inbound connection requests. Go to step 22, below.

  7. On the Collector Connection Status page, click the expand icon () to view the connection path. The health of each hop in the connection is reported separately, but hops after an unresponsive hop will not be checked. This "Connection Path" information can be useful in diagnosing collector-database connection issues.

  8. To view any changes to the connection status, click Refresh Status.

    If you want to disconnect the collector and close the SSH tunnel between the collector and the Database Server, click Disconnect & Clear Configuration. This action will close the outgoing connection from the collector to all configured destinations, and it will also clear all local configuration. This action cannot be undone.

  9. Close the Node Configuration Utility.

  10. In SL1, go to the Registered tab on the Nodes page, where you can now see the new collector in the list, aligned with the Collector Group you specified in the Add Node wizard. The new collector also displays on the Appliance Manager page (System > Settings > Appliances).

    This is the final step for a "Collector Initiates | System Accepts" connection type.

  11. For a "Collector Initiates | User Accepts" connection type, after you copy the six-digit confirmation code from the Connect Collector page of the Node Configuration Utility, you will need to return to SL1.

  12. On Step 3 of the Add Node wizard, click See Pending Requests. The Pending tab on the Nodes page appears with the pending request.

  13. Select the Actions icon () next to the pending request for the new collector and select Accept. The Accept Request dialog appears.

  14. Paste the six-digit confirmation code from the Connect Collector page of the Node Configuration Utility and click Validate. The Configure Collector dialog displays a summary of the collector information you entered in the Add Node wizard.

  15. Edit the collector information and collector group as needed, and then click Save. The Configure Collector dialog displays a summary of your information.

  16. Click OK. The Registered tab on the Nodes page displays the new collector, aligned with the collector group you specified. The new collector also displays on the Appliance Manager page (System > Settings > Appliances).

    This is the final step for a "Collector Initiates | User Accepts" connection type.

  17. For a "Database Initiates | System Accepts" connection type, after you connect the new collector, you will need to manually register the collector in SL1 by navigating to the Appliance Manager page (System > Settings > Appliances).

  18. Complete the following fields:

    1. Host Name. Type the host name of the collector.

    2. IP Address. Type the loopback IP address of the collector. The loopback IP address is a special, virtual network interface that your computer uses to communicate with itself. This address also allows you to view content on a server in the same way a client would. In most cases, the loopback address is 127.0.0.1, although the loopback address can be any IP address in the 127.0.0.0/8 block.

    3. Model Type. Select the type of appliance (Data Collector or Message Collector) you are registering. 

      When you select either type of collector, the DB User and DB Password fields appear. If the Database Server has different credentials from the collector, type the relevant credentials in these fields.

    4. Description. Type a description for the Data Collector or Message Collector. This field is optional.

  19. Click Save. If the save is successful, the message "Appliance Registered" displays.

  20. If all information is valid and the Database Server can communicate with the Data Collector or Message Collector, the Appliance Manager page displays the SL1 version installed on the collector in the Build column. If the Build column remains blank for longer than five minutes, double-check your settings and network connection.

  21. Perform steps 20-23 for each Data Collector and Message Collector in your PhoneHome configuration.

  22. Finally, align the new collector with the relevant Collector Group by going to the Collector Groups page (System > Settings > Collector Groups).

  23. Click the edit icon () next to the Collector Group you want to use, select the new collector from the Collector Selection field, and click Save.

  24. Go to the Registered tab on the Nodes page, where you can now see the new collector in the list, aligned with the Collector Group you specified.

    This is the final step for a "Database Initiates | System Accepts" connection type.

Managing the Nodes Page

The following topics describe how to use and add information on the Nodes page.

Viewing the List of Registered Nodes

The Registered tab of the Nodes page lets you manage the nodes used for installing SL1 collectors, SL1 instances, and other related appliances. You can also click the Add Node button to connect an SL1 collector to an SL1 Database Server.

The Registered tab of the Nodes page

The Pending tab displays a list of pending requests for establishing a connection between a collector and an SL1 Database Server. The Tokens tab displays a list of existing and expired tokens used for connecting collectors.

The Pending tab and the Tokens tab do not display on an All-In-One SL1 system.

The Nodes page replaces some of the functionality previously found in the Web Configuration utility and the Appliance Manager page.

You can filter the items on this inventory page by typing filter text or selecting filter options in one or more of the filters found above the columns on the page. For more information, see Filtering Inventory Pages.

By default, the Nodes page displays the following about each node:

  • Name. Name of the node.
  • IP . Primary IP address for the node.
  • Status. The node status types include:
  • Available
  • Unavailable
  • Failed Over
  • Available Failed Over
  • Unconfigured
  • Unlicensed
  • Node Type. The node types include: 
  • All-In-One Appliance
  • Application Server (Administration Portal)
  • Compute Node
  • Collector Unit (Data Collector)
  • Database Server
  • Message Collector
  • Storage Node
  • Database Version. Version number of the Database Server for an All-In-One Appliance or a Database Server node.
  • Collector Group . For Data Collectors and All-In-One Appliances, specifies the Collector Group name associated with the node.

In addition, you can click the Grid Settings button and select Column Preferences to add the following columns to the Nodes page:

  • Node ID. Unique numeric ID, automatically assigned by SL1 to each node on the Nodes page.
  • Capacity. For Database Servers, specifies the licensed capacity of the node.
  • Description. Description of the node.
  • Patch Level. Most recent patch version number for the node, where applicable.
  • Release Version. SL1 version running on the node.
  • Version ID. Unique numeric ID, automatically assigned by the platform to each SL1 version.
  • Created. Date and time the node was registered and licensed.
  • Edit User. User who last edited the node's information.
  • Last Edited. Date the node's information was discovered or last edited.
  • Task Manager Paused. Specifies whether the task manager service is paused. This value is updated every two minutes.
  • Needs Reboot. Specifies whether the node requires reboot to add latest kernel or security updates.
  • Allocation. For Data Collectors, specifies the number of devices aligned with the node.
  • Endpoint. SL1 Agent endpoint for the Gen 1 Agent.
  • Collector Group ID. For Data Collectors and All-In-One Appliances, specifies the Collector Group ID associated with the node.

Viewing the Tokens on the Nodes Page

The Tokens tab on the Nodes page lists the existing and expired tokens that get used when connecting a collector. A token is a JSON web token (JWT) that contains a set of secure data that SL1 uses to establish communication between the new SL1 Collector and the SL1 Database Server.

By default, tokens for a "Collector Initiates | System Accepts" connection type have a 30-minute expiration period.

The Tokens tab lists the following:

  • Collector registration details entered by the user at the time of token creation (collector hostname, description)
  • Collector type (Data Collector or Message Collector) and aligned Collector Group
  • Details about the token (including its type, date of creation, and expiration date)

A token inherits organization membership from the Collector Group to which it is aligned to allow multi-tenancy.

Recreating a Token

Expired tokens cannot be recovered on the Tokens tab, but you can recreate an expired token, which lets you generate a new token with the same collector details. Recreating the token actually deletes the existing token, but retains the user-supplied collector registration details to use in the new token.

To recreate an expired token:

  1. Go to the Tokens tab on the Nodes page.
  2. Click the Actions menu () and select Recreate for the expired token. The Recreated Token window appears.

    The Recreated Token window on the Nodes page

  3. Click the Copy button to copy the token, and then paste the copied token into the Node Configuration Utility.