Configuring SL1 for PhoneHome Communication

This section explains how to configure SL1 to use PhoneHome Communication.

Use the following menu options to navigate the SL1 user interface:

• To view a pop-out list of menu options, click the menu icon ([Original reference image unavailable: menu icon]).
• To view a page containing all the menu options, click the Advanced menu icon ([Original reference image unavailable: AdvancedMenu]).

The following topics cover the details of configuring PhoneHome Communication:

What is PhoneHome Communication?

SL1 supports two methods for communication between Database Servers and the Data Collectors and Message Collectors in a system:

The traditional method, where the Database Server initiates communication with each Data Collector and Message Collector. The Database Server periodically pushes configuration data to the Data Collectors and Message Collectors and retrieves data from the Data Collectors and Message Collectors.

[Original reference image unavailable: Traditional Method Overview 576x412]

The benefit of this method is that communication to the Database Server is extremely limited, so the Database Server remains as secure as possible.

The PhoneHome method ,where the Data Collectors and Message Collectors initiate communication with the Database Server. The Data Collectors and Message Collectors create an SSH tunnel. The Database Server uses the SSH tunnel to periodically push configuration data to the Data Collectors and Message Collectors and retrieve data from the Data Collectors and Message Collectors.

[Original reference image unavailable: PhoneHome Method Overview 576x355]

The benefits of this method are that no firewall rules must be added on the network that contains the Data Collectors, and no new TCP ports are opened on the network that contains the Data Collectors.

The PhoneHome configuration uses public key/private key authentication to maintain the security of the Database Server. 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.

Prerequisites

Before configuring PhoneHome communication in your ScienceLogic environment, you must:

• Have SSH access or console access to each database.
• On each ScienceLogic appliance, know the username and password for access to the console as em7admin.
• Ensure that the Database Server opens a port for PhoneHome communication. The default port used by the Configuration Utility is 7705, but you can use other ports besides 7705.

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.

Overview of the PhoneHome Configuration

For a configuration that includes one or more Database Servers, perform the following steps to use PhoneHome communications:

1. Configure one or more Database Servers for PhoneHome. Each Database Server must have SL1 installed, have an IP address, and be licensed with ScienceLogic. 

NOTE: If you are using a High Availability and Disaster Recovery configuration, see Configuring PhoneHome for High Availability and Disaster Recovery to configure Database Servers.

2. Configure the Data Collectors and Message Collectors for PhoneHome. Each Data Collector or Message Collector must have SL1 installed and have an IP address.
3. Define the Database Server associated with each Data Collector or Message Collector appliance.
4. Register the Data Collectors and Message Collectors in SL1.

5. As needed, define port forwarding for each collector to use SSH from the Database Server to access that Data Collector or Message Collector.

6. See the Troubleshooting section for additional help.

NOTE: You do not need to license collectors if your SL1 system is built from the 8.1.2 ISO or later. If your SL1 system is built from the 8.1.1 ISO or earlier, you will have to license each Data Collector and Message Collector. For details on licensing Data Collectors and Message Collectors, see the Licensing an Appliance chapter in the 7.8 version of the Installation and Initial Configuration manual.

Configuring the Database Server for PhoneHome

In PhoneHome communication, the Database Server that communicates with the Data Collectors and the optional Message Collectors is known as the Control Node. The Control Node stores all the configuration information for the PhoneHome configuration.

In 8.14.0 or later releases, Phonehome configuration is stored in tables on the Database Server. The information is accessible to all Database Servers in the SL1 system. Any Database Server server in the SL1 system can provide network access, and therefore there is no need for a fixed control node.

NOTE: In 8.14.0 or later releases, there is no Control Node.

NOTE: In a high-availability or disaster recovery system, the Control Node is usually also the primary Database Server. For more information about high availability and disaster recovery configuration, see Configuring PhoneHome for High Availability and Disaster Recovery.

To configure the Control Node Database Server for PhoneHome communication, you must first perform the following required steps:

• Install the SL1 on the Database Server.
• Assign an IP address to the Database Server.
• License the Database Server with ScienceLogic. For more information, see Licensing and Configuring a Database Server.

Next, configure the Control Node Database Server for PhoneHome communication:

1. Go to the console of the Database Server or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.

3. For the Database Server, you must open a port to accept incoming connection requests. To do this, type the following at the shell prompt:

sudo phonehome open-control-port port_number

where port_number is an unused port number greater than 1000. The Configuration Utility uses port 7705 as the default port. If you want to use the default port, specify 7705 in this command. To use a different port, specify that port number in this command.

4. To define the Database Server (to itself), type the following at the shell prompt:

sudo phonehome add database

5. Review the output, which should look like the following:

Created local: #0

Reloading sshd configurations

Created database: #11

Changing password for user: "phonehome11"

Created Device Id: "11"

Created token: "phonehome://11@71.97.6.197/ee4sdRRK8yNu"

6. Note the ID number for the database (11 in our example).

7. If the database is behind a firewall, you need to define the public-facing IP address of the Database Server and also define the port to use for SSH communication from PhoneHome servers to the Database Server. To do this, type the following at the shell prompt:

sudo phonehome set appliance_ID -ip=IP_address -port=port_number

where appliance_ID is the value you noted in step 6, IP_address is the public-facing IP address, and port_number is the port you want to use for SSH communication to and from the Database Server.

For example:

sudo phonehome set 11 -ip=71.197.6.197 -port=7705

8. You must now configure the Data Collectors and Message Collectors in your network. To do this, go the next section.

Configuring the Data Collectors and Message Collectors for PhoneHome

This section describes how to configure a Data Collector and a Message Collector for use in a PhoneHome configuration.

Before configuring a Data Collector and a Message Collector for use in a PhoneHome configuration, you must first perform the following required steps:

• Install SL1 on each Data Collector and Message Collector
• Assign an IP address to each Data Collector and Message Collector

NOTE: If your PhoneHome configuration uses proxy servers, do not use this section to configure a Data Collector or Message Collector. See the section on proxy servers instead.

To configure a Data Collector or Message Collector as part of a PhoneHome configuration:

• On the Data Collector or Message Collector, log in to the Web Configuration Utility using any web browser supported by SL1. The address of the Web Configuration Utility is in the following format:

https://ip_address_of_collector:7700

2. Type the address of the Web Configuration Utility in the Address bar of your browser, replacing "ip-address-of-appliance" with the IP address of the Data Collector or Message Collector.
3. When prompted to enter your user name and password, log in as the "em7admin" user with either the default password of em7admin or the password you configured.

[Original reference image unavailable: SLAdmin login 432x178]

4. After you log in, the Configuration Utilities page appears:

[Original reference image unavailable: scilo admin collector 432x326]

5. Click the PhoneHome button. The PhoneHome - Collector page appears.

[Original reference image unavailable: collector1 576x244]

6. Complete the following fields:

• Hostname/IP. Type the Hostname or IP address of the Database Server that is configured for PhoneHome.
• Port (if not 7705). Optional. Port number for SSH communications with the Database Server that is configured for PhoneHome. If you are using a port other than 7705 on the Database Server, type the port number in this field. Otherwise, leave this field blank.

• Make request with the Web Configuration Utility via HTTPS. Optional. If you select this checkbox, the Data Collector sends the PhoneHome request to the Database Server using an HTTPS request. The Data Collector sends the request directly to the ScienceLogic Web Configuration Utility (port 7700) on the Database Server. This option works only if the Data Collector has direct access to port 7700 on the Database Server. If you do not select this checkbox, requests are made via SSH.

NOTE: The option Make request with the Web Configuration Utility via HTTPS was removed in 8.14.0. In versions of SL1 of 8.14.0 or later, this option does not appear in the Web Configuration Utility page for PhoneHome.

• Verify SSL Cert. Optional. When you use HTTPS, the Database Server sends an SSL certificate. If the certificate is from a Certificate Authority and must be verified, select this checkbox. If the certificate is internal and does not require verification, do not select this checkbox.

7. Click the Send Connection Request button to send the request from the Data Collector to the Database Server that is configured for PhoneHome. After clicking the Send Connection Request button, the PhoneHome - Collector page displays the status Pending database approval.

NOTE: Do not close the browser window or navigate away from this page while the connection request is being processed.

8. In a new browser window, open the ScienceLogic Web Configuration Utility for the Database Server. To do this, type the following, replacing "ip-address-of-database" with the IP address of the Database Server:

https://ip_address_of_database:7700

• When prompted to enter your user name and password, log in as the "em7admin" user with either the default password of em7admin or the password you configured. The main Configuration Utility page appears.

• Click the PhoneHome button. The PhoneHome Database - Master page appears.

[Original reference image unavailable: db approve 576x357]

• Note that the list of Collectors includes a request. Click the Accept button for that collector. The Status for the Collector now displays as Approved.

• On the Data Collector or Message Collector, open the ScienceLogic Web Configuration Utility and click the PhoneHome button. The PhoneHome - Collector page appears:

[Original reference image unavailable: collector3 576x245]

13. Click the [Check Approval] button. Note that the Status message is now Configured - ID [phonehome_user_number].
14. If you refresh the page, the status field displays the message Synced and Connected.

If you have a large number of collectors, you can perform the following steps to approve multiple collectors at the same time:

• On each Data Collector or Message Collector, follow steps 1-7 in the previous procedure to send the connection request for each collector.
• Open the ScienceLogic Web Configuration Utility for the Database Server and click the PhoneHome button.

• Click the Accept All Collector Requests button.
• Open the ScienceLogic Web Configuration Utility for each collector, click the PhoneHome button, and then click the Check Approval button.
• Repeat step 4 until you have approved all of your collectors.

Registering the Data Collectors and Message Collectors

NOTE: Perform the steps in this section after you have successfully established a PhoneHome connection between Data Collectors or Message Collectors and the main Database Server. The steps in this section ensure that the SL1 system uses the loopback address that is assigned to each Data Collector and Message Collector upon successful completion of a phonehome connection request.

In this section:

• In the Web Configuration Utility, you must define the Database Server associated with each Data Collector or Message Collector appliance.
• In SL1, you must register the Data Collectors or Message Collectors with the main Database Server.

Define the Database Server for Each Collector

You must perform the following steps in the Web Configuration Utility to configure a Data Collector or a Message Collector:

• Log in to the Web Configuration Utility on the Data Collector or the Message Collector. The Configuration Utilities page appears.

• Click the Device Settings button. The Settings page appears.

[Original reference image unavailable: Image of the Device Settings page]

3. On the Settings page, update the following field:

• Database IP Address. The IP address of the ScienceLogic Database Server(s). If more than one Database Server will manage this appliance, type the IP addresses of the Database Servers, separated by commas. You cannot paste an IP address into this field.

• Click the Save button.
• Click the Logout button to log out of the Web Configuration Utility for this collector.
• Perform steps 1-5 for each Data Collector and Message Collector in your PhoneHome configuration.

Register the Collectors with the Main Database Server

In SL1, to register a Data Collector or Message Collector with the main Database Server:

• In the address bar of your browser, type the IP address of the SL1 appliance that provides the user interface for your SL1 system. The user interface is provided by either the Database Server or an Administration Portal. The login page appears:

[Original reference image unavailable: login page 576x205]

• Log in as the "em7admin" user with the password "em7admin" (or the password you configured).
• If this is your first successful login, you will be asked to agree to the End-user License Agreement. Read the End-user License Agreement and then click the I Agree to The Terms Outlined Above button.

• Go to the Appliance Manager page (System > Settings > Appliances):

[Original reference image unavailable: add collector to em7 576x98]

• Complete the following fields:

• Host Name. Type the host name of the Data Collector or Message Collector.
• IP Address. Type the loopback IP address of the Data Collector or Message 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.

TIP: If you go to the Web Configuration Utility of the Database Server and click the PhoneHome button, you can view a list of all the connected collectors, along with their IDs. The ID indicates the loopback address. For example, if the ID of a given collector is 12, then its loopback address is 127.0.0.12.

• Model Type. Select the type of appliance (Data Collector or Message Collector) you are registering.
• Description. Type a description for the Data Collector or Message Collector. This field is optional.

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

• If all information is valid and the Database Server can communicate with the Data Collector or Message Collector, the Appliance Manager page displays the ScienceLogic 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.
• Perform these steps for each Data Collector and Message Collector in your PhoneHome configuration.

Defining Port Forwarding

If you define port forwarding for each Data Collector or Message Collector in the PhoneHome configuration, you can use SSH from the Database Server to access the Data Collector or Message Collector.

To define port forwarding:

1. Either go to the console of the Database Server or use SSH to access the server.

2. Log in as user em7admin with the password you configured during setup.
3. For each Data Collector and/or Message Collector, type the following at the shell prompt:

sudo phonehome set appliance_ID -forwards=port_number

where:

• appliance_ID is device ID for the Data Collector or Message Collector.
• port_number is the port you want to use for SSH communication from the Database Server to the Data Collector or Message Collector.

For example:

sudo phonehome set 12 -forwards=22

4. For every other server in the PhoneHome configuration, go to the console of the Database Server or use SSH to access the server.
5. Log in as user em7admin with the password you configured during setup.
6. Type the following at the shell prompt:

sudo phonehome sync

7. Now, whenever you are SSHed in to the Database Server, you can SSH to the Data Collector or Message Collector.

8. To use the forward port, append "100" to the front of the port you defined in step #3 and use the loopback IP of the Data Collector or Message Collector using port 10022:

ssh –p 10022 root@127.0.0.12

Using Custom Options for AutoSSH

By default, SL1 stores settings for AutoSSH for PhoneHome configurations in the file /opt/em7/backend/phonehome/em7_ph_tunnels on each Data Collector and Message Collector in your configuration.

If you want to use custom AutoSSH settings for a specific Data Collector or Message Collector in your configuration, you can create the file /etc/phonehome/local.conf and define custom AutoSSH options for that server.

To define custom SSH options for a server:

• Log in to the console of the Data Collector or Message Collector as the root user.

• Open the file /etc/phonehome/local.confg with a text editor like vi:

vi /etc/phonehome/local.conf

• Add one or more custom settings for AutoSSH. You can define:

• TCPKeepAlive = "yes or no". Specifies whether the client will send a null packet to the server (to keep the connection alive). Uses the TCP layer to send the packet. The default value is "no". If you set this value to zero (0), this feature is disabled. Your connection will drop if idle for too long.

• • ServerAliveInterval = "number of seconds". The number of seconds the client will wait before sending a null packet to the server (to keep the connection alive). Uses the SSH layer to send the packet. The default value is "10". If you set this value to zero (0), this feature is disabled.

• StrictHostKeyChecking = "yes or no". If this flag is set to “yes”, AutoSSH will never automatically add host keys to AutoSSH configuration and will refuse to connect to hosts whose host key has changed. This option forces the user to manually add all new hosts. If this flag is set to “no”, ssh will automatically add new host keys to the known hosts files. The default value is "no".
• ServerAliveCountMax = "number of messages". The maximum number of unacknowledged null packets the client will send to the server (to keep the connection alive). After the maximum number of unacknolwedged null packets, the client will drop the SSH connection to the server. The default value is "2". If you set this value to zero (0), this feature is disabled. Your connection will drop if idle for too long.
• CUSTOM_PARAMS = "-o parameter = argument". Any additional SSH parameters can be configured with this option. For example:

CUSTOM_PARAMS="-o ExitOnForwardFailure=yes"

NOTE: To determine the format for entries in the /etc/phonehome/loca.confg file, see the file /opt/em7/backend/phonehome/em7_ph_tunnels.

• Save your changes and exit the file.

Configuring PhoneHome for High Availability and Disaster Recovery

This section describes how to configure the Database Servers in your system for use in a PhoneHome configuration.

NOTE: You can use the same Database Servers in both a PhoneHome configuration and a traditional configuration.

After performing the steps in this section, go the section on Configuring the Data Collectors and Message Collectors to complete the configuration.

What is the Control Node?

In a PhoneHome configuration, the Control Node is the Database Server that communicates with the Data Collectors and the optional Message Collectors. This Database Server stores all the configuration information for the PhoneHome configuration.

In a high-availability or disaster recovery system, the Control Node is usually also the primary Database Server .

In 8.14.0 or later releases, Phonehome configuration is stored in tables on the Database Server. The information is accessible to all Database Servers in the SL1 system. Any Database Server server in the SL1 system can provide network access, and therefore there is no need for a fixed control node.

NOTE: In 8.14.0 or later releases, there is no Control Node.

Configuring the Control Node Database Server for High Availability and Disaster Recovery

To configure the Control Node for PhoneHome communication:

1. Go to the console of the Control Node Database Server or use SSH to access the server.

2. 2. Log in as user em7admin with the password you configured during setup.
   3. For the Control Node Database Server, you must first open a port to accept incoming connection requests. To do this, type the following at the shell prompt:

sudo phonehome open-control-port port_number

where port_number is an unused port number greater than 1000. The default value in the Configuration Utility is 7705. If you want to use the default port later in the Configuration Utility, specify "7705" in this command.

4. To define the Control Node Database Server (to itself), type the following at the shell prompt:

sudo phonehome add database

5. Review the output, which should look like the following:

Created local: #0

Reloading sshd configurations

Created database: #11

Changing password for user: "phonehome11"

Created Device Id: "11"

Created token: "phonehome://11@71.97.6.197/ee4sdRRK8yNu"

6. Note the ID number for the Control Node (11 in our example).

7. To define the public-facing IP address of the Control Node Database Server and the port to use for SSH communication from PhoneHome servers to the Control Node Database Server, type the following at the shell prompt:

sudo phonehome set appliance_ID -ip=IP_address -port=port_number

where port_number is an unused port number greater than 1000. The Configuration Utility uses port 7705 as the default port. If you want to use the default port, specify 7705 in this command. To use a different port, specify that port number in this command.

For example:

sudo phonehome set 11 -ip=71.197.6.197 -port=7705

8. If your SL1 System uses multiple databases for high availability and/or disaster recovery, you must create a record for the secondary Database Server on the Control Node Database Server. To do so, type the following at the shell prompt:

sudo phonehome add database

9. The output will look like this:

Reloading sshd configurations

Created database: #13

Changing password for user: "phonehome13"

Created Device Id: "13"

Created token: "phonehome://13@10.64.68.31:22/GmHtYvDd9O0V"

10. Note the ID number for the secondary Database Server. You will need this value later in the configuration.
11. Copy and save the token for the secondary Database Server. You will need this value later in the configuration.

12. To define the public-facing IP address of the secondary Database Server and the port to use for SSH communications from PhoneHome servers to the secondary Database Server, type the following at the shell prompt:

sudo phonehome set appliance_ID -ip=IP_address -port=port_number

where:

• appliance_ID is the value you noted in step 5.
• IP_address is the public-facing IP address.
• port_number is the port you want to use for SSH communication to and from the Control Node Database Server.

For example, we could enter:

sudo phonehome set 13 -ip=71.197.6.198 -port=7705

Configuring the Secondary Database Server for High Availability and Disaster Recovery

To configure a secondary Database Server as part of a PhoneHome configuration:

1. Either go to the console of the secondary Database Server or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.

3. 3. For the secondary Database Server, you must first open a port to accept incoming connection requests. To do this, type the following at the shell prompt:

sudo phonehome open-control-port port_number

where:

3. • port_number is an unused port number greater than 1000. The default value in the Configuration Utility is 7705. If you want to use the default value, specify "7705".

NOTE: ScienceLogic recommends that you use the same port number on each database in your PhoneHome configuration.

4. To register the secondary Database Server, type the following at the shell prompt:

sudo phonehome register appliance_token

where:

• appliance_token is the URL you saved during step 10 in the section Configuring the Control Node Database Server.

5. The output looks like this:

Registered device successfully

6. Type the following at the shell prompt:

sudo phonehome sync

7. The output looks like this:

Started synchronization

Synchronized: collectors

Synchronized: databases

Reloading sshd configurations

Finished synchronizations

Configuring Data Collectors and Message Collectors for High Availability and Disaster Recovery

You must now configure the Data Collectors and Message Collectors in your network. To do this, see Configuring the Data Collectors and Message Collectors.

NOTE: If your PhoneHome configuration uses proxy servers, do not use this section to configure a Data Collector or Message Collector. See the section on proxy servers instead.

Syncing the High Availability and Disaster Recovery System

After adding Data Collector(s) or Message Collector(s) to your PhoneHome configuration, you must once again execute the sync command on all Database Servers and then on the newly configured Collectors in the PhoneHome configuration.

To sync your PhoneHome configuration:

1. Either go to the console of the Database Server (or the new Collectors) or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.

3. At the shell prompt, type the following:

sudo phonehome sync

4. Perform these steps on each Database Server, Data Collector, and Message Collector in your PhoneHome configuration.

Adding a New Secondary Database Server

To add a new secondary Database Server to an existing PhoneHome configuration:

• On the primary Database Server (the Control Node), perform steps 15-19 from the section Configuring the Primary Database Server. These are the steps that define the secondary Database Server, including saving the token and saving the new configuration.

• On the new secondary Database Server, perform the steps from the section Configuring the Secondary Database Server for High Availability and Disaster Recovery.
• For each Data Collector and optional Message Collector, either go to the console of the SL1 appliance or use SSH to access the Data Collector. Log in as "em7admin".
• At the shell prompt, type the following:

phonehome sync

• Perform steps 3 and 4 on each Data Collector and Message Collector in the PhoneHome configuration.
• Either go to the console of the SL1 appliance or use SSH to access the new secondary Database Server. Log in as "root".

• At the shell prompt, type the following:

phonehome status

• The new secondary Database Server should be connected to each Data Collector in the PhoneHome configuration.

Configuring One or More Proxy Servers

If your organization requires that you use a proxy for outbound requests, you can configure one or more Data Collectors to act as proxy servers. These proxy servers will sit between the Data Collectors in your PhoneHome configuration and the Database Server in your PhoneHome configuration.

To use one or more Data Collectors as proxy servers in a PhoneHome configuration:

• Ensure that the SSH port is open on each Data Collector that acts as a proxy server.
• Ensure that the SSH port is open on each Database Server in the PhoneHome configuration.

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

To configure your PhoneHome configuration to use a proxy server, you must:

1. Configure a Database Server for PhoneHome configuration as either a stand-alone Database Server (Configuring the Database Servers) or a High Availability Database Server (Configuring the Database Servers for High Availability)
2. Edit the ssh_config file.
3. Use the command line to configure Data Collectors that connect via proxy.
4. Copy the SSH key to each proxy.
5. Synchronize the Data Collectors with the Database Server.

Editing ssh_config

1. Either go to the console of the Data Collector that will be part of the PhoneHome configuration or use SSH to access the server.

NOTE: Perform these steps on the Data Collector that will be part of the PhoneHome configuration, not on the Data Collector that will serve as a proxy server.

2. Log in as user em7admin with the password you configured during setup.
3. Open the file /etc/ssh/ssh_config with vi or another text editor:

sudo vi /etc/ssh/ssh_config

4. Add the following lines to the file:

Host hostname_of_primary_Database_Server

ProxyCommand ssh -q em7admin@proxy_hostname nc %h %p

where:

hostname_of_primary_Database_Server is the hostname for the primary Database Server.

proxy_hostname is the hostname of the proxy server that directly communicates with the Database Server. If you have a chain of proxy servers, this value is the hostname of the last proxy server in that chain (the proxy server that connects to the Database Server).

NOTE: If you use hostnames to configure proxy servers, you must use hostnames for all PhoneHome configuration. If you use IP addresses to configure proxy servers, you must use IP addresses for all PhoneHome configuration. You cannot mix hostnames and IP addresses in ssh_config and in PhoneHome configuration.

5. If applicable, for all secondary databases, add the following lines to the file:

Host hostname_of_secondary_Database_Server

ProxyCommand ssh -q em7admin@proxy_hostname nc %h %p

where:

hostname_of_secondary_Database_Server is the hostname for the secondary Database Server.

proxy_hostname is the hostname of the proxy server that directly communicates with the secondary Database Server. If you have a chain of proxy servers, this value is the hostname of the last proxy server in that chain (the proxy server that connects to the Database Server).

6. If you have more than one proxy server, add the following lines to the file:

Host hostname_of_proxy_server

ProxyCommand ssh -q em7admin@proxy_hostname nc %h %p

where:

hostname_of_proxy_server is the hostname of the current proxy server (the proxy server you are creating an entry for). For example, you could create an entry for "ProxyServer2".

proxy_hostname is the hostname of the proxy server that is previous in the chain and communicates with the current proxy server. If your entry is for "ProxyServer2", you would specify "ProxyServer1" in this field.

For example, if you had the following configuration:

PhoneHome Data Collector -> ProxyServer1 -> ProxyServer2 -> ProxyServer3 -> Database Server

You would add the following entries to /etc/ssh/ssh_config:

Host ProxyServer2

ProxyCommand ssh -q em7admin@ProxyServer1 nc %h %p

Host ProxyServer3

ProxyCommand ssh -q em7admin@ProxyServer2 nc %h %p

Host EM7_DB1

ProxyCommand ssh -q em7admin@ProxyServer3 nc %h %p

For another example, if you had the following configuration:

PhoneHome Data Collector -> ProxyServer1 -> ProxyServer2 -> ProxyServer3 -> primary Database Server

PhoneHome Data Collector -> ProxyServer1 -> ProxyServer2 -> ProxyServer3 -> secondary Database Server

You would add the following entries to /etc/ssh/ssh_config:

Host ProxyServer2

ProxyCommand ssh -q em7admin@ProxyServer1 nc %h %p

Host ProxyServer3

ProxyCommand ssh -q em7admin@ProxyServer2 nc %h %p

Host EM7_DB1

ProxyCommand ssh -q em7admin@ProxyServer3 nc %h %p

Host EM7_DB2

ProxyCommand ssh -q em7admin@ProxyServer3 nc %h %p

7. Save (:wq) your changes to the /etc/ssh/ssh_config file.

Configuring Data Collectors that Connect to the PhoneHome Database Server Through a Proxy

To configure a Data Collector that connect to the PhoneHome Database Server through a Proxy:

1. Either go to the console of the Database Server or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.
3. For the Database Server, you must first open a port to accept incoming connection requests. To do this, type the following at the shell prompt:

sudo phonehome open-control-port port_number

where:

• port_number is an unused port number greater than 1000.

4. To define the Data Collector (to the Database Server), type the following at the shell prompt:

sudo phonehome add collector

5. The output will look like this:

Created collector: #12

Changing password for user: "phonehome12"

Created Device Id: "12"

Created token: "phonehome://12@10.64.68.31:22/om3Odt3iPEAD

6. Note the token for the Data Collector.
7. Either go to the console of the Data Collector or use SSH to access the server.

NOTE: Perform these steps on the Data Collector that will be part of the PhoneHome configuration, not on the Data Collector that will serve as a proxy server.

8. Register the Data Collector with the Database Server . To do this, type the following at the shell prompt:

sudo phonehome register token

where:

• token is the value you noted in step 5.

Copying the SSH key to Each Proxy

You must now copy the SSH key to each proxy server. To do this:

1. Either go to the console of the Data Collector that will be part of the PhoneHome configuration (not the proxy server) or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.
3. At the shell prompt, type the following:

ssh-copy-id -i /home/phonehome0/.ssh/id_rsa.pub em7admin@[IP_address_of_proxy_server]

4. Perform step 3 for each proxy server in your PhoneHome configuration.

Synchronize the Data Collectors with the Database Server

After adding Data Collector(s) or Message Collector(s) to your PhoneHome configuration, you must execute the sync command on all Database Servers in the PhoneHome configuration.

To execute the sync command on all Database Servers:

1. Either go to the console of theDatabase Server or use SSH to access the server.
2. Log in as user em7admin with the password you configured during setup.
3. At the shell prompt, type the following:

sudo phonehome sync

4. Perform these steps on each Database Server in your PhoneHome configuration.

The Watchdog Service

Each Data Collector and Message Collector in a PhoneHome configuration runs a service called watchdog. The watchdog process automatically checks the connection between the Data Collector or Message Collector and the Database Server. If the connection is stale, the watchdog service automatically forces the Database Server to reconnect to the Data Collector or Message Collector.

The watchdog service can also detect configuration changes. If the PhoneHome configuration changes, the watchdog service will detect the changes and synchronize the configuration data on each device in the PhoneHome configuration.

The watchdog service is started automatically on each Data Collector, Message Collector, and secondary Database Server.

To view information about the watchdog service:

• Log in to the console of the Data Collector, Message Collector, and secondary Database Server as the root user.

• At the command line, type the following:

phonehome watchdog view

• You should see something like the following:

Current settings:

autosync: yes

interval: 20

state: enabled

autoreconnect: yes

timeoutcount: 2

check: default

• You can change any of these settings by typing the following at the command line:

phonehome watchdog set -settingvalue

where setting is one of the settings displayed with the view command and value is the value to assign to that setting.

• For details about the watchdog service, type the following at the command line:

phonehome watchdog help

For details about the arguments and settings for watchdog, see the section on Using the Command Line Interface.

Logging PhoneHome Configuration Information

The PhoneHome configuration logs information to the following files:

• /var/log/phonehome/phonehome0.log. Resides on each device in the PhoneHome configuration. This log file stores the date and time that devices are added to or removed from the PhoneHome configuration and each configuration action, including token generation, device registration, and configuration data synchronization, performed for each device.

1. /var/log/phonehome/phonehome.log. Resides on the Control Node (usually the Database Server). This log file stores an entry for each action requested by or performed on a specific device (specified by device ID).
2. /var/log/phonehome/ph_watchdog.log. Resides on the Control Node (usually the Database Server). This log file stores information about the watchdog service.

Using the Command-Line Interface

If you have access to the console for each appliance in the PhoneHome configuration, or if you have SSH access to each appliance in the PhoneHome configuration, you can use a shell session and the phonehome command to configure and troubleshoot your PhoneHome configuration.

The phonehome Command

To use the phonehome command:

• Either go to the console of the SL1 appliance or use SSH to access the server. Log in as "root".

For details on enabling and using SSH with SL1, see the Security section.

• At the command prompt, you can type the following:

phonehome argument

where argument is one of the following:

• add appliance_type or request_file. Run this command on the Control Node Database Server. Adds an appliance to the current PhoneHome configuration.

• appliance_type. Type one of the following:

• collector. Adds a Data Collector or Message Collector to the PhoneHome configuration.
• database. Adds a Control Node secondary Database Server or a secondary Database Server to the PhoneHome configuration.

• request_file. When the Data Collector or Message Collector sends a request to the Database Server, the Database Server creates a request file in the directory /home/phonehomerequest/requests. You can specify the full pathname of a request file to accept a request and add a new Data Collector or Message Collector to the PhoneHome configuration.

NOTE: The phonehome add request_file command performs the same operations as selecting the Accept button for a request in ScienceLogic Web Configuration Utility.

• check -json yes. Run this command on any appliance in the PhoneHome configuration. Executes diagnostic steps to aid in troubleshooting.

The phonehome command first tries to connect to the Control Node.

If you issue this command from a Database Server, the command checks the status of the database port, the SSH port, and port for the web configuration tool for each Data Collector and Message Collector.

If you issue this command from a Data Collector or Message Collector, the command checks the status of the database port, the SSH port, and port for the web configuration tool for each Database Server.

• -json  yes. Displays output in json format.

• clear clear_type. Clears the PhoneHome configuration, as specified in the clear_type argument.

• clear_type. Specifies which configuration to remove. Can be one of the following:

• client. Run this command on the secondary Database Server, Data Collector, or Message Collector. Removes the PhoneHome connection (SSH tunnel). The appliance can then no longer connect to the Control Node Database Server.
• users. Run this command on the Control Node Database Server. Removes the PhoneHome configuration for all appliances except the Control Node Database Server.
• all. Run this command on the Control Node Database Server. Removes the PhoneHome configuration for each Data Collector, Message Collector, secondary Database Server, and the primary Database Server.

• close-control-port port_number. Run this command on Database Servers (Control Node and secondary). Blocks future connection requests from Data Collectors and secondary Database Servers.
• connect. Run this command from the Data Collectors, Message Collectors, or secondary Database Server. Starts communication between the Control Node Database Server and the Data Collector, Message Collector, or secondary Database Server.
• delete appliance_ID. Run this command on the Control Node Database Server. Deletes an appliance from the current PhoneHome configuration.

• appliance_ID. Enter the numeric ID of the appliance. You can find this ID with the phonehome status command.

• disconnect. Run this command from the Data Collector(s), Message Collector(s), or secondary Database Server. Stops communication between the Control Node Database Server and the Data Collector, Message Collector, or secondary Database Server.
• enable appliance_ID. Run this command on the Control Node Database Server. Enables a PhoneHome appliance.

• appliance_ID. Enter the numeric ID of the appliance. You can find this ID with the phonehome status command.

• help. Run this command from any appliance in the PhoneHome configuration. Displays information about each parameter for the phonehome command.
• help extra. Run this command from any appliance in the PhoneHome configuration. Displays information about the basic steps to configure a PhoneHome configuration.

• mysql appliance_id. Run this command on the Control Node Database Server. Tests the connection to the MySQL database. If the appliance_ID specifies a Data Collector or Message Collector, the phonehome command will test the MySQL connection using the loopback address of the Data Collector or Message Collector and port 7707. If the appliance_ID specifies a Database Server, the phonehome command will test the MySQL connection using the public IP address of the Database Server and port 7706.

• appliance_ID. Enter the numeric ID of the appliance. You can find this ID with the phonehome status command.

• open-control-port port_number. Run this command on Database Servers (Control Node and secondary). Adds an entry for the specified SSH port to the /etc/sysconfig/iptables file on the current server.
• reconnect. Run this command from the Data Collector(s), Message Collector(s), or secondary Database Server. Stops and then restarts communication between the Control Node Database Server and the Data Collector(s),Message Collector(s), or secondary Database Server.
• register device_token. Run this command from the Data Collector(s),Message Collector(s), or secondary Database Server. Registers the appliance with the Control Node Database Server.

After you generate a token for a Data Collector or Message Collector (either with phonehome token or phonehome add), go to the Data Collector or Message Collector and use the phonehome register command to register the Data Collector or Message Collector with the Control Node Database Server. The Data Collector or Message Collector will then upload its public key to the Control Node Database Server and download its configuration for PhoneHome from the Control Node Database Server. After executing this command, the Data Collector or Message Collector will automatically connect to the Database Server.

In configurations that have multiple Database Servers: After you generate a token for a secondary Database Server (either with phonehome token or phonehome add), go to the secondary Database Server and use the phonehome register command to register the secondary Database Server with the primary Database Server. The secondary Database Server will then upload its public key to the primary Database Server and download its configuration for PhoneHome from the primary Database Server.

• device_token. Enter the token you generated for the Data Collector, Message Collector, or secondary Database Server.

• reload. Can be run on any appliance in the PhoneHome configuration. Stops the em7_sshd and em7_ph_service processes, finds and applies any configuration changes, and restarts the service.

• request [protocol]://[database_IP] [no_verify]. Run this command from the Data Collector or Message Collector to send a request to the Database Server.

• protocol. Enter the protocol to use to send the request to the Database Server. Choices are phonehome or https.
• database_IP. The IP address of the Database Server in the PhoneHome configuration.
• no_verify. Optional. If you specified https in the protocol option, you can specify no_verify to disable SSL verification.

NOTE: The phonehome request command performs the same operations as sending a request to the Database Server from the ScienceLogic Web Configuration Utility. Specifying no_verify performs the same operation as not selecting the Verify SSL Cert checkbox.

You can use the phonehome request command and the phonehome add request_file command to add a Data Collector or Message Collector to a PhoneHome Configuration. Go to the Data Collector or Message Collector and use the phonehome request command to send a request to join the PhoneHome configuration. Go to the Database Server and use the phonehome add request_file command to accept the request from the Data Collector or Message Collector. Go to the Data Collector or Message Collector again and execute the phonehome request command a second time to retrieve the request approval and set up the connection.

• set appliance_ID -parameter=value. Run on the Control Node Database Server. For a specific device, assigns a value to a parameter:

• appliance_ID. Enter the numeric ID of the appliance. You can find this ID with the phonehome status command.
• parameter. Can be one of the following parameters, preceded by a dash:

• name. Specifies the name of the device in the Name field in the Web Configuration Utility.
• ssh. Specifies whether or not to enable port forwarding for the SSH port for this device. Possible values are "yes" or "no".
• ip. Specifies the IP address of the device in the IP Address field in the Web Configuration Utility.
• forwards. Enables port forwarding for one or more ports. Specify one or more port numbers, separated by a space.

• value. Value to assign to the parameter, surrounded by double quotes.

For example:

phonehome set 11 -ssh yes -name "Reston"

• This example affects the device with an appliance ID of "11".
• The example enables port forwarding for SSH.
• The example enables port forwarding for the Web Configuration Utility.
• The example sets the device’s device name to "Reston".

• ssh appliance_id. Run on the Control Node Database Server. Tests the SSH connection to the specified appliance. If the appliance_ID specifies a Data Collector or Message Collector, the phonehome command will test the SSH connection using the loopback address of the Data Collector or Message Collector and port 10022. If the appliance ID specifies a Database Server, the phonehome command will test the SSH connection using the public IP address of the Database Server and defined SSH port.

• appliance_ID. Enter the numeric ID of the appliance. You can find this ID with the phonehome status command.

• status. Can be run on any appliance in the PhoneHome configuration. Displays the name and status of each currently defined PhoneHome appliance.
• sync. Run this command from the Data Collectors, Message Collectors, or secondary Database Server. Downloads the current configuration for PhoneHome from the Control Node Database Server to the Data Collector, Message Collector, and secondary Database Server.

• token appliance_ID. Run this command from the Control Node Database Server. This command creates a URL that allows the Data Collector(s), Message Collector(s), or secondary Database Server to log in to the Control Node Database Server, upload a public key to the Control Node Database Server, and download the configuration for PhoneHome from the Control Node Database Server.

• appliance_ID. Enter the numeric ID of the Data Collector, Message Collector, or secondary Database Server. You can find this ID with the phonehome status command.

• view appliance_id -jsonyes. Run this command from the Control Node Database Server. Displays the name, type, loopback IP, port status, revision number, and SSH status of the Data Collector, Message Collector, or secondary Database Server specified in appliance_ID.

• appliance_ID. Enter the numeric ID of the appliance that you want. You can find this ID with the phonehome status command.
• -json yes. Displays output in json format.

• wake appliance_id. Run this command from the primary Database Server. Depending on the specified appliance_ID, stops and then restarts communication between the Database Server and the Data Collector, Message Collector, or secondary Database Server.

• appliance_ID. Enter the numeric ID of the appliance that you want. You can find this ID with the phonehome status command.

• watchdog option. Run this command from the Data Collector, Message Collector, or secondary Database Server. The watchdog service runs automatically on each Data Collector, Message Collector, or secondary Database Server and checks the connection to the Control Node Database Server. If the connection is stale, the watchdog service automatically forces the Control Node Database Server to reconnect to the Data Collector, Message Collector, or secondary Database Server. The watchdog service can also detect configuration changes. If the PhoneHome configuration changes, the watchdog service will detect the changes and synchronize the configuration data on each device in the PhoneHome configuration.

NOTE: The watchdog and autosync services are not available for versions of SL1 earlier than the 7.5.3 ISO.

You can use this command to control the watchdog service. The options are:

• start. Starts the PhoneHome watchdog service.
• stop. Stops the PhoneHome watchdog service.
• status. Gets the status of the PhoneHome watchdog service.
• view. Displays the current settings for the watchdog service.
• set -parameter value. Sets the value of a parameter for the watchdog service. Parameters are:

• interval seconds. Specify the interval, in seconds, at which to execute the watchdog service. The default value is "50".
• autosync (yes, no). Specifies whether or not you want the watchdog service to cause configuration data to be synchronized automatically at regular intervals.
• autoreconnect (yes, no). Specifies whether or not you want the watchdog service to reconnect stale connections automatically.
• state (enabled, disabled). Specifies whether or not the watchdog service is running.
• timeoutcount number. Specifies the number of failed calls to the watchdog service before stopping and restarting the watchdog. The default value is "3".
• check (ssh, db, default). Specifies which port the watchdog service checks. The default value is "db".

• run -verbose (yes, no). Manually starts the watchdog service if it is not already running.

• -verbose (yes, no). Specifies whether or not to display verbose logging to standard output.

Troubleshooting the PhoneHome Configuration

Best Practices

Make all changes to the PhoneHome configuration on the Control Node. After making these changes, run the following command on each appliance in the PhoneHome configuration:

sudo phonehome sync

Basic Troubleshooting

Verifying the Control Node

For the PhoneHome configuration to perform successfully, each server in the configuration must use the same Control Node. To determine which Database Server is the Control Node, perform the following:

• Either go to the console of the SL1 appliance or use SSH to access a Database Server. Log in as "em7admin
• At the shell prompt, type the following:

sudo phonehome status

• For the Control Node, you should see something that looks like this:

[Original reference image unavailable: phonehome status primaryDB 576x161]

• The Control Node displays "Device:0" in the output.
• The output for the control node does not include a URL.

• Perform steps 1-3 on each additional Database Server in the PhoneHome Configuration. You should see something like this:

[Original reference image unavailable: phonehome status secondaryDB 576x210]

• The URL for the secondary Database Server includes the IP address its control node.

• Either go to the console of the SL1 appliance or use SSH to access a Data Collector or Message Collector. Log in as "em7admin".
• At the shell prompt, type the following:

sudo phonehome status

• You should see something that looks like this:

[Original reference image unavailable: phonehome status collector 576x153]

• The output for the Data Collector or Message Collector includes the text "Client Configuration" in the output.
• The URL for the Data Collector or Message Collector includes the IP address in its control node.

• Perform steps 5-7 on each Data Collector and Message Collector in the PhoneHome Configuration.

To fix one or more secondary Database Servers that returns a different Control Node, you can perform the following:

• On the Database Server that the secondary Database Server incorrectly identifies as the Control Node, either go to the console of the SL1 appliance or use SSH to access the server. Log in as "em7admin". Type the following:

phonehome clear client

• On the Database Server that is the correct Control Node, perform steps 8-12 in Configuring the Control Node Database Server. These are the steps that define the secondary Database Server, including saving the token and saving the new configuration.
• On the secondary Database Server that returns the incorrect control node, perform the steps in Configuring the Secondary Database Server for High Availability and Disaster Recovery.