Sysdig Documentation

Install Components (Replicated)

You can use the Replicated UI to install the Sysdig platform on either a single host or on multiple hosts. If multi-host, decide which machine will also run the Replicated Admin Console and begin there.

Note

If your environment is "airgapped" (no access to inbound or outbound internet traffic), there are some setup steps you must perform before doing the GUI-based Replicated installation.

See Airgapped Installation for details.

Install the Replicated Client

Log in to the chosen machine with a shell and run a command to install the Replicated components. You can also install Docker if it's not already on the environment.

  1. Log into the designated server instance with SSH.

  2. Run the following commands:

    a. To install the Replicated Infrastructure and Docker:

    sudo curl -sSL https://install.sysdigcloud.com/docker | sudo bash

    b. If Docker is already installed on the server instance, add-s --no-dockerto the command:

    sudo curl -sSL https://install.sysdigcloud.com/docker | sudo bash -s -- no-docker

    c. If installing the Replicated Infrastructure behind a proxy, modify the installation command as shown below:

    sudo curl -sSL -x http://<proxy>:<port> -o /tmp/sdc-onpremises-installer.sh https://install.sysdigcloud.com/docker && bash /tmp/sdc-onpremises-installer.sh http-proxy=http://<proxy>:<port>

Define Basic Settings & License Info

Log In to Replicated Admin Console/ "admin console" and Set SSL Certificate

  1. As prompted, open the Replicated Client at https://<yourserver>:8800.

  2. Supply the DNS hostname for the Replicated Admin Console.

  3. Accept the self-signed certificate, or upload a custom SSL certificate and private key.

    Note

    Note: If a self-signed certificate is uploaded, it must include the end user, all intermediate, and the root certificates, as the certificate will be used by the Sysdig platform, as well as for the Replicated Admin Console.

    To later replace a self-sign cert with a custom cert, see Replace a Self-Signed Cert with Custom Cert.

    373573422.jpg
  4. Click the Choose License button, and upload the Sysdig license file supplied from Sysdig Sales.

  5. Choose Online installation option if prompted.

Set the Replicated Admin Console Password

Once the Sysdig license validation is complete, secure the Replicated Admin Console using a local password, LDAP user account, or anonymous access (insecure).

373573408.jpg

Note

Sysdig recommends securing the console with either a local password or LDAP user account.

Click Continue.

Configure Sysdig Super Admin Password and Basic Settings

After clicking Continue, the Settings page is displayed. Here you enter the configuration information that will be used by Replicated to orchestrate the Sysdig installation.

373573443.jpg

Configure the Basic Settings for the Sysdig installation

  • Hostname: The host name where the Replicated Admin Console is installed (re-enter).

    By default, the value is the admin server's public IP. If the Sysdig Monitor instance is installed behind a private network, firewall, or proxy, configure the hostname to the server's private address or routable DNS.

  • Admin User/Default User: The Sysdig administrator (super admin) Email and Password.

    Save this account information in a secure place.

    See also "System-Based Privileges" in User and Team Administration, and Find the Super Admin Credentials and API Token for more information on this role.

SMTP Relay ConfigurationThis information will be used for e-mail notifications. See also Notifications Management.

  • SMPT Server Endpoint: URL of SMTP server to be used for email notifications.

  • SMTP Port: default 25. Port to be used for email communication.

  • Username (SMTP): default blank.

  • Password (SMTP): default blank.

  • SMTP Secure: Choose encryption if needed.

  • Email Header Configuration: Optional setting for the "From" field in Notifications.

    See also Notifications Management.

Click Show Advanced Settings to continue.

Note: Advanced Settings are defined after consultation with a Sysdig Sales Engineer.

Define Advanced Settings

These settings are typically defined with consultation from a Sysdig Sales Engineer.

 

Any JVM options to be passed to the application, such as memory constraint settings for the Java Virtual Machine components, proxy settings, etc.

At a minimum, it is recommended to define the memory constraints, in the format:

-Xms###g Xmx###g.

Note that if multiple components are on a single machine, adjust the percentages as needed so JVMs all fit in a node.

  • Cassandra JVM options: recommended allocating 50% of the host's memory to this JVM

    (in a multi-node environment)

  • Elasticsearch JVM options: recommended allocating 50% of the host's memory to this JVM

    (in a multi-node environment)

  • Sysdig Cloud application JVM options: recommended to allocate up to 80% of the host's memory to this JVM.

    This is also used to set proxy settings; see HTTP/HTTPS and Proxy Support.

    It is also used to set an implicit key in AWS; see AWS: Integrate AWS Account and CloudWatch Metrics (Optional).

    NOTE: If you do not want to use SSL between the agent and the collectors, you append the following settings to the Sysdig Cloud application JVM options entry:

    -Ddraios.agents.installParams.sslEnabled=false

    For example:

    -Xms8G Xmx8G -Ddraios.agents.installParams.sslEnabled=false

Ports and Security

  • Sysdig UI port: default 80. Port used for the Sysdig Monitor/ Sysdig Secure GUI.

  • Sysdig UI secure port: default 433. SSL port used for Sysdig Monitor/ Sysdig Secure GUI.

  • Force HTTPS: This turns off the unsecured port (80) access.

  • Forward Sysdig application logs to stdout: switches logging from the application log files to Linux standard output (stdout).

  • Sysdig collector port: default 6443. Port used for agent metrics collection. See also Agent Installation.

    Note

    In earlier versions, the Sysdig Agent connected to port 6666. This behavior has been deprecated, as the Sysdig agent now connects to port 6443.

  • Sysdig secure collector port: default 6443. Port used for agent metrics collection. See also Agent Installation.

  • Exposed port for HTTP traffic inbound to Sysdig Platform backend container: 27878 – do not change without the recommendation of Sysdig Support.

  • Exposed port for Collector traffic inbound: 27877 – do not change without the recommendation of Sysdig Support.

Database Entries

  • Store Sysdig Captures in Cassandra (recommended): Default checked. Used for Sysdig trace file storage when capture function is used. If you do not store files in the Cassandra DB, you can alternately configure an AWS S3 bucket storage location.

    See also: Storage: Configure AWS Capture File Storage (Optional) and Captures.

  • Sysdig data directory: default /opt. Where Cassandra, MySQL, and Elasticsearch databases will be created on a host.

  • Cassandra CQL native client's port: The default port is 9042. Change the default port if you are running your own Cassandra cluster with non-standard ports.

  • Cassandra replication factor: The value should be either 1 or 3, never 2.

  • Sysdig MySQL user: default admin, recommend changing

  • Sysdig MySQL password: Enter a unique password and store securely.

  • Warning

    This password is needed for future updates and will not be visible in the Replicated Admin Console. Retain this password for future use.

  • Sysdig MySQL max connections: The default is 1024.

  • Cassandra CQL native client's port: The default is 9042.

  • External MySQL service: The secure end of your MySQL service. This is external to the Sysdig platform.

  • External Cassandra service: The secure end of your Cassandra service. This is external to the Sysdig platform.

  • External Redis service: The secure end of your Redis Service. This is external to the Sysdig platform.

  • Sysdig Redis password: The password associated with the Redis account.

  • External Elasticsearch service URL: An external service URL with user name and password embedded

  • OAuth allowed domains: List of secure Elasticsearch domains.

  • Google OAuth client ID: Used when integrating Google-based user login.

    See Google OAuth (On-Prem)

  • Google OAuth client secret: Used when integrating Google-based user login. See Google OAuth (On-Prem)

  • SSO CA certificate: CA certificate for single sign-on.

  • Datastore Authorization and SSL: See Authenticating Backend Components on Cassandra and Authenticating Backend Components on Elasticsearch.

When fields are complete, click Save.

After Saving, click Start Now to apply settings to the environment immediately. Click Cancelto apply settings at a later time.

Authenticating Backend Components on Cassandra

As of version 2.4.1, authenticating Sysdig backend components on Sysdig's Cassandra nodes or for your own Cassandra nodes is supported. In order to authenticate the backend components to Cassandra, enable the option, specify credentials of the identity you want to establish with Cassandra, and enable secure communication. This is the additional layer of defense against unauthorized access to the datastore.

Figure 2. Enable Cassandra Authentication
Enable Cassandra Authentication


  • Enable Cassandra authentication: Select this option if you want to authenticate Sysdig backend components to use Cassandra datastore. The option by default is disabled.

  • Cassandra password for authentication: The password associated with the username. If running Sysdig's Cassandra database, create a password here. If you are using your own Cassandra database, enter the appropriate user password for Sysdig access.

  • Enable Cassandra TLS: (Mandatory) Establish TLS communication between the Sysdig backend components and the Cassandra node. The option by default is unchecked.

  • Cassandra username for authentication: The username of the identity that you want to establish with Cassandra. If running Sysdig's Cassandra database, create a user here.  If you are using your own Cassandra database, enter the appropriate user account for Sysdig access.

Authenticating Backend Components on Elasticsearch

As of version 2.4.1, authenticating Sysdig backend components on both Sysdig's Elasticsearch cluster or for your own Elasticsearch cluster is supported. In order to authenticate the backend components to Elasticsearch datastore, configure TLS-based authentication. You generate certificates and keys for Elasticsearch server, client, and admin user, and specify them along with Elasticsearch user credentials while setting up Sysdig platform. This is the additional layer of security to safeguard the datastore.

Before you configure Elasticsearch authentication, ensure that you set up Sysdig Agent for data collection and TLS generate certificates.

Generate TLS Certificates

  1. Log into Quay:

    1. Locate your Quay pull_secret. Contact Support if you are unable to locate it.

    2. Get your credentials by running:

      # Note: For MacOS users, change "base64 -d" to "base64 -D"echo <quay_pull_secret> | base64 -d | awk NR==4 | cut -d'"' -f4 | xargs | base64 -d

      The Output should look as follows:

      sysdig+<your_username>:<your_password>
    3. Log into Quay by running the following:

      docker login quay.io -u sysdig+<your_username> -p <your_password>
  2. Run the following docker command to generate the root/admin certificates for Elasticsearch to a directory within the current working directory:

    docker run -d -v "$(pwd)"/generated_elasticsearch_certs:/tools/out quay.io/sysdig/elasticsearch:1.0.1-es-certs

    The following files are generated in the generated_elasticsearch_certs directory.  Retain the certificates and key files to upload as part of the TLS configuration as described in Configure TLS Authentication.

    • Elasticsearch root CA

      • root-ca.pem

      • root-ca.key

    • Elasticsearch Admin (Kirk)

      • kirk.pem

      • kirk.key

    • EElasticsearch Client (Spock)

      • spoke.pem

      • spoke.key

Configure TLS Authentication

Sysdig Replicated install supports Search Guard to establish secure authentication with Elasticsearch datastore. You set up two users in order to access Elasticsearch datastore on behalf of the Sysdig backend components: Admin user and read-only user.

Amin user: The admin user will have the read and write permissions on Elasticsearch clusters and indices. Sysdig backend components use this identity to write data to Elasticsearch clusters. This is the same as the Search Guard admin user. 

Read-only user: As the name implies, the read-only user will only have the read permission on Elasticsearch indices. Sysdig Agent uses this identity to read data from Elasticsearch datastore. This is the same as the Search Guard sg_readonly user that is created as part of the installation.

Figure 3. Enable Elasticsearch authentication
Enable Elasticsearch authentication


  • Enable Elasticsearch Authentication and TLS:  Select this option to enable authentication and secure communication between Sysdig backend components and the Elasticsearch datastore. To gain access to Elasticsearch datastore, you must prove your identity, by using credentials and certificates. The Elastic Stack authenticates users by identifying the users behind the requests that hit the datastore and verifying that they are who they claim to be.

  • Elasticsearch admin username: The admin user is created by default. You can edit the user name if desired. The default user is admin.

  • Elasticsearch admin password: The password associated with the Elasticsearch admin user.

  • Elasticsearch read-only username: Specify the username for the read-only access to the Elasticsearch indices. If running your own secure Elasticsearch cluster, enter the username for the read-only Search Guard user.

  • Elasticsearch read-only password: The password associated with Elasticsearch read-only username.

When fields are complete, click Save. 

After saving, click Restart Now to apply settings to the environment immediately.

Click Cancel to apply settings at a later time.

Configure Sysdig Agent

If you are monitoring Elasticsearch with sysdig-agent, ensure the sysdig-agent configuration file, dragent.yaml, has the following Elasticsearch configuration in the data.dragent.yaml.app_checks section below:

app_checks:
  - name: elasticsearch
    check_module: elastic
    pattern:
      port: 9200
      comm: java
    conf:
      url: https://<DNS_or_ip_address_to_elasticsearch>:9200
      username: <your_read_only_username>
      password: <your_read_only_password>
      ssl_verify: false
Example for Docker Environment
  1. Follow these steps if you are running the Agent in a Docker container:

    READONLY_USERNAME=<your_readonly_username>
    READONLY_PASSWORD=<your_readonly_username_password>
    ELASTICSEARCH_PORT=9200
    URL_TO_SECURE_ELASTICSEARCH=https://<your_url_to_secure_elasticsearch>
    ADDITIONAL_CONF="$(echo "app_checks:
      - name: elasticsearch
        check_module: elastic
        pattern:
          port: $ELASTICSEARCH_PORT
          comm: java
        conf:
          url: $URL_TO_SECURE_ELASTICSEARCH:$ELASTICSEARCH_PORT
          username: $READONLY_USERNAME
          password: $READONLY_PASSWORD
          ssl_verify: false
    " | sed -e ':a' -e 'N' -e '$!ba' -e 's/\n/\\n/g')"
  2. Remove the existing Agent container:

    Warning

    Make sure that you remove the existing Agent container instead of just stopping it. By default, the Agent container is named sysdig-agent. If you stop the Agent container and attempt to create a new one, you will get a name-conflict error:

    docker: Error response from daemon: Conflict. The container name "/sysdig-agent" is already in use by container <ontainer-id>. You have to remove (or rename) that container to be able to reuse that name.

  3. Run the Agent container with the new additional config. For example:

    docker run \
        --name sysdig-agent \
        --restart always
        --privileged \
        --net host \
        --pid host \
        -e ACCESS_KEY=1234-your-key-here-1234 \
        -e COLLECTOR=collector_ip
        -e COLLECTOR_PORT=6443
        -e SECURE=true
        -e TAGS=dept:sales,local:NYC \
        -e ADDITIONAL_CONF="$ADDITIONAL_CONF" \
        -v /var/run/docker.sock:/host/var/run/docker.sock \
        -v /dev:/host/dev \
        -v /proc:/host/proc:ro \
        -v /boot:/host/boot:ro \
        -v /lib/modules:/host/lib/modules:ro \
        -v /usr:/host/usr:ro \
        sysdig/agent

    Note

    You may encounter an error in the sysdig-agent logs stating that an unverified HTTPS request has been made. You can safely ignore the error for now.

Example for Non-Containerized Environment

Do the following if you are running the Agent directly on the machine (non-containerized environment):

  1. Add the app_check configuration to your /opt/draios/etc/dragent.yaml configuration:

    app_checks:
      - name: elasticsearch
        check_module: elastic
        pattern:
          port: 9200
          comm: java
        conf:
          url: https://<DNS_or_ip_address_to_elasticsearch>:9200
          username: <your_read_only_username>
          password: <your_read_only_password>
          ssl_verify: false
  2. Restart the agent:

    service dragent restart

Single-Host Installation Wrap-Up

After completing the Settings and restarting, no further installation steps are required for a single-host install.

The dashboard will remain in Starting mode for approximately 4-5 minutes, depending on the internet connection bandwidth, while Sysdig application software is downloaded and installed. Once the installation is complete, the dashboard will move to Started mode.

  1. Click the Open link to navigate to the Sysdig Monitor login panel.

  2. Input the Super Admin user login credentials defined in the basic settings, above.

Next Steps

  • To start, stop, and update the application, or to retrieve support information, use the Replicated Admin Console: https://<yourserver>:8800.

  • To login as a user and see metrics for hosts with the Sysdig Agent installed, use the Sysdig Monitor Web Interface: https://<yourserver>:80

    • If you have not yet done so, install Sysdig Agents to monitor your environment. See Agent Installation for details.

Multi-Host Installation Wrap-Up

After configuring the settings and clicking Start Now, an error will indicate the need to assign and install the remaining components. You will need to define the hosts/nodes to be used and will assign the Sysdig components to be installed on them. The steps below describe the actions on one host; they must be repeated on all applicable hosts and all the Sysdig components must be assigned.

  1. Choose the Cluster tab in the Replicated Admin Console.

    373573429.png

    From here, you can tag components to be run on the local host, and/or add new nodes.

    To add and configure new nodes:

  2. Click Add Node.

    The Add Node worksheet is displayed. Here you enter the IP address and then tag the Sysdig component(s) to be installed on that node.

    Replicated will compile either an installation script or a Docker run command out of your entries, which you will copy and use on the given node.

    373573401.jpg
  3. On the Add Node worksheet page, do the following:

    1. Choose Installation script or Docker run command option.

    2. Enter private and/or public IP address, depending on the type of access you want to permit.

    3. Select the Sysdig components to be installed by checking the appropriate "Tags" buttons.

      Descriptions in the table below:

      Name

      Tag

      Role Description

      api

      api

      Application Programming Interface server

      cassandradb

      cassandra

      Cassandra database server

      elasticsearch

      elasticsearch

      Elasticsearch server for events storage/search

      collector

      collector

      Agent metrics collector

      lb_collector

      lb_collector

      Load balancer for collector service; handles connections from the agents

      lb_api

      lb_api

      Load balancer for API service; handles user connection requests to the Sysdig application.

      Use the address for this node as the DNS entry for the cluster.

      mysql, redis

      mysql & redis

      MySQL & Redis databases

      worker

      worker

      Metrics history processor

      emailrenderer

      emailrenderer

      Email renderer

      nginxfrontend

      nginxfrontend

      Frontend static server

      Note

      When setting up a DNS entry for the cluster, use the address for the 'lb_api' node.

    4. At the bottom of the page, a curl script or Docker run command is compiled for you.

      Copy the command and issue it on the targeted host.

  4. Repeat this procedure on all desired hosts.

  5. Restart the Sysdig application from the Replicated console.

    The dashboard will be in “Starting” mode for several minutes while software is downloaded and installed onto each server component (depending on your internet connection bandwidth).

    You should see green check marks for each host next to the Provisioned and Connected columns, as the software is installed and the node connects successfully to the Replicated Admin server.

    Once the installation is fully completed, the infrastructure admin dashboard will be in “Started” mode and will also show the “Open” link that will bring you to Sysdig Monitor web interface login screen.

  6. At the login screen, use the credentials configured earlier (Default User) to log in and start using the Sysdig application on-premises solution.

    To start, stop, and update the application or retrieve support information use the Replicated Admin dashboard: https://server_address:8800

    To log in as a user and see metrics about hosts where Sysdig agents are installed, use the Sysdig Monitor UI: https://server_address:80