This the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

  • 1:
    • 2:
      • 3:

        Install with Replicated

        Sysdig will deprecate support for Replicated installs in the coming months. If you are a new customer considering installing with Replicated, please contact Sysdig support.

        Understand the Choice Points

        When planning an on-premises installation, the following choice points must be decided upon.

        1. Infrastructure Managers: To install Sysdig on-premises, administrators choose one of two infrastructure managers:

          • Kubernetes (see Installer (Kubernetes | OpenShift), or

          • Replicated: an easy-to-use orchestrator that includes a GUI management tool.

            This guide describes how to install the Replicated client and use it to install and manage the Sysdig platform.

        2. Single-Host or Multi-Host Install: For test or proof-of-concept installations, a single-host install will include all components; for production, a distributed environment is needed.

        3. Airgapped or non-airgapped environment:

          If your environment is accessible to the Internet during the install process, then the installation options include both script-based or GUI-based.

          In airgapped environments (no Internet access), you must download components into your airgapped repository, and can only use the GUI-based installation.

          See Airgapped Installation.

        4. Where to put the Replicated Management Console: When installing on-premises using Replicated as the orchestrator, the following Replicated components will be installed on your system:

          • Replicated UI (on a host you designate to host the Replicated Management Console)

          • Replicated retraced containers that handle logging (on the Management Console host only)

          • Replicated operator component (will go on all hosts)

        In a multi-host installation, one server will be the Replicated Management Console host. The system load for these components is minor.

        No matter which installation options you choose, you will use the Replicated GUI post-installation to:

        Understand the Installation Process

        1. Review and complete the Pre-Install requirements.

        2. If installing on multiple nodes, decide which node will host the Replicated Management Console.

        3. If using an airgapped environment, set up for an Airgapped Installation.

        4. Install the Replicated Clienton a host.

        5. Log In to the Replicated Management Console and set the Replicated Management Console Password.

        6. Configure Sysdig Admin Password and Basic Settings.

        7. Configure Sysdig Application Advanced Settings (if necessary).

        8. Complete Distributed Install Steps (if necessary).

        9. Restart the host(s).

        1 -

        Airgapped Installation

        Sysdig will deprecate support for Replicated installs in the coming months. If you are a new customer considering installing with Replicated, please contact Sysdig support.

        To install the Sysdig platform on-premises, in an environment that has no inbound or outbound paths available to internet traffic, you must use the Replicated GUI-based installation option. No script-based option is currently available.

        Perform the following steps to download the required Sysdig installation files, the Replicated components, and the Sysdig license file, and save them to a repository on your airgapped server. Then perform the setup steps in the Replicated Management Console, as described below.

        Prerequisites

        A server instance with Docker version 1.7.1 or later installed is required prior to installation.

        The Replicated .airgap installation script does not install docker-engine. Sysdig recommends using the latest version of Docker available for the server operating system.

        For more information on installing Docker in an airgapped environment, refer to the Installing Docker in an Airgapped Environment documentation.

        Instructions

        Download Components to a Repository

        1. Download the latest Sysdig installation files using the links provided by the Sysdig Sales Engineer:

          • The Sysdig platform application .airgap package

          • The Sysdig application license file (.rli)

          • (Optional) The Sysdig Agent Docker image

        2. Download the latest Replicated installation file from:

          https://s3.amazonaws.com/replicated-airgap-work/replicated.tar.gz

        3. Copy all downloaded files to a designated location on your airgapped server. For example:

          /var/tmp/sysdig

          (Note this path to be used when you complete the Install Components (Replicated).)

        4. Open a command shell on the airgapped server and extract the replicated.tar.gz file:

          sudo tar xzvf replicated.tar.gz
          

        Install and Set Up Replicated Management Infrastructure

        1. Run the following command to install the Replicated infrastructure manager:

          sudo cat ./install.sh | sudo bash -s airgap

        2. In a browser, navigate to the Replicated Management Console: https://server_address:8800 **(**Replace server_address with the server name/IP address.)

        3. Accept the default self-signed certificate, or provide a custom one, and click Continue.

        4. On the next screen, once the “preflight” checks have been resolved, select the Airgapped option, and click Continue.

        5. Upload the .rli license file.

        6. Provide a path to the Sysdig application .airgap file.

          Should you need to upgrade an airgapped license at a future time, see Upgrade an On-Premises License. For general license information, see Subscription.

        Complete the Installation Steps

        Continue with “Setting the Replication Management Password” and the rest of the installation steps in Install Components (Replicated).

        2 -

        Install Components (Replicated)

        Sysdig will deprecate support for Replicated installs in the coming months. If you are a new customer considering installing with Replicated, please contact Sysdig support.

        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.

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

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

        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.

        || ||

        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.

          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.

        • 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 **Cancel**to 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.

        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.

        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:

          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
          

          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.

          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.

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

          Choose Installation script or Docker run command option.

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

          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

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

          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

        3 -

        Post-Install Configuration

        Sysdig will deprecate support for Replicated installs in the coming months. If you are a new customer considering installing with Replicated, please contact Sysdig support.

        These configurations are optional.

        Replace a Self-Signed Cert with Custom Cert

        This process differs depending on how you installed the Sysdig Platform.

        For Kubernetes Installer Installs

        If you installed the Sysdig Platform on Kubernetes or OpenShift using the Installer, the Installer automatically generates a self-signed cert on the fly. To use a different certificate you would:

        • Add your cert and key to the /certs directory ex: (server.crt, server.key)

        • Update values.yaml:

          sysdig:
            certificate:
              crt: certs/server.crt
              key: certs/server.key
          
        • Rerun the Installer.

        The configuration_parameter.md Readme gives full details on sysdig.certificate.crt and sysdig.certificate.key.

        For Kubernetes Manual Installs

        If you installed the Sysdig Platform manually on Kubernetes or OpenShift, the steps for managing the certs are described in Step 5 of the installation procedures:

        For Replicated Installs

        If you installed the Sysdig Platform using Replicated and you accepted the self-signed certificate for SSL/TLS communication when installing the Sysdig components (see Define Basic Settings & License Info ), you can exchange for a custom certificate as follows:

        • Log in to the Replicated Management Console and select the Gear icon > Console Settings.

        • Click Upload certificate and it will automatically replace the original self-signed certificate.

        Optional: Custom Self-Signed Certificat

        Sysdig Monitor/Cloud/etc uses a self-signed SSL/TLS security certificate, unless a custom certificate is provided.

        The example command below creates a custom, unsigned certificate called MyCert.pem; the certificate has a private key called MyCert.key, and is valid for five years:

        sudo openssl req -new -x509 -sha256 -days 1825 -nodes -out ./MyCert.pem -keyout ./MyCert.key