Configuring SL1 for PhoneHome Communication

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

Starting with SL1 version 11.2.0, the PhoneHome Communication configuration process for SL1 Collectors has been moved to Installing and Configuring an SL1 Collector. The procedures in this chapter are not compatible with the new procedures for SL1 version 11.2.0 or later that are covered in that chapter.

The PhoneHome command-line interface for SL1 version 11.2.0 and later was extensively updated, with many new and removed commands. For more information, see Using the Command-Line Interface for PhoneHome Collection in SL1 Version 11.2.0 and Later.

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

To view a pop-out list of menu options, click the menu icon ().
To view a page containing all of the menu options, click the Advanced menu icon ().

What is PhoneHome Communication?

SL1 supports two methods for communication between a Database Server (an SL1 Central Database or an SL1 Data Engine) and the Data Collectors and Message Collectors:

Traditional
PhoneHome

In the Traditional method, the SL1 services on the Database Server initiate a new connection to the MariaDB port on the collector to read and write data. The connection request traverses the network, including the Internet if necessary, eventually reaching the collector. For this approach to work, the collector administrator must allow ingress communication from the Database Server on port 7707 (the MariaDB port on the collector). The communication is encrypted using SSL whenever possible.

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

In the PhoneHome method, the collectors initiate an outbound connection to the Database Server over SSH. After authenticating, the client forwards the local MariaDB port onto the Database Server using a loopback remote IP address. A corresponding SL1 appliance is added using the loopback IP. When the SL1 services on the database try to make a connection to the collector's MariaDB, they connect locally to the loopback IP address, in contrast to reaching out to the collector's IP or DNS name. The communication is encrypted.

The benefits of this method are that no ingress firewall rules need to be added as the collector initiates an outbound connection, 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 Server.
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.

Please note that whitelisting port 7705 in the firewall is not enough. If the firewall does a layer 7 (application layer) filtering, you must create an exception rule to allow any outgoing traffic from the collector to all the Database Servers on the control port, which is port 7705 by default. Some firewalls enable this by default and, as a result, those firewalls will drop SSH traffic on a non-standard port like 7705 in this situation.

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 in the SL1 user interface to use PhoneHome communications:

Configure one or more Database Servers for PhoneHome.

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.

Configure the Data Collectors and Message Collectors for PhoneHome.

Starting with SL1 version 11.2.0, the PhoneHome Communication configuration process for SL1 Collectors has been moved to Installing and Configuring an SL1 Collector. The procedures in this chapter are not compatible with the new procedures for SL1 version 11.2.0 or later that are covered in that chapter.
Define the Database Server associated with each Data Collector or Message Collector appliance.
Register the Data Collectors and Message Collectors in SL1.
As needed, define port forwarding for each collector to use SSH from the Database Server to access that collector.
See the Troubleshooting section for additional help.

The PhoneHome command-line interface for SL1 version 11.2.0 was extensively updated, with many new and removed commands. For more information, see Using the Command-Line Interface for PhoneHome Collection in SL1 Version 11.2.0 and Later.

Configuring the Database Server for PhoneHome

In PhoneHome communication, the Database Server communicates with the Data Collectors and the optional Message Collectors. The Database Server stores all the configuration information for the PhoneHome configuration. The Database Server can be a Central Database (CDB) appliance or a Data Engine (DE) appliance.

Setting up a Database Server prepares the server to listen to incoming connections from a PhoneHome collector. This process also opens the firewall rules on the configured port and labels the configured port for SSH traffic in the SE Linux subsystem.

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 in the SL1 system can provide network access.

Before Configuring the Database Server

Make sure you have answers to the following questions before setting up the Database Server:

Is the Database Server a single CDB or DE, or is there a High Availabilty (HA) or Disaster Recovery (DR) pair?
Is the CDB or DE behind a NAT gateway?
Do you want the PhoneHome server to listen on to the default port 7705, or do you want to customize the port?
Does the Database Server have multiple routable IP addresses to it, and do you plan to have PhoneHome collectors from different subnets connect to the Database Server?

Each Database Server must have SL1 installed, have an IP address assigned to it, and be licensed with ScienceLogic. For more information about licensing, see Licensing and Configuring a Database Server.

Configuring the Database Server in SL1 Version 11.2.0 and Later

The following sections explain how to configure the Database Server based on your SL1 environment.

After you configure the Database Server for PhoneHome communication, you must configure the Data Collectors and Message Collectors in your network. For more information, see Configuring the Data Collectors and Message Collectors for PhoneHome.

Configuring a Single Database

The most basic SL1 environment is with a single database appliance. This setup makes the following assumptions:

The database appliance has a public IP address assigned to one of its network interfaces or has a private IP address.
All the PhoneHome collectors will be on the same network and will be able to reach the private IP address of the PhoneHome Database Server.
The user intends to configure the PhoneHome Database Server to listen on port 7705.
The user intends to name the PhoneHome server as "ph-db-1". Naming the PhoneHome device is optional, but recommended.

To configure a single database appliance for PhoneHome communication:

Go to the console of the Database Server or use SSH to access the server and log in as user em7admin with the password you configured during setup.
Run the following command:

sudo phonehome setup -n ph-db-1

Configuring a Database with a Non-default Address or Port

Use this setup in the following situations:

You want the PhoneHome server to listen on a non-default port, or on an address that is different than the output of the getaddrbyhostname syscall.
The database appliance is behind a NAT gateway
The database appliance is set up on a cloud host, like AWS, where the public IP is not assigned directly to the network interface of the virtual host.

To configure a Database Server with a non-default address or port:

Go to the console of the Database Server or use SSH to access the server and log in as user em7admin with the password you configured during setup.
Run the following command:

sudo phonehome setup -n ph-db-1 -a <addr>

where <addr> is an IPv4 or DNS same in "host:port" format, such as 203.65.33.22:7809 or ph-db1.example.com:8899.

The PhoneHome server process runs as an unprivileged user that will not be able to bind to a privileged port (1-1023). So when you choose a custom port, you must choose port 1024 or higher.

Configuring a Database with Multiple IP Addresses

To configure a Database Server with multiple IP addresses:

Go to the console of the Database Server or use SSH to access the server and log in as user em7admin with the password you configured during setup.
Run the following command:

sudo phonehome setup -n ph-db-1
Run the following command:

sudo phonehome destination add <id> <addr>

where <id> is the resulting device ID for the PhoneHome database and <addr> is an actual address string in "host:port" format. The port in all addresses must be the same, because a PhoneHome server is by design not capable of listening on multiple ports.
Repeat this command for every address that you want to add to the destination.

Configuring Additional Databases in a HA or DR Environment

In this setup, configure the Database Server the same as setting up a single database using setup command where you customize the name and the address as needed.

Configuring the Database Server in SL1 Version 11.1.x and Earlier

To configure the Database Server for PhoneHome communication in SL1 version 11.1.x and earlier:

Go to the console of the Database Server or use SSH to access the server and log in as user em7admin with the password you configured during setup.
Run the following command to open a port to accept incoming connection requests.:

sudo phonehome open-control-port <port_number>

where <port_number> is an unused port number greater than 1024. 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.

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

sudo phonehome add database
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"
Note the ID number for the database (11 in our example).
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

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

Starting with SL1 version 11.2.0, the installation and configuration process for SL1 Collectors was updated. For detailed procedures about configuring a collector, see Installing and Configuring an SL1 Collector.

This section describes how to configure a Data Collector and a Message Collector for use in a PhoneHome configuration running a version of SL1 before version 11.2.0.

Each Data Collector and Message Collector f must have SL1 installed, and each Data Collector and Message Collector must have an IP address assigned to it.

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 in SL1 before version 11.2.0:

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

where <IP_address_of_collector> is the IP address of the Data Collector or Message Collector.

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 Configuration Utilities page appears.
Click the PhoneHome button. The PhoneHome - Collector page appears.
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.

The PhoneHome connection between a Collector and the Database Server requires that you initiate outbound communication on TCP/443 and TCP/7705. Both ports must be open for this connection to work. You can use the nmap command to make sure the ports are open before attempting the connection:

nmap - p 443 x.x.x.x
nmap -p 7705 x.x.x.x
Make request via HTTPS. Optional. If you select this checkbox, the Data Collector will send the PhoneHome request to the Database Server using an HTTPS request. The Data Collector will send 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.
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.

Click the Send Connection Request button to send the request from the Data Collector to the Database Server that is configured for PhoneHome. This option uses SSH to send the request. After clicking the Send Connection Request button, the PhoneHome - Collector page displays the status Pending database approval. Do not close the browser window or navigate away from this page while the connection request is being processed. Do not close the browser window or navigate away from this page while the connection request is being processed.

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 username 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.
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.

Note that the Status message is now Configured - ID [phonehome_user_number]. 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 PhoneHomebutton.

Click the Accept All Collector Requests button.
Open the ScienceLogic Web Configuration Utility for each collector, click the PhoneHomebutton, 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

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.

Starting with SL1 version 11.3.0 and later, you only need to license a Database Server, whether it is a central database (CDB) or a data engine (DE). SL1 automatically licenses Data Collectors, Message Collectors, and Administration Portal appliances when they are added to the environment.

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.

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).

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.

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.
DB User. User name that can access the MariaDB database on the Data Collector or Message Collector.
DB Password. Password that allows access the MariaDB database on the Data Collector or Message Collector.

In SL1 version 11.2.0, SL1 automatically set the default database credentials when adding an SL1 collector to the stack. Starting with SL1 version 11.3.0, SL1 no longer specifies the credentials. As a result, you will need to specify the credentials for the collector on the Appliances page (System > Settings > Appliances), in the DB User and DB Password fields.

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.

Managing Port Forwarding for PhoneHome Communication in SL1 Version 11.2.0 and Later

A port forward is a configuration that allows a PhoneHome client to "copy" a local port from the SL1 Collector to the Database Server, essentially making the local port available on the Database Server appliance as if it was physically present on that appliance itself.

The local MariaDB port 7707 on the collector is forwarded to the Database Server by default.

Viewing a List of Port Forwards

This section applies only to SL1 version 11.2.0 and later.

To view a list of ports forwarded from an SL1 Collector to the Database Server:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector:

phonehome forwards list

This list will not include the MariaDB port 7707, which is forwarded by default.

Adding a Port Forward

This section applies only to SL1 version 11.2.0 and later.

To add a port forward:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, replacing <Remote Address> with the port on the Database Server onto which the local port will be forwarded and <Local Address> with the local port to forward from the SL1 Collector:

phonehome forward add <Remote Address> <Local Address>

Addresses should be in the format :<port>.

The remote port should be an unprivileged port (a port greater than 1023).

For example, if you want to forward SSH port 22 from the SL1 Collector to the Database Server appliance as port 10022 to enable a Database Server administrator to SSH into the SL1 Collector from the Database Server appliance, you would run the following command:

phonehome forward add :10022 :22

New forwards do not take effect until the PhoneHome client is restarted or the next watchdog cycle occurs.

Removing a Port Forward

This section applies only to SL1 version 11.2.0 and later.

To remove a port forward:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, replacing <Remote Address> with the port on the Database Server appliance onto which the local port was forwarded and <Local Address> with the local port that was forwarded from the SL1 Collector:

phonehome forward remove <Remote Address> <Local Address>

Addresses should be in the format :<port>.

For example, if you want to no longer forward SSH port 22 from the SL1 Collector to the Database Server appliance as port 10022, run the following command:

phonehome forward remove :10022 :22

Deleted forwards do not take effect until the PhoneHome client is restarted or the next watchdog cycle occurs.

Defining Port Forwarding for PhoneHome Communication in SL1 Version 11.1.x and Earlier

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:

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

Log in as user em7admin with the password you configured during setup.
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 the device ID for the Data Collector or Message Collector and <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
For every other server in the PhoneHome configuration, go to the console of the Database Server or use SSH to access the server.
Log in as user em7admin with the password you configured during setup.
Type the following at the shell prompt:

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

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:

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 unacknowledged 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"

To determine the format for entries in the /etc/phonehome/local.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.

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.

Configuring the Primary Database Server for High Availability and Disaster Recovery

To configure the primaryDatabase Server for PhoneHome communication:

Go to the console of the primary Database Server or use SSH to access the server.
Log in as user em7admin with the password you configured during setup.
For the primary 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 1024. 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.

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

sudo phonehome add database
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"
Note the ID number for the primary Database Server (11 in our example).
To define the public-facing IP address of the primary Database Server and the port to use for SSH communication from PhoneHome servers to the primary 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 1024. 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
Start the PhoneHome watchdog. To do so, type the following at the shell prompt:

sudo systemctl enable em7_ph_watchdog

sudo systemctl start em7_ph_watchdog
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 primary Database Server. To do so, type the following at the shell prompt:

sudo phonehome add database
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"
Note the ID number for the secondary Database Server. You will need this value later in the configuration.
Copy and save the token for the secondary Database Server. You will need this value later in the configuration.
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 primary 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:

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

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 <port_number> is an unused port number greater than 1024. The default value in the Configuration Utility is 7705. If you want to use the default value, specify "7705". ScienceLogic recommends that you use the same port number on each database in your PhoneHome configuration.

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 11 in the section Configuring the Primary Database for High Availability and Disaster Recovery.

The output looks like the following:

Registered device successfully

Type the following at the shell prompt:

sudo phonehome sync

The output looks like the following:

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.

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:

Either go to the console of the Database Server (or the new Collectors) or use SSH to access the server.
Log in as user em7admin with the password you configured during setup.
At the shell prompt, type the following:

sudo phonehome sync
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, perform the steps 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.
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.

Managing Destinations

A destination is a list of addresses associated with a Database Server. A PhoneHome Database Server can have one or more destination addresses associated with it.

Destination addresses can be IPv4 addresses or DNS names, or a combination of both.

Viewing a List of Destinations

This section applies only to SL1 version 11.2.0 and later.

To view a list of all destinations in your stack:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector:

phonehome destination list

This command provides a list of all Database Servers with their device IDs, addresses, and priorities. Priorities define the order in which an SL1 Collector will try to connect to the individual addresses. It will keep trying until it can connect to one of them.

To view a list of destinations on a specific PhoneHome Database Server, run the following command, where <Device ID> is the ID of the PhoneHome Database Server:

phonehome destination list --id <Device ID>

Adding a Destination Address

This section applies only to SL1 version 11.2.0 and later.

To add a new destination address:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, where <Device ID> is the ID of the device to which you want to add a new address and <Address> is the destination address:

phonehome destination add <Device ID> <Address>

Addresses should be in the format <host>:<port>.

Host addresses can be IPv4 addresses or DNS names.

If successful, you will get a message confirming that the new address was successfully added to the destination.

For example, if you wanted to add the destination address 192.168.0.13, with port 7705 open, to the device with the device ID 2, run the following command:

phonehome destination add 2 192.168.0.13:7705

The port you open must match the port that is open for the original device. Otherwise, you will receive an error.

Optionally, you can add the suffix --priority <Priority> to establish the destination's priority, or use the suffix --force to force add a destination address, even if the port does not match with the device's listed port.

Removing a Destination

This section applies only to SL1 version 11.2.0 and later.

To remove an existing address from a destination:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, where <Device ID> is the ID of the device from which you want to remove a destination address and <Address> is the destination address:

phonehome dest remove <Device ID> <Address>

Addresses should be in the format <host>:<port>.

Host addresses can be IPv4 addresses or DNS names.

You cannot remove an address from a destination if it is the destination's only address.

Managing Proxy Connections for PhoneHome Communication in SL1 Version 11.2.0 and Later

If your organization requires that you use a proxy for outbound requests, you can configure one or more proxy connections between the an SL1 Collector and the Database Server.

For example, you might use a proxy connection if your SL1 Collector does not have a direct outbound internet connection to reach the Database Server. A PhoneHome proxy configuration includes the destination address—either the address of the Database Server or that of the next proxy host—and the address of the proxy server to which the client must connect to reach the destination.

There can be one or more proxy hosts in between an SL1 Collector and a Database Server, thus forming a proxy chain.

If you use a proxy in your PhoneHome configuration, perform the steps in the section about Adding a Proxy Connection before you configure the other steps in thissection. The other steps in the PhoneHome configuration will require the proxy for communication.

Viewing a List of Proxy Connections

To view a list of proxy connections from an SL1 Collector to the Database Server:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector:

phonehome proxy list

Adding a Proxy Configuration

To add a proxy connection between an SL1 Collector to the Database Server:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, replacing <Destination Address> with the address and port of the Database Server appliance to which you want to connect, <Proxy Address> with the proxy host address and port you want to use as a tunnel, and <Proxy User> with the username used to log in to the proxy host:

phonehome proxy new <Destination Address> <Proxy Address> <Proxy User>

Addresses should be in the format <host>:<port>. The host can be either an IP address or a DNS name.

For example, if you want to configure the SL1 Collector to connect to the Database Server with an address of 202.35.52.71 through a proxy host with the address 10.1.17.68 with the user em7admin, you would run the following command:

phonehome proxy new 202.35.52.71:7705 10.1.17.68:22 em7admin

If you are connecting to the Database Server through a chain consisting of multiple proxies, you should add the proxy configurations in reverse order, starting with the destination address and last proxy host address, then the last proxy host address and previous proxy host address, and so forth, until you get to the first proxy host.

For example, if you want to connect to the Database Server with an address of 202.42.63.79 through proxy host A with an address of 192.168.0.3 with the user proxyuser, and also proxy host B with an address of 10.2.13.79 with the user em7admin, then you would run the following commands:

phonehome proxy new 202.42.63.79:7705 10.2.13.79:22 em7admin

phonehome proxy new 10.2.13.79:22 192.168.0.3 proxyuser

New proxy configurations do not take effect until the PhoneHome client is restarted or the next watchdog cycle occurs.

When you run the command, the system prompts you for a password for the proxy host. The system uses this password to automatically configure and validate SSH key-based authentication to the host; the next time you need to run anything via the proxy host, it will use the collector's private key for authentication rather than prompting you for the password. Optionally, you can disable this behavior by adding "-n" to the end of the command. If you do so, you must then manually configure the proxy's SSH key-based authentication.

Deleting a Proxy Configuration

To add a proxy configuration between an SL1 Collector to the Database Server:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, replacing <Destination Address> with the address and port of the Database Server appliance to which the proxy is connecting:

phonehome proxy delete <Destination Address>

Addresses should be in the format <host>:<port>. The host can be either an IP address or a DNS name.

Removed proxy configurations do not take effect until the PhoneHome client is restarted or the next watchdog cycle occurs.

Managing Proxy Connections for PhoneHome Communication in SL1 Version 11.1.x and Earlier

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.

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:

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)
Edit the ssh_config file.
Use the command line to configure Data Collectors that connect via proxy.
Copy the SSH key to each proxy.
Synchronize the Data Collectors with the Database Server.

Editing ssh_config

To edit the ssh_config file:

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.

Either go to the console of the Data Collector that will be part of the PhoneHome configuration or use SSH to access the server.
Log in as user em7admin with the password you configured during setup.
Open the file /etc/ssh/ssh_config with vi or another text editor:

sudo vi /etc/ssh/ssh_config
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).
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.

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).

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 for which you are creating an entry). 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

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:

Either go to the console of the Database Server or use SSH to access the server.
Log in as user em7admin with the password you configured during setup.
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 1024.
To define the Data Collector (to the Database Server), type the following at the shell prompt:

sudo phonehome add collector

The output will look like the following:

Created collector: #12

Changing password for user: "phonehome12"

Created Device Id: "12"

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

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

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.

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:

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.
Log in as user em7admin with the password you configured during setup.
At the shell prompt, type the following:

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

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:

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

sudo phonehome sync
Perform these steps on each Database Server in your PhoneHome configuration.

Deleting a PhoneHome Collector

This section applies only to SL1 version 11.2.0 and later.

You can delete a PhoneHome SL1 Collector only if it has no corresponding SL1 appliance.

Therefore, to delete a PhoneHome SL1 Collector, you must also perform the following steps, if applicable:

If the SL1 Collector has a corresponding SL1 appliance, you must delete that appliance before you can delete the SL1 Collector.
If the corresponding SL1 appliance is included in a collector group, you must delete that collector group before you can delete the appliance and then the SL1 Collector.
If the SL1 appliance's collector group includes other devices, you must move those devices to a different collector group before you can delete the appliance's collector group, then the appliance, and finally the SL1 Collector.

Once you delete a PhoneHome SL1 Collector, you cannot undelete it. Deleting an SL1 Collector will delete all configuration related to the device and cause all Database Servers to close incoming connections from the device.

To delete a PhoneHome SL1 Collector:

Go to the console of the SL1 Collector.
Run the following command on the SL1 Collector, replacing <id> with the PhoneHome device ID of the device you want to delete:

phonehome delete <id>

One of the following will occur:

If the device does not have a corresponding SL1 appliance on the stack, a confirmation prompt appears, asking you to confirm that you want to delete the device. Type "Y" and press Enter. The device is deleted and you can skip the rest of this section.
If the device does have a corresponding SL1 appliance, a message similar to the following appears:

Error: Cannot delete a phonehome device that has a corresponding appliance: [Module ID: 10, Name: example-device-cu1, CUG(s): cug-dc09]

If you receive an error message, proceed to the next step.

Go to the Appliance Manager page (System > Settings > Appliances).
Locate the device with the ID that matches the Module ID value that was returned in the error message in step 2, and then do one of the following:

If the appliance is not part of a collector group, click its bomb icon () to delete it. You can then repeat steps 1 and 2 to delete the SL1 Collector.
If the appliance is part of a collector group, the bomb icon is disabled. Proceed to the next step.

Go to the Collector Group Management page (System > Settings > Collector Groups).
Locate the collector group with the name that matches the CUG value that was returned in the error message in step 2, and do one of the following:

If the collector group does not contain any devices, click its bomb icon () to delete it. You can then repeat steps 3 and 4 to delete the appliance.
If the collector group contains devices, the bomb icon is disabled. Proceed to the next step.

Go to the Device Manager page (Registry > Devices > Device Manager).
Select the checkbox for each device that you want to move to a different collector group.
In the Select Action field (in the lower right), select Change Collector Group and then select a collector group.
Click the Go button. The selected devices will now be aligned with the selected collector group.
Repeat steps 5 and 6, and then work your way backwards as needed, completing steps 3 and 4, followed by steps 1 and 2. Repeat these steps as needed until the device is deleted successfully in step 2.

Deleting a PhoneHome Database Server

This section applies only to SL1 version 11.2.0 and later.

To delete a PhoneHome Database Server:

Go to the console of the Database Server that you want to delete.
Run the following command:

sudo phonehome clear -d

A confirmation prompt appears, asking you to confirm that you want to delete the device. Type "delete" and press Enter.

You must run this command from the Database Server that you want to delete. You cannot run it from any other Database Server or the Administration Portal.

Once you delete a PhoneHome Database Server, you cannot undelete it. Deleting a Database Server will delete all configuration related to the device and close all incoming connections from PhoneHome SL1 Collectors.

Using the Watchdog Service with SL1 11.1.x and Earlier

This section applies only to SL1 version 11.1.x and earlier.

Each Database Server, 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:

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

This following section applies only to SL1 version 11.2.0 and later.

In SL1 version 11.2.0 and later, the server hosts are stored in the journald log for the phd service on the Database Server and in the journald log for the phc service on the Collector.

To view those logs, run the following commands on the Database Server or Collector:

sudo journalctl -u phd.service

sudo journalctl -u phc.service

Viewing PhoneHome Logs in SL1 version 11.1.x and Earlier

The following section applies only to SL1 version 11.1.x and earlier.

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. This log is rotated daily.
/var/log/phonehome/phonehome<device ID>.log. Resides on the Database Server. This log file stores an entry for each action requested by or performed on a specific device (specified by device ID). This log is rotated daily.
Log files that store information about registration operations and periodic checks performed by the Data Collectors reside in the directories listed below. These log files are auto-rotated when they exceed 10MB.

/var/log/ph_shell_collector. Contains shell logs from users in group em7-ph-collectors (Data Collectors).
/var/log/ph_shell_local. Contains shell logs for users in group em7-ph-local (the phonehome0 and phonehomerequest users).
/var/log/ph_shell_database/. Contains shell logs for users in group em7-ph-cdb (Database Servers)
/var/log/phonehome/commands.log. Stores the log entries about each phonehome command executed on that appliance.
/var/log/phonehome/

/var/log/phonehome/ph_watchdog.log. Resides on the Database Server. This log file stores information about the watchdog service. This log is rotated daily.

Using the Command-Line Interface for PhoneHome Collection in SL1 Version 11.2.0 and Later

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 the phonehome command to configure and troubleshoot your PhoneHome configuration.

The following list of commands includes new commands that were available with SL1 version 11.2.0 and later. The new server and client does not use OpenSSH tooling. If you are running a version of SL1 earlier than 11.2.0, see Using the Command-Line Interface for PhoneHome Collection in SL1 Version 11.1.0 and Earlier.

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".
At the command prompt, type the following:

phonehome <command>

where <command> is one of the following commands:

clear. Clears the PhoneHome configuration on a PhoneHome device.
check. Checks the state of the connection from an SL1 Collector to the Database Server, visualizing the network path from the SL1 Collector to the Database Server as well as any proxy hops in between, if applicable. The output indicates any failures connecting to any hop.
client. Runs the PhoneHome client (installed as a systemd service phc). New in SL1 11.2.0.
config. Displays and enables you to edit PhoneHome configuration related to the server and client. New in SL1 11.2.0.
delete. Deletes a PhoneHome SL1 Collector. This argument prevents you from deleting any SL1 Collector with an associated SL1 appliance.
destination. Enables you to add, remove, or view addresses to a PhoneHome Database Server. New in SL1 11.2.0.
forwards. Enables you to add, remove, or view ports forwarded from an SL1 Collector to the Database Server. New in SL1 11.2.0.
list. Displays a list of PhoneHome devices (Database Servers and Collectors). New in SL1 11.2.0.
migrate. Migrates the configuration from the classic PhoneHome setup to the new PhoneHome setup. This is done automatically during upgrade. New in SL1 11.2.0.
proxy. Enables you to add, remove, or view proxy configurations along the network path from an SL1 Collector to the Database Server. New in SL1 11.2.0.
register. Registers a new SL1 Collector as a PhoneHome collector with a token.
request. Enables you to send, view, accept, or reject an SL1 Collector registration request. New in SL1 11.2.0.
server. Runs the PhoneHome server (installed as a systemd service phd). New in SL1 11.2.0.
setup. Configures a new PhoneHome Database Server. New in SL1 11.2.0.
status. Displays the status of the PhoneHome SL1 Collectors. The output is tabular by default but supports JSON output as well. The output does not contain the remote loopback IP address of PhoneHome SL1 Collectors, nor does it list PhoneHome Database Servers.
sync. Syncs the configuration from the Database Server. This command does not restart the SSH tunnel to the Database Server.
token. Enables you to create, view, or delete registration tokens. New in SL1 11.2.0.
view. Displays the state of an SL1 Collector. This argument must be run on a Database Server.

Additional New Command-line Features in SL1 version 11.2.0

The following features are new or updated in SL1 version 11.2.0 or later:

Adding a Database Server or Collector does not require the creation of users on the operating system of the Database Server.
The authentication of the server and client happens over the configuration store in MariaDB on the server, rather than flat files on the filesystem of the Database Server.
There is no notion of a control node. Every Database Server in a HA/DR setup can participate in all operations.
You can assign multiple addresses to a destination if required. The list of addresses can be a mix of IPv4 and DNS names.
There is now a command in the command-line interface to manage proxy configuration that validates and assists in setting up proxy.
Onboarding a PhoneHome Collector automatically adds a corresponding SL1 Appliance and also adds it to the predefined SL1 Collector Group.
For the token registration workflow, the token is a signed JSON Web Token (JWT) that expires after a predefined time from the time of generation. The token expires after 30 minutes by default, but it can be extended to a maximum of 2 hours. The token encodes all destination addresses
To generate a token, you now need to execute the phonehome token new command. You need to know the model type, collector group ID, name, and description of the collector you are trying to onboard.
The token request workflow includes the following:

A collector registration request does not expire until it is deleted by a database administrator.
Creates a one-time password to accept a request. This one-time password must be shared with the database administrator so that the administrator can accept the request
An additional human-friendly identifier or label can be passed along with the request to uniquely identify the request

The control of port forwarding is with the collector administrator. A PhoneHome collector forwards the local MariaDB port (7707) by default. The collector administrator can forward other local ports as needed. The database cannot instruct the collector to forward an arbitrary port.
When setting up a Database Server, the open-control-port command is no longer available. The setup command creates a PhoneHome device in the config store along with its corresponding RSA host key. It also adds the default non-loopback IP corresponding to the hostname as the default destination address. The user can define a custom destination address if required. The command also adds a firewall rule to allow incoming connections on the specified port and labels it as SSH port (ssh_port_t) in the SELinux subsystem.
Systemd services:

The em7_ph_tunnels service is no longer available, and it was replaced by the phc (phonehome client) service.
The OpenSSH service for the control port is replaced by the phd service. OpenSSH will not be listening anymore on the control port after the migration.
The em7_ph_watchdog is no longer available. Both the server and client run in-process watchdog in separate threads.

Tuning PhoneHome Settings in SL1 Version 11.2.0 and Later

A PhoneHome setting is a customizable configuration that impacts how a PhoneHome server or client behaves. Some settings impact both the server and client; others are localized to either just the server or just the client.

Updated PhoneHome settings do not take effect until the PhoneHome server or client is restarted or the next watchdog cycle occurs.

Viewing a List of Current PhoneHome Settings

This section applies only to SL1 version 11.2.0 and later.

To view a list of current PhoneHome settings:

Go to the console of the SL1 Collector or Database Server.
Run the following command on the SL1 Collector or Database Server:

phonehome config list

When you run the command, the system returns a list that includes each configuration setting, its value, a description, and an indication of whether the setting affects the client, the server, or both.

Updating PhoneHome Settings

This section applies only to SL1 version 11.2.0 and later.

To set a new value for an existing PhoneHome setting:

Go to the console of the SL1 Collector or Database Server.
Run the following command on the SL1 Collector or Database Server:

phonehome config set <setting_name> <new_value>

For example, if you want to change the client timeout value to 30 seconds, you would run the following command:

phonehome config set client_timeout 30s

You can update the following settings:

Configuration	Setting	Description	Default Value	Affects
Client Timeout	client_timeout	Maximum amount of time allowed for the client to connect to a Database Server, after which the connection times out. The value is an actual time value, such as 30s, 5m, or 2h.	30s	Client
Exit on Forward Failure	exit_on_forward_failure	Indicates whether to close the connection to the Database Server if any custom ports fail to forward. This is not applicable to MariaDB port forwarding (port 7707). If the MariaDB port fails to forward, the client closes the connection regardless of this setting. The value is either true or false.	false	Client
Watchdog Frequency Duration	watchdog_freq	Amount of time between watchdog service cycles. The value is an actual time value, such 30s, 5m, or 2h.	1m0s	Both
Port Ping Timeout	port_ping_timeout	Maximum allowed time for a Database Server's watchdog to connect to the forwarded port before it marks the SL1 Collector as disconnected and closes the incoming client connection. The value is an actual time value, such as 30s, 5m, or 2h.	10s	Server
Token Time to Live (TTL)	token_ttl	Default amount of time a token is valid before it expires. The value is an actual time value, such as 30s, 5m, or 2h. The maximum value is 2h.	30m0s	Server
Expired Token Cleanup Frequency	expired_token_cleanup_freq	Amount of time after which an expired token is deleted by the server. The value is an actual time value, such as 30s, 5m, or 2h.	48h0m0s	Server

Using the Command-Line Interface for PhoneHome Collection in SL1 Version 11.1.x and Earlier

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".
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 primary Database Server. Adds an appliance to the current PhoneHome configuration.

This command is not available in SL1 version 11.2.0 or later; in this situation, use the token or the request workflows.

appliance_type. Type one of the following:

collector. Adds a Data Collector or Message Collector to the PhoneHome configuration.
database. Adds a primary 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.

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.
- -json yes. Displays output in json format.
The phonehome command first tries to connect to the primary Database Server.

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.

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 primary Database Server.
users. Run this command on the primary Database Server. Removes the PhoneHome configuration for all appliances except the primary Database Server.
all. Run this command on the primary 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 (primary and secondary). Blocks future connection requests from Data Collectors and secondary Database Servers.

The close-control-port command is not available in SL1 version 11.2.0 or later; in this situation, use the clear command on a Database Server.
connect. Run this command from the Data Collectors, Message Collectors, or secondary Database Server. Starts communication between the primary Database Server and the Data Collector, Message Collector, or secondary Database Server.
delete appliance_ID. Run this command on the primary 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 primary Database Server and the Data Collector, Message Collector, or secondary Database Server.

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 primary 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 (primary and secondary). Adds an entry for the specified SSH port to the /etc/sysconfig/iptables file on the current server.

This command is not available in SL1 version 11.2.0 or later; in this situation, use the setup command on a Database Server.
reconnect. Run this command from the Data Collector(s), Message Collector(s), or secondary Database Server. Stops and then restarts communication between the primary 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 primary 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 primary Database Server. The Data Collector or Message Collector will then upload its public key to the primary Database Server and download its configuration for PhoneHome from the primary 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.

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 primary 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 primary 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 or Message Collectors. Downloads the current configuration for PhoneHome from the primary Database Server to the Data Collector or Message Collector.

token appliance_ID. Run this command from the primary 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 primary Database Server, upload a public key to the primary Database Server, and download the configuration for PhoneHome from the primary 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 primary 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 primary Database Server. If the connection is stale, the watchdog service automatically forces the primary 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.

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.

The monitor_phonehome Command

The monitor_phonehome utility is available to use when debugging or diagnosing PhoneHome related issues. It is especially useful when escalating a PhoneHome issue to ScienceLogic Support.

Troubleshooting the PhoneHome Configuration in SL1 Version 11.1.x and Earlier

Using the PhoneHome Troubleshooting Script

The troubleshooting tool for PhoneHome provides diagnostics about the connection between a Data Collector and a Database Server in the PhoneHome system.

This section applies only to SL1 version 11.1.0 and earlier.

To use the troubleshooting tool:

Either go to the console of a Data Collector or use SSH to access the Data Collector.
Enter the following at the shell prompt:

sudo phtb -h

Available Commands

This command checks the SSH connectivity between the Data Collector and the PhoneHome primary Database Server

sudo phtb destination

If the connection is healthy, the output looks like this:

Executing phonehome destination check

Running check for destination with host 52.70.238.48, port 7705, user phonehome13

=================================================================================

Remote server 52.70.238.48 reported back the status of this device (check command): [Status: forwarded, Summary: db (Alive), Phonehome status: operational]

SSH test to destination (Name: Phone Home database 11, IP: 52.70.238.48, Port: 7705) is successful

Destination check summary: [Total: 1, Skipped: 0, Success: 1, failed: 0]

If the connection is not healthy, the output looks like this:

Executing phonehome destination check

Running check for destination with host 10.152.2.100, port 7705, user phonehome13

=================================================================================

Failed to check destination 10.152.2.100 on port 7705. Error: dial tcp 10.152.2.100:7705: i/o timeout

Destination check summary: [Total: 1, Skipped: 0, Success: 0, failed: 1]

This command checks the SSH credentials.

sudo phtb probe-host <hostname or IP address of server> <port number> <username> <-p password or -k path to private key> <options>

Here is an example with output for correct credentials:

phtb probe-host 52.70.238.48 7705 phonehome13 -k /home/phonehome0/.ssh/id_rsa.pub

Executing probe for host 52.70.238.48 on port 7705

Successfully established SSH connection to host 52.70.238.48 on port 7705

Here is an example with output for incorrect credentials:

phtb probe-host 52.70.238.48 7705 em7admin -p em7admin

Executing probe for host 52.70.238.48 on port 7705

Failed to obtain SSH connection to host 52.70.238.48 on port 7705. Error: ssh: handshake failed: ssh: unable to authenticate, attempted methods [none], no supported methods remain

This command verifies the connection to a proxy server.

sudo phtb proxy <hostname or IP address of server> <port number> <optional -u username>

Here is an example with output for "no proxy found":

sudo phtb proxy 52.70.238.48 7705

Executing proxy check for host 52.70.238.48, port 7705

There is not any proxy configured for host 52.70.238.48. No further action needed.

Basic Troubleshooting

Problem	Possible Cause	Diagnostics
Can't register a server or sync a server	Confirm that the Data Collector can "see" the phonehome port on the Database Server.	At the command line of the server that can't sync or register: nmap -p port_number IP_address_of_database_server For example: nmap -p 7705 71.197.6.197
Can't register a server or sync a server	Confirm that the PhoneHome port is open on the firewall on the Database Server.	At the command line of the Database Server: iptables -nL You should see output that specifies that the port accepts connections. To open the port, run this command: sudo phonehome open-control-port
Can't register a server or sync a server	Ensure that the Data Collector has line-of-sight with the Database Server	sudo tcptraceroute <IP_address_of_database>
Can't register a server or sync a server	Ensure the Data Collector can initiate an SSH session to the phonehome port on the Database Server	sudo -u phonehome0 -s ssh -vvv -o StrictHostKeyChecking=no -p <control_port_(usually_7705)> phonehome<device_id_of_collector>@<IP_address_of_database> Output should include: Remote server string which specifies a version of OpenSSH SL1 trying various authentication methods until one succeeds or fails If authentication is attempted, this means that the Data Collector can establish a TCP connection on the control port to the Database Server
Can't register a server	Ensure that tunnel service is running on the Data Collector.	sudo systemctl status em7_ph_tunnels.service If the services is not running, force a sync using the following command: sudo phonehome sync
Problem with authentication	Ensure that the Data Collector is registered with the Database Server.
Problem with authentication	Check that that the public keys of the Data Collector(/home/phonehome0/.ssh/id_rsa.pub) are configured correctly.	Ensure that the public keys of the Data Collector(/home/phonehome0/.ssh/id_rsa.pub) are present in the following places: On the Database Server, in /home/phonehome<id>/.ssh/authorized_keys On the Database Server, in /home/phonehome<id>/remote_key file On the Database Server, in the database table sysinfo..phonehome_devices, find the row for the Data Collector. The pub column should contain the public keys
Forgot to copy the token for a server		phonehome token appliance_ID
Confirm that Data Collector(s) and/or Message Collector(s) are successfully configured for PhoneHome		At the command line of the Database Server: netstat –an \|grep –i listen \|grep “127.0.0.” \|grep 7707 Output displays each Data Collector and Message Collector that is listening for PhoneHome communications.