The term
“on-premises” (or
“on-prem”) is both industry-standard and evolving, so it means different
things to different people.
In the context of Sysdig, on-prem customers install and manage the
Sysdig backend components as they see fit. This could be in a data
center, or in an enterprise’s cloud-provider space, such as AWS or GKE.
With version 3.6.0, the Sysdig Platform can no longer be installed using
Replicated.
Oversight Services Now Offered for All Installs and Upgrades
As part of our continued focus on our customers, we are now offering
oversight services for all on-premise installs and upgrades. Your
Technical Account Manager (TAM), in conjunction with our support
organization and Professional Services [where applicable], will work
with you to:
Assess your environment to ensure it is configured correctly
Review your infrastructure to validate the appropriate storage
capacities are available
Review and provide recommendations for backing up your Sysdig data
Work with you to ensure our teams are ready to assist you during the
install and upgrade process
Provide the software for the install
Be available during the process to ensure a successful deployment
You can always review the process in the documentation on
GitHub (v. 3.6.0+) or
the standard docs site
(for older versions).
If you are a new customer looking to explore Sysdig, please head over
here to sign up for a trial on
our SaaS Platform. Alternatively, you can contact us
here.
1 - Architecture & System Requirements
Before installing an on-premises solution, review the Sysdig
architecture, sizing tips, configuration options, and installation
options.
Each on-premise release is tested on several platforms and
Kubernetes orchestrators. You can find the the official matrix in
the onprem-install-docs repository. Click
the on-premise version and navigate to the release notes page
to view the supported platforms.
The actual installation instructions can be found in the onprem-install-docs repository.
1.1 - Architecture
Review the diagram and component descriptions. When installing
on-premises, you can decide where to deploy various components.
Sysdig Agent
Sysdig will collect monitoring and security information from all the
target entities. To achieve this, one Sysdig agent should be deployed in
each host. These hosts can be:
The nodes that make up a Kubernetes or OpenShift cluster
Virtual machines or bare metal
Living in a cloud environment (i.e. AWS, Google Cloud, IBM Cloud,
Azure, etc.) or on the customer’s premises
The Sysdig agent can be installed as a container itself using a Helm
chart, Kubernetes operator, etc.
Once the agent is installed in the host it will automatically start
collecting information from the running containers, container runtime,
the orchestration API (Kubernetes, OpenShift, etc), metrics from defined
Prometheus endpoints, auto-detected JMX sources, StatsD, and
integrations as well as the host
itself.
The Sysdig agent maintains a permanent communication channel with the
Sysdig backend which is used to encapsulate messages containing the
monitoring metrics, infrastructure metadata, and security events. The
channel is protected using standard TLS encryption and transports data
using binary messages. Using this channel, the agent can transmit data,
but also receive additional configuration from the backend, such as
security runtime policies or benchmarks.
Sysdig Backend
The Sysdig backend is used directly in its SaaS version, thus being
managed transparently by Sysdig Inc., or it can also be installed on the
customer’s premises. This distinction does not affect the operation of
the platform described below.
Once the agent messages are received in the backend, they are processed
and extracted into data available to the platform - time series,
infrastructure and security events, and infrastructure metadata.
The main components of the backend/platform include:
Extraction and post-processing of the metric data from the agent, so
that full time-series, with all the necessary infrastructure
metadata, is available to the user
Maintenance of the infrastructure metadata (most notably Kubernetes
state), so that all events and time series can be enriched and
correctly grouped
Storage of time-series and event data
Processing of time-series data to calculate alert triggers
Queuing the security events triggered by the agents to be shown on
the event feed, notifying by the configured notification channels
and alerts and forwarding via the Event Forwarder to external
platforms like Splunk, Syslog or IBM MCM / Qradar
Aggregating and post-processing other security data such as
container fingerprints that will be used to generate container
profiles, or security benchmark results.
The Sysdig platform then stores this post-processed data in a set of
internal databases that will be combined by the API service to create
the data views, such as dashboards, event feeds, vulnerability reports,
or security benchmarks.
Sysdig APIs
The Sysdig platform provides several ways to consume and present its
internal data. All APIs are RESTful, HTTP JSON-based, and secured using
TLS. The same APIs are used to power the Sysdig front end, as well as
any API clients (such as sdc-cli).
Monitor API
User and Team management API
Dashboard API
Events API
Alerts API
Data API (proprietary Sysdig API for querying time-series data)
Secure API
Image Scanning API
Security Events API
Activity Audit API
Secure Overview API
PromQL API: Prometheus compatible HTTP API for querying time
-series data
These enable different use cases:
User access to the platform via the Sysdig user interface
Programmatic input and extraction of data, i.e.
Automatic user creation
Terraform scripts to save or recover configuration state
Inline scanning to push scanning results from the CI/CD pipeline
PromQL API interface that can be used to connect any
PromQL-compatible solutions, such as Grafana.
1.2 - System Requirements
Supported Distributions
Linux Distributions
A 64-bit Linux distribution with a minimum kernel version of 3.10, and
support of docker-engine 1.7.1 or later, is required for each server
instance.
Recommended Linux distributions: RedHat, Ubuntu, Amazon AMI, Amazon
Linux 2.
Docker Requirements
For the Docker installation, running devicemapper in ’loopback mode'
is not supported. It has known performance problems and a different
storage driver should be used.
Installing the latest version of Docker is recommended.
Cassandra
Cassandra is used as the metrics store for Sysdig agents. It is the most
dynamic component of the system, and requires additional attention to
ensure that your system is performing well and highly responsive.
This component is stateful, and should be treated more carefully than
stateless components. Cassandra sizing is based on a minimum replication
factor as well as the number of agents writing data.
A minimum replication factor of 3 is recommended for the Sysdig
application, which allows the cluster to survive the failure of 1
Cassandra instance.
Each agent consumes anywhere from 500MB to 2GB of Cassandra storage,
with average sizing at 1.5GB/agent. Because of Sysdig’s data aggregation
model, this storage should comfortably handle multi-year history. This
needs to then be multiplied by the replication factor to determine the
total disk space required. A rough calculation might be:
100 agents = 150GB raw, X replication factor of 3, = 450GB total
To be safe we recommend that you size some additional disk space as
buffer (say 25-50%) on top of that.
Network Configuration
The following firewall/security configurations are required for inbound
and outbound traffic for the Sysdig platform:
Replicated Management Console access (for on-premises installations that don't use Kubernetes)
Warning: Port 6666 should only be opened if agents will be
communicating with the collectors without encryption.
Additional ports may need to be configured for the Replicated
infrastructure manager. Refer to the Replicated port
requirements
documentation for more information.
HTTP/HTTPS and Proxy Support
All non-airgapped hosts require outbound HTTP/S internet access for:
License validation
Pulling Sysdig/Agent containers from the Docker hub repository
Release update checks
Note: Sysdig does not support HTTP/S proxies for Sysdig platform
components.
Summary: Plan Proxy Support for Notification Channels, CloudWatch Metrics, Capture Storage
In release #760 and newer of the Sysdig platform back-end, an option is
available to configure outgoing HTTP/HTTPS connections to be made via
proxy. This has been tested and supports outgoing web connections that
are necessary to support the following features:
Notification Channels
PagerDuty
Slack
Amazon SNS
VictorOps
OpsGenie
WebHook
Gathering of AWS CloudWatch data
Capture storage to an AWS S3 bucket
Proxied web connectivity to support authentication mechanisms (SAML.
OpenID Connect, OAuth) are not supported at this time.
Configure Proxy Using JVM Options
The proxy settings are configured via the JVM options passed to the
Sysdig software components. JVM options can be added/appended at any
time (with a required restart).
If JVM settings have already been set, log in to the Replicated
Management console and choose the Settings tab. At the bottom of
the screen, check the box to Show Advanced Settings to reveal
the configuration option.
# Optional: Sysdig Cloud application JVM options. For heavy load environments you'll need to tweak# the memory or garbage collection settingssysdigcloud.jvm.api.options:""sysdigcloud.jvm.worker.options:""sysdigcloud.jvm.collector.options:""
Enter the proxy parameters, as in the example below.
This JVM options string will forward all HTTP and HTTPS traffic via
outgoing port 8888 on a proxy at hostname
proxy.example.com. The IP address may be
specified instead of hostname.
-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=8888 -Dhttps.proxyPort=8888 -Dhttps.proxyHost=proxy.example.com# Optional: Sysdig Cloud application JVM options. For heavy load environments you'll need to tweak# the memory or garbage collection settingssysdigcloud.jvm.api.options:-Xms2048m -Xmx2048m -Dhttp.proxyHost=xxx.xxx.sysdig.com -Dhttp.proxyPort=80 -Dhttps.proxyHost=xxx.xxx.sysdig.com -Dhttps.proxyPort=80
Exclusions
Do not use local host or 127.0.0.1. By default, HTTP/HTTPS requests
to localhost or 127.0.0.1 will not be directed by the back-end
toward any configured proxy, which is necessary for the functioning
of some web components internal to the Sysdig platform containers.
If you deploy the Sysdig platform in AWS, add an additional proxy
parameter
-Dhttp.nonProxyHosts=169.254.169.254
Rational: This provides a work-around for the backend occasionally
making HTTP requests to a special instance metadata
address
169.254.169.254, which is undesirable when using a proxy.
This IP address will be excluded from proxying by default in a
future release.
If you have additional proxy exclusions you wish to specify that are
unique to your environment, these can also be added using the pipe
separator.
For example, assume your deployment was in AWS and you also had a
webhook target 192.168.1.2 that was not reachable via your proxy.To
exclude both:
Replicated: your complete string to enter into the console for
Sysdig application JVM options would be:
Kubernetes: when setting the sysdigcloud.jvm.api.options and
sysdigcloud.jvm.worker.options in the
config.yaml
for the ConfigMap, the pipe separator must be double-escaped, such
as:
The Sysdig platform requires the system clocks to be closely
synchronized between hosts. When provisioning hosts for installation,
ensure the system clocks are synchronized.
Recommended: Install NTP to ensure all host clocks stay
synchronized.
1.3 - Securing User Passwords
For MySQL, Redis, and the initial “super admin”
user, a strong password
is recommended, 16-20 characters, alphanumeric.
For Cassandra and MySQL, it is also possible to set up third-party
authentication
For Redis, users can set up an SSH tunnel and Sysdig can connect
over this tunnel.
2 - On-Premises Installation
When planning to install Sysdig products on-premises, enterprises
should:
Organize resources for a test environment and the production
environment
Review the supported platforms and orchestrators.
You can find the the official matrix in the onprem-install-docs repository. Click
the on-premise version and navigate to the release notes page to view the supported platforms.
Oversight Services Now Offered for All Installs and Upgrades
As part of our continued focus on our customers, we are now offering
oversight services for all on-premise installs and upgrades. Your
Technical Account Manager (TAM), in conjunction with our support
organization and Professional Services [where applicable], will work
with you to:
Assess your environment to ensure it is configured correctly
Review your infrastructure to validate the appropriate storage
capacities are available
Review and provide recommendations for backing up your Sysdig data
Work with you to ensure our teams are ready to assist you during the
install and upgrade process
Provide the software for the install
Be available during the process to ensure a successful deployment
You can always review the process in the documentation on
GitHub (v. 3.6.0+) or
the standard docs site
(for older versions).
If you are a new customer looking to explore Sysdig, please head over
here to sign up for a trial on
our SaaS Platform. Alternatively, you can contact us
here.
2.1 - Installer (Kubernetes | OpenShift)
For v 3.6.0+, go to the GitHub
repo. On-prem
installation documentation is transitioning to GitHub.
For customers, the instructions in this section are for review purposes
only.
The Sysdig Installer tool is a binary containing a collection of scripts
that help automate the on-premises deployment of the Sysdig platform
(Sysdig Monitor and/or Sysdig Secure), for environments using Kubernetes
or OpenShift. Use the Installer to install or upgrade your Sysdig
platform. It is recommended as a replacement for the earlier Kubernetes
manual installation and upgrade procedures.
Installation Overview
To install, you will download the installer binary and a values.yaml
file for the version you’d like to install, provide a few basic parameters, and launch the Installer. In a normal installation, the rest is automatically configured and deployed.
You can perform a quick install if your environment has access to the
internet, or a partial or full airgapped installation, as needed. Each
is described below.
Use hostPath for static storage of Sysdig components
Use Kubernetes node labels and taints to run only Sysdig pods on
selected nodes in a cluster
Install vs Upgrade
With Sysdig Platform 3.5.0, the installer has been simplified from
previous versions. Upgrade differs from Install in that you run an
installer diff to discover the differences between the old and new
versions and then installer deploy for the new version.
If you are installing the Sysdig Platform for the first time, ignore the
For Upgrade Only step in the process.
If you are upgrading, check the Upgrade
notes before you begin.
Prerequisites
The installer must be run from a machine with kubectl/oc configured
with access to the target cluster where the Sysdig platform will be
installed. Note that this cluster may be different than where the Sysdig
agent will be deployed.
Requirements for Installation Machine with Internet Access
Network access to Kubernetes cluster
Network access to quay.io
A domain name you are in control of.
Additional Requirements for Airgapped Environments
Edited values.yaml with airgap registry details updated
Network and authenticated access to the private registry
Access Requirements
Sysdig license key (Monitor and/or Secure)
Quay pull secret
Storage Requirements
You may use dynamic or static storage on a variety of platforms to store
the Sysdig platform components (stateful sets). Different configuration
parameters and values are used during the install, depending on which
scenario you have.
Use Case 1: Default, undefined (AWS/GKE)
If you will use dynamic storage on AWS or GKE and haven’t configured any
storage class there yet, then the Quick Install streamlines the process
for you.
storageclassProvisioner: Enter aws or gke. The installer will
create the appropriate storage class and then use it for all the
Sysdig platform stateful sets.
storageclassName: Leave empty.
Use Case 2: Dynamic, predefined
It is also possible that you are using dynamic storage but have already
created storage classes there. This dynamic storage could be AWS, GKE,
or any other functioning dynamic storage you use. In this case, you
would enter:
storageclassProvisioner: Leave empty; anything put here would be
ignored.
storageclassName: Provide the name of the pre-configured storage
class you want to use. The installer will use this storage class for
all the Sysdig platform stateful sets.
Use Case 3: Static Storage
In cases where dynamic storage is not available, you can use static
storage for the Sysdig stateful sets. In this case, you would use:
storageclassProvisioner: Enter hostpath, then define the nodes
for the four main Sysdig components: ElasticSearch, Cassandra,
MySQL, and Postgres.storageclassProvisioner
If you have the default use case, enter aws or gke in the
storageClassProvisioner field. Otherwise, refer to Use Case 2
or 3.
sysdig.license: Sysdig license key provided with your Sysdig
purchase confirmation mail
sysdig.dnsname: The domain name the Sysdig APIs will be
served on. Note that the master node may not be used as the DNS
name when using hostNetwork mode.
sysdig.collector.dnsName: (OpenShift installs only) Domain
name the Sysdig collector will be served on. When not configured
it defaults to whatever is configured for sysdig.dnsName. Note
that the master node may not be used as the DNS name when using
hostNetwork mode.
deployment: (OpenShift installs only) Add
deployment: openshift to the root of the values.yaml file.
sysdig.ingressNetworking: The networking construct used to
expose the Sysdig API and collector.Options are:
hostnetwork: sets the hostnetworking in the ingress
daemonset and opens host ports for api and collector. This
does not create a Kubernetes service.
loadbalancer: creates a service of type loadbalancer and
expects that your Kubernetes cluster can provision a load
balancer with your cloud provider.
nodeport: creates a service of type nodeport.The node
ports can be customized with:
sysdig.ingressNetworkingInsecureApiNodePort
sysdig.ingressNetworkingApiNodePort
sysdig.ingressNetworkingCollectorNodePort
When not configured, sysdig.ingressNetworking defaults to
hostnetwork.
If doing an airgapped install , you would also edit the
following values:
- **airgapped\_registry\_name:** The URL of the airgapped
(internal) docker registry. This URL is used for installations
where the Kubernetes cluster can not pull images directly from
Quay
- **airgapped\_repository\_prefix:** This defines custom
repository prefix for airgapped\_registry. Tags and pushes
images as
`airgapped_registry_name/airgapped_repository_prefix/image_name:tag`
- **airgapped\_registry\_password:** The password for the
configured airgapped\_registry\_username. Ignore this parameter
if the registry does not require authentication.
- **airgapped\_registry\_username:** The username for the
configured airgapped\_registry\_name. Ignore this parameter if
the registry does not require authentication.
[For Upgrades Only:]
[Generate and review the diff of changes the installer is about to
introduce:
./installer diff
This will generate the differences between the installed environment
and the upgrade version. The changes will be displayed in your
terminal.
If you want to override a change, based on your environment’s custom
settings, then contact Sysdig Support for assistance.]
Save the values.yaml file in a secure location; it will be used for
future upgrades. There will also be a generated directory containing various Kubernetes
configuration yaml files that were applied by the Installer against
your cluster. It is not necessary to keep the generated directory, as
the Installer can regenerate it consistently with the same
values.yaml file.
Airgapped Installation Options
The installer can be used in airgapped environments, either with a
multi-homed installation machine that has internet access, or in an
environment with no internet access.
This assumes a private docker registry is used and the installation
machine has network access to pull from quay.io and push images to the
private registry.
The Prerequisites and workflow are the same as in the Quickstart Install
(above) with the following exceptions:
In step 2, add the airgap registry information
After step 3, make the installer push Sysdig images to the airgapped
registry by running:
./installer airgap
That will pull all the images into the images_archive directory as
tar files and push them to the airgapped registry.
If you are upgrading, run the diff as directed in Step 4.
Run the installer:
./installer deploy
Full Airgap Install
This assumes a private docker registry is used and the installation
machine does not have network access to pull from quay.io, but can push
images to the private registry.
In this situation, a machine with network access (called the “jump
machine”) will pull an image containing a self-extracting tarball which
can be copied to the installation machine.
Access Requirements
Sysdig license key (Monitor and/or Secure)
Quay pull secret
Anchore license file (if Sysdig Secure is licensed)
If you have the default use case, enter aws or gke in the
storageClassProvisioner field. Otherwise, refer to Use Case 2
or 3.
sysdig.license: Sysdig license key provided with your Sysdig
purchase confirmation mail
sysdig.dnsname: The domain name the Sysdig APIs will be
served on. Note that the master node may not be used as the DNS
name when using hostNetwork mode.
sysdig.collector.dnsName: (OpenShift installs only) Domain
name the Sysdig collector will be served on. When not configured
it defaults to whatever is configured for sysdig.dnsName. Note
that the master node may not be used as the DNS name when using
hostNetwork mode.
deployment: (OpenShift installs only) Add
deployment: openshift to the root of the values.yaml file.
sysdig.ingressNetworking: The networking construct used to
expose the Sysdig API and collector.Options are:
hostnetwork: sets the hostnetworking in the ingress
daemonset and opens host ports for api and collector. This
does not create a Kubernetes service.
loadbalancer: creates a service of type loadbalancer and
expects that your Kubernetes cluster can provision a load
balancer with your cloud provider.
nodeport: creates a service of type nodeport.The node
ports can be customized with:
sysdig.ingressNetworkingInsecureApiNodePort
sysdig.ingressNetworkingApiNodePort
sysdig.ingressNetworkingCollectorNodePort
airgapped_registry_name: The URL of the airgapped
(internal) docker registry. This URL is used for installations
where the Kubernetes cluster can not pull images directly from
Quay
airgapped_repository_prefix: This defines custom
repository prefix for airgapped_registry. Tags and pushes
images as
airgapped_registry_name/airgapped_repository_prefix/image_name:tag
airgapped_registry_password: The password for the
configured airgapped_registry_username. Ignore this parameter
if the registry does not require authentication.
airgapped_registry_username: The username for the
configured airgapped_registry_name. Ignore this parameter if
the registry does not require authentication.
Copy the tarball file to the directory where you have your
values.yaml file.
NOTE: This step will extract the images into the
images_archive directory relative to where the installer was run
and push the images to the airgapped_registry.
[For Upgrades Only:]
[Generate and review the diff of changes the installer is about to
introduce:
./installer diff
This will generate the differences between the installed environment
and the upgrade version. The changes will be displayed in your
terminal.
If you want to override a change, based on your environment’s custom
settings, then contact Sysdig Support for assistance.]
Save the values.yaml file in a secure location; it will be used for
future upgrades.
There will also be a generated directory containing various Kubernetes
configuration yaml files that were applied by the Installer against
your cluster. It is not necessary to keep the generated directory, as
the Installer can regenerate it consistently with the same
values.yaml file.
Updating Vulnerability Feed in Airgapped Environments
NOTE: Sysdig Secure users who install in an airgapped environment do
not have internet access to the continuous checks of vulnerability
databases that are used in image scanning. (See also: How Sysdig Image
Scanning
Works.)
As of installer version 3.2.0-9, airgapped environments can also
receive periodic vulnerability database updates.
When you install with the “airgapped_” parameters enabled (see Full
Airgap
Install
instructions), the installer will automatically push the latest
vulnerability database to your environment. Follow the steps below to
reinstall/refresh the vuln db, or use the script and chron job to
schedule automated updates (daily, weekly, etc.).
To automatically update the vulnerability database, you can:
Schedule a chron job to run the script on a chosen schedule (e.g. every
day):
08***feeds-database-update.sh >/dev/null 2>&1
Output
A successful installation should display output in the terminal such as:
All Pods Ready.....ContinuingCongratulations, your Sysdig installation was successful!You can now login to the UI at "https://awesome-domain.com:443" with:username:"configured-username@awesome-domain.com"password:"awesome-password"
There will also be a generated directory containing various Kubernetes
configuration yaml files which were applied by installer against your
cluster. It is not necessary to keep the generated directory, as the
installer can regenerate consistently with the same values.yaml file.
Additional Installer Resources
To see all the configuration parameters available, as well as their
definitions, values, and examples, see
configuration_parameters.md
on GitHub. Please note that this is for version 5.1.4 of the installer.
The available fields for SMTP configuration are documented in the
configuration_parameters.md. Each includes SMTP in its name. For
example:
sysdig:...smtpServer:smtp.sendgrid.netsmtpServerPort:587#User,Password can be empty if the server does not require authenticationsmtpUser:apikeysmtpPassword:XY.abcdefghijk...smtpProtocolTLS:truesmtpProtocolSSL:false#Optional Email HeadersmtpFromAddress:sysdig@mycompany.com
To configure email settings to be used for a notification
channel, copy the
parameters and appropriate values into your values.yaml.
Use hostPath for Static Storage of Sysdig Components
The Installer assumes the usage of a dynamic storage provider (AWS or
GKE). In case these are not used in your environment, add the entries
below to thevalues.yamlto configure static storage.
Based on the size entered in the values.yaml file
(small/medium/large), the Installer assumes a minimum number of
replicas and nodes to be provided. You will enter the names of the nodes
on which you will run the Cassandra, ElasticSearch, mySQL and Postgres
components of Sysdig in the values.yaml, as in the parameters and
example below.
Parameters
storageClassProvisioner:hostPath.
sysdig.cassandra.hostPathNodes: The number of nodes configured
here needs to be at minimum 1 when configured size is small, 3
when configured size is medium and 6 when configured size is
large.
elasticsearch.hostPathNodes: The number of nodes configured here
needs to be at minimum 1 when configured size is small, 3 when
configured size is medium and 6 when configured size is large.
sysdig.mysql.hostPathNodes: When sysdig.mysqlHA is configured to
true, this must be at least 3 nodes. When sysdig.mysqlHA is not
configured, it should be at least 1 node.
sysdig.postgresql.hostPathNodes: This can be ignored if Sysdig
Secure is not licensed or used in this environment. If Secure is
used, then the parameter should be set to 1, regardless of the
size setting
Run Only Sysdig Pods on a Node Using Taints and Tolerations
If you have a large shared Kubernetes cluster and want to dedicate a few
nodes for just the Sysdig backend component installation, you can use
the Kubernetes concept of taints and
tolerations.
Copy that section to your own values.yaml file and edit with
labels and taints you assigned.
Example from the sample file:
# To make the 'tolerations' code sample below functional, assign nodes the taint# dedicated=sysdig:NoSchedule. E.g:# kubectl taint my-awesome-node01 dedicated=sysdig:NoScheduletolerations:- key:"dedicated"operator:"Equal"value:sysdigeffect:"NoSchedule"# To make the Label code sample below functional, assign nodes the label# role=sysdig.# e.g: kubectl label nodes my-awesome-node01 role=sysdignodeaffinityLabel:key:rolevalue:sysdig
Patching
Patching can be used to customize or “tweak” the default behavior of the
Installer to accommodate the unique requirements of a specific
environment. Use patching to modify the parameters that are not exposed
by thevalues.yaml. Refer to the configuration_parameters.md for more
detail about various parameters.
The most common use case for patching is during
upgrades. When generating
the differences between an existing installation and the upgrade, you
may see previously customized configurations that the upgrade would
overwrite, but that you want to preserve.
Patching Process
If you have run generate diff and found a configuration that you
need to tweak (e.g. the installer will delete something you want to
keep, or you need to add something that isn’t there), then follow these
general steps:
Create an overlays directory in the same location as the
values.yaml.
This directory, and the PATCH.yaml you create for it, must be kept.
The installer will use it during future upgrades of Sysdig.
Create a .yaml file to be used for patching. You can name it
whatever you want; we will call it PATCH.yaml for this example.
Patch files must include, at a minimum:
apiVersion
kind
metadata.name
of the object to be patched.
Then you add the specific configuration required for your needs. See
one example below.
You will need this patch definition for every Kubernetes object you
want to patch.
Run generate diff again and check that the outcome will be what
you want.
When satisfied, complete the update by changing the scripts value to
deploy and running the installer (see Installer Upgrade
(2.5.0+).
If you want to add another patch, you can either add a separate
.yaml file or a new YAML document separated by ---.
The recommended practice is to use a single patch per Kubernetes object.
Example
Presume you have the following generated configuration:
All on-premises installations and upgrades are now scheduled with and guided by Sysdig technical account managers and professional services division. See Oversight Services Now Offered for All Installs and Upgrades. For customers, the instructions in this section are for review purposes
only.
The Sysdig platform includes both Sysdig Monitor and Sysdig Secure,
which are licensed separately. All installations include Sysdig Monitor,
while some of the Secure components are installed and configured as
additional steps, as noted.
When installing the Sysdig platform with Kubernetes as the
orchestrator, you install each backend component with separate kubectl
commands.
Installation with the Installer tool is recommended from version 2.5.0 onwards.
To perform a manual install on OpenShift, see Manual Install
(OpenShift). The manual install on Kubernetes 1.9+ is described below.
Prerequisites
Access to a running Kubernetes cluster 1.9+
(Note: if your environment is installed elsewhere, such as your own
data center, contact Sysdig Professional Services to customize the
installation instructions appropriately.)
Two items from your Sysdig purchase-confirmation email:
kubectl installed on your machine and communicating with the
Kubernetes cluster
(Note that your kubectl and Kubernetes versions should match to
avoid errors.)
An External Load Balancer (required for production – see below)
If installing in a cloud-provider environment (such as AWS, GCloud,
or Azure), you will deploy an HAProxy load balancer and point a DNS
record to that load balancer.
If installing in your own data center, then you will need two DNS
records, one for the collector and one for the UI.
A DNS server and control over a DNS name that you can point to
Sysdig
Consider Elasticsearch Default Privileges
By default, the Elasticsearch container will be installed in
privileged (root-access) mode. This mode is only needed so the
container can reconfigure the hosts’ Linux file descriptors if
necessary. See Elasticsearch’s description
here.
If you prefer not to allow Elasticsearch to run with root access to the
host, you will need to:
Set your own file descriptors on all Linux hosts in the Kubernetes
cluster.
If one host were to go down, Kubernetes could choose a different
node for Elasticsearch, so each Linux host must have the file
descriptors set.
Setprivileged:falsein the elasticsearch-statefulset.yaml
file.
See the step under Coonfigure Backend Components, below, for
details.
Configure Storage Class
If you are using EKS or GKE, default storage classes are provided; check
for them (step 1).
In other environments, you may need to create a storage class (step 2).
Finally, enter the storageClassName in the appropriate .yaml files
(step 3).
Verify whether a storage class has been created, by running the
command:
kubectl get storageclass
If no storage class has been defined, create a manifest for one, and
then deploy it.
For example, a manifest could be named
sysdigcloud-storageclass.yaml and contain the following contents
(for a storage class using GP2 volumes in AWS):
Sysdig provides the necessary scripts, images, and .yaml files in a
GitHub repository. The first step is to clone those files and check out
the latest version. (These examples use 1234.)
Create a TCP load balancer (i.e., AWS NLB) that forwards ports 80, 443,
6443 to the Kubernetes worker nodes, with a healthcheck to /healthz on
port 10253.
This can be done in three ways:
Use an existing external load balancer. Sysdig relies heavily on
DNS; you need a DNS record pointing to the load balancer.
Create a yaml with the following content and apply it to the
sysdigcloud namespace. This automatically creates a load balancer in
the cloud provider environment, with an external DNS name.
This is the fully qualified domain name required later in the
config.yaml, api-ingress.yaml and/or
api-ingress-with-secure.yaml.
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE SELECTORhaproxy-ingress-lb-service LoadBalancer 100.66.118.183 sample123.us-east-1.elb.amazonaws.com 80:31688/TCP,443:32324/TCP,6443:30668/TCP 1d run=haproxy-ingress
DNS Entry (For Test Environments without a Load Balancer)
Not for production environments.
Create a DNS entry for your Sysdig install using the fully qualified
domain name that contains all the external IPs as A records. This will
use DNS round-robin to load balance your clients to the Kubernetes
cluster.
Change the super admin name and password, which are the super
admin credentials for the entire system. See
here for details.
Find the settings in config.yaml here:
sysdigcloud.default.user:test@sysdig.com# Required: Sysdig Cloud super admin user password# NOTE: Change upon first loginsysdigcloud.default.user.password:test
Change the mysql.password from change_me to desired
credentials.
mysql.password:change_me# Required: Cassandra endpoint DNS/IP. If Cassandra is deployed as aKubernetes service, this will be the service name.# If using an external database, put the proper address (the address of asingle node will be sufficient)
**Edit the collector endpoint and api-url:**Change the defaults
(sysdigcloud-collector and sysdigcloud-api:443) to point to the
DNS name you have established for Sysdig.
Configure DNS name in api-ingress.yaml (or
api-ingress-with-secure.yaml if using Secure). (Files located in
sysdigcloud/)
Edit: host: <EXTERNAL-DNS-NAME> to suit your DNS name
Define namespace in ingress-clusterrolebinding.yaml. (File
located in
sysdigcloud/ingress_controller/) Edit namespace: sysdigcloud
Step 2 Add Storage Class to Manifests
Using either the existing storage class name from step 1, or the storage
class name defined in the previous step, edit the storageClassName in
the following .yaml files:
Step 6 (Optional) Use CA Certs for External SSL Connection
The Sysdig platform may sometimes open connections over SSL to certain
external services, including:
LDAP over SSL
SAML over SSL
OpenID Connect over SSL
HTTPS Proxies
If the signing authorities for the certificates presented by these
services are not well-known to the Sysdig Platform (e.g., if you
maintain your own Certificate Authority), they are not trusted by
default.
To allow the Sysdig platform to trust these certificates, use the
command below to upload one or more PEM-format CA certificates. You must
ensure you’ve uploaded all certificates in the CA approval chain to the
root CA.
Create the datastore statefulsets for Elasticsearch and Cassandra.
Elasticsearch and Cassandra are automatically set up with
--replica=3 generating full clusters.
After updating the configmap, the Sysdig components must be restarted
for the changed parameters to take effect. This can be done by forcing a
rolling update of the deployments.
A possible way to do so is to change something innocuous, which forces a
rolling update. E.g.:
For Sysdig installations on Kubernetes or OpenShift, version 2.5.0 and
above.
The Sysdig Installer tool is a Docker image containing a collection of
scripts that help automate the on-premises deployment of the Sysdig
platform (Sysdig Monitor and/or Sysdig Secure), for environments using
Kubernetes or OpenShift. Use the Installer to install or upgrade your
Sysdig platform. It is recommended as a replacement for the earlier
Kubernetes manual installation and upgrade procedures.
Installation Overview
To install, you will log in to quay.io, download a values.yaml
file, provide a few basic parameters in it, and launch the Installer. In
a normal installation, the rest is automatically configured and
deployed.
You can perform a quick install if your environment has access to the
internet, or a partial or full airgapped installation, as needed. Each
is described below.
Use hostPath for static storage of Sysdig components
Use Kubernetes node labels and taints to run only Sysdig pods on
selected nodes in a cluster
Prerequisites
The installer must be run from a machine with kubectl/oc configured
with access to the target cluster where the Sysdig platform will be
installed. Note that this cluster may be different than where the Sysdig
agent will be deployed.
Requirements for Installation Machine with Internet Access
Additional Requirements for Airgapped Environments
Edited values.yaml
with
airgap registry details updated
Network and authenticated access to the private registry
Access Requirements
Sysdig license key (Monitor and/or Secure)
Quay pull secret
Storage Requirements
You may use dynamic or static storage on a variety of platforms to store
the Sysdig platform components (stateful sets). Different configuration
parameters and values are used during the install, depending on which
scenario you have.
Use Case 1: Default, undefined (AWS/GKE)
If you will use dynamic storage on AWS or GKE and haven’t configured any
storage class there yet, then the Quick Install streamlines the process
for you.
storageclassProvisioner: Enter aws or gke. The installer will
create the appropriate storage class and then use it for all the
Sysdig platform stateful sets.
storageclassName: Leave empty.
Use Case 2: Dynamic, predefined
It is also possible that you are using dynamic storage but have already
created storage classes there. This dynamic storage could be AWS, GKE,
or any other functioning dynamic storage you use. In this case, you
would enter:
storageclassProvisioner: Leave empty; anything put here would be
ignored.
storageclassName: Provide the name of the pre-configured storage
class you want to use. The installer will use this storage class for
all the Sysdig platform stateful sets.
Use Case 3: Static Storage
In cases where dynamic storage is not available, you can use static
storage for the Sysdig stateful sets. In this case, you would use:
storageclassProvisioner: Enter hostpath, then define the nodes
for the four main Sysdig components: ElasticSearch, Cassandra,
MySQL, and Postgres.storageclassProvisioner
If you have the default use case, enter aws or gke in the
storageClassProvisioner field. Otherwise, refer to Use Case 2
or 3.
sysdig.license: Sysdig license key provided with your Sysdig
purchase confirmation mail
sysdig.dnsname: The domain name the Sysdig APIs will be
served on. Note that the master node may not be used as the DNS
name when using hostNetwork mode.
sysdig.collector.dnsName: (OpenShift installs only) Domain
name the Sysdig collector will be served on. When not configured
it defaults to whatever is configured for sysdig.dnsName. Note
that the master node may not be used as the DNS name when using
hostNetwork mode.
deployment: (OpenShift installs only) Add
deployment: openshift to the root of the values.yaml file.
sysdig.ingressNetworking: The networking construct used to
expose the Sysdig API and collector.Options are:
hostnetwork: sets the hostnetworking in the ingress
daemonset and opens host ports for api and collector. This
does not create a Kubernetes service.
loadbalancer: creates a service of type loadbalancer and
expects that your Kubernetes cluster can provision a load
balancer with your cloud provider.
nodeport: creates a service of type nodeport.The node
ports can be customized with:
sysdig.ingressNetworkingInsecureApiNodePort
sysdig.ingressNetworkingApiNodePort
sysdig.ingressNetworkingCollectorNodePort
When not configured, sysdig.ingressNetworking defaults to
hostnetwork.
If doing an airgapped install , you would also edit the
following values:
- **airgapped\_registry\_name:** The URL of the airgapped
(internal) docker registry. This URL is used for installations
where the Kubernetes cluster can not pull images directly from
Quay
- **airgapped\_repository\_prefix:** This defines custom
repository prefix for airgapped\_registry. Tags and pushes
images as
`airgapped_registry_name/airgapped_repository_prefix/image_name:tag`
- **airgapped\_registry\_password:** The password for the
configured airgapped\_registry\_username. Ignore this parameter
if the registry does not require authentication.
- **airgapped\_registry\_username:** The username for the
configured airgapped\_registry\_name. Ignore this parameter if
the registry does not require authentication.
Run the installer. (This step differs in Airgapped Installation,
below.)
Save the values.yaml file in a secure location; it will be used for
future upgrades.
There will also be a generated directory containing various Kubernetes
configuration yaml files that were applied by the Installer against
your cluster. It is not necessary to keep the generated directory, as
the Installer can regenerate it consistently with the same
values.yaml file.
Airgapped Installation Options
The installer can be used to install in airgapped environments, either
with a multi-homed installation machine that has internet access, or in
an environment with no internet access.
Updating Vulnerability Feed in Airgapped Environments
NOTE: Sysdig Secure users who install in an airgapped environment do
not have internet access to the continuous checks of vulnerability
databases that are used in image scanning. (See also: How Sysdig Image
Scanning
Works.)
As of installer version 3.2.0-9, airgapped environments can also
receive periodic vulnerability database updates.
When you install with the “airgapped_” parameters enabled (see Full
Airgap
Install
instructions), the installer will automatically push the latest
vulnerability database to your environment. Follow the steps below to
reinstall/refresh the vuln db, or use the script and chron job to
schedule automated updates (daily, weekly, etc.).
To automatically update the vulnerability database, you can:
This assumes a private docker registry is used and the installation
machine has network access to pull from quay.io and push images to the
private registry.
The Prerequisites and workflow are the same as in the Quickstart Install
(above) with the following exceptions:
This assumes a private docker registry is used and the installation
machine does not have network access to pull from quay.io, but can push
images to the private registry.
In this situation, a machine with network access (called the “jump
machine”) will pull an image containing a self-extracting tarball which
can be copied to the installation machine.
If you have the default use case, enter aws or gke in the
storageClassProvisioner field. Otherwise, refer to Use Case 2
or 3.
sysdig.license: Sysdig license key provided with your Sysdig
purchase confirmation mail
sysdig.dnsname: The domain name the Sysdig APIs will be
served on. Note that the master node may not be used as the DNS
name when using hostNetwork mode.
sysdig.collector.dnsName: (OpenShift installs only) Domain
name the Sysdig collector will be served on. When not configured
it defaults to whatever is configured for sysdig.dnsName. Note
that the master node may not be used as the DNS name when using
hostNetwork mode.
deployment: (OpenShift installs only) Add
deployment: openshift to the root of the values.yaml file.
sysdig.ingressNetworking: The networking construct used to
expose the Sysdig API and collector.Options are:
hostnetwork: sets the hostnetworking in the ingress
daemonset and opens host ports for api and collector. This
does not create a Kubernetes service.
loadbalancer: creates a service of type loadbalancer and
expects that your Kubernetes cluster can provision a load
balancer with your cloud provider.
nodeport: creates a service of type nodeport.The node
ports can be customized with:
sysdig.ingressNetworkingInsecureApiNodePort
sysdig.ingressNetworkingApiNodePort
sysdig.ingressNetworkingCollectorNodePort
airgapped_registry_name: The URL of the airgapped
(internal) docker registry. This URL is used for installations
where the Kubernetes cluster can not pull images directly from
Quay
airgapped_repository_prefix: This defines custom
repository prefix for airgapped_registry. Tags and pushes
images as
airgapped_registry_name/airgapped_repository_prefix/image_name:tag
airgapped_registry_password: The password for the
configured airgapped_registry_username. Ignore this parameter
if the registry does not require authentication.
airgapped_registry_username: The username for the
configured airgapped_registry_name. Ignore this parameter if
the registry does not require authentication.
Copy the tarball file to the directory where you have your
values.yaml file.
Run the tar file:
bash sysdig_installer.tar.gz
NOTE: The above step extracts images, runs the installer, and pushes
images to the remote repository in a single step. The extract/push
images can be redundant for successive installer runs. Setting
IMAGE_EXTRACT_PUSH=false runs only the installer:
Save the values.yaml file in a secure location; it will be used for
future upgrades.
There will also be a generated directory containing various Kubernetes
configuration yaml files that were applied by the Installer against
your cluster. It is not necessary to keep the generated directory, as
the Installer can regenerate it consistently with the same
values.yaml file.
Output
A successful installation should display output in the terminal such as:
All Pods Ready.....ContinuingCongratulations, your Sysdig installation was successful!You can now login to the UI at "https://awesome-domain.com:443" with:username:"configured-username@awesome-domain.com"password:"awesome-password"
There will also be a generated directory containing various Kubernetes
configuration yaml files which were applied by installer against your
cluster. It is not necessary to keep the generated directory, as the
installer can regenerate consistently with the same values.yaml file.
Additional Installer Resources
To see all the configuration parameters available, as well as their
definitions, values, and examples, see
configuration_parameters.md
on GitHub.
For customers, the instructions in this section are for review purposes only.
As of Sysdig Platform v 2.5.0, a semi-automated install option is
available and is preferred. This section describes how to install the backend components of the
Sysdig platform using an existing OpenShift cluster. It applies to
backend versions 1929 and higher.
Introduction
The Sysdig platform includes both Sysdig Monitor and Sysdig Secure,
which are licensed separately. All installations include Sysdig Monitor,
while some of the Secure components are installed and configured as
additional steps within the overall installation process. When
installing the Sysdig platform on OpenShift manually, you will install
each backend component with separate oc commands.
Prerequisites
Overview
Access to a running OpenShift 3.11+ instance
Two items from your Sysdig purchase-confirmation email:
octools installed on your machine and communicating with the
OpenShift cluster. (Note that your oc and OpenShift versions
should match to avoid errors.)
DNS Preparation
If you want more information on OpenShift’s DNS requirements; see the
OpenShift
documentation.
Option 1: DNS without Wildcard
You need to request two different DNS records from your DNS team:
one for the Sysdig API/UI and another for the Sysdig collector.
These records should point to your infrastructure nodes and are the
two routes that will be exposed, i.e., sysdig.api.example.com and
sysdig.collector.example.com.
Option 2: DNS with Wildcard
With wildcard DNS, you do not have to make an official request from
the DNS team. Your implementation team can pick any two DNS names to
use for the API/UI and Collector. These will be exposed to the
infrastructure nodes once the configuration is completed. (i.e.
sysdig.api.example.com and sysdig.collector.example.com.)
With wildcard SSL, you use the same certificate for both the API and
the collector.
SSL without Wildcard
You need two SSL certs, one for each DNS record.
Consider Elasticsearch Default Privileges
By default, the Elasticsearch container will be installed in
privileged (root-access) mode. This mode is only needed so the
container can reconfigure the hosts’ Linux file descriptors if
necessary. See Elasticsearch’s description
here.
If you prefer not to allow Elasticsearch to run with root access to the
host, you will need to:
Set your own file descriptors on all Linux hosts in the Kubernetes
cluster.
If one host were to go down, Kubernetes could choose a different
node for Elasticsearch, so each Linux host must have the file
descriptors set.
Setprivileged:falsein the elasticsearch-statefulset.yaml
file.
See the step under Coonfigure Backend Components, below, for
details.
The source link has the format:
https://github.com/draios/sysdigcloud-kubernetes/archive/<v1234>.tar.gz. To
unpack it, run the following commands (replacing version number as
appropriate):
Change the super admin name and password, which are the super
admin credentials for the entire system. See
here for details.
Find the settings in config.yaml here:
sysdigcloud.default.user:test@sysdig.com# Required: Sysdig Cloud super admin user password# NOTE: Change upon first loginsysdigcloud.default.user.password:test
**Edit the collector endpoint and API URL:**Change the placeholder
to point to the DNS names you have established for Sysdig.
Remember that you must have defined one name for the collector and
another for the API URL.
Note: Change the collector port to 443.
```yaml
collector.endpoint: <COLLECTOR_DNS_NAME>
collector.port: "443"
api.url: https://<API_DNS_NAME>:443
```
Recommended: edit the file to set the JVM options for Cassandra,
Elasticsearch, and API, worker, and collector as well.
Edit the collector DNS name in the fileopenshift-collector-router.yaml. Use the collector DNS name you
created in the Prerequisites.
The file is located in sysdigcloud/openshift/.
spec:host:<COLLECTOR_DNS_NAME>
Step 3 (Secure-Only): Edit mysql-deployment.yaml
If using Sysdig Secure :
Edit the MySQL deployment to uncomment the MYSQL_EXTRADB_*
environment variables. This forces MySQL to create the necessary
scanning database on startup.
The scanning service will not start unless MySQL creates the scanning database.
Step 4: Deploy Your Quay Pull Secret
A specific Quay pull secret is sent via email with your license key.
Edit the file sysdigcloud/pull-secret.yaml and change the
place holder <PULL_SECRET> with the provided pull secret.
vi sysdigcloud/pull-secret.yaml---apiVersion:v1kind:Secretmetadata:name:sysdigcloud-pull-secretdata:.dockerconfigjson:<PULL_SECRET>type:kubernetes.io/dockerconfigjson
Step 6: (Optional) Use CA Certs for External SSL Connections
The Sysdig platform may sometimes open connections over SSL to certain
external services, including:
LDAP over SSL
SAML over SSL
OpenID Connect over SSL
HTTPS Proxies
If the signing authorities for the certificates presented by these
services are not well-known to the Sysdig Platform (e.g., if you
maintain your own Certificate Authority), they are not trusted by
default.
To allow the Sysdig platform to trust these certificates, use the
command below to upload one or more PEM-format CA certificates. You must
ensure you’ve uploaded all certificates in the CA approval chain to the
root CA.
You need a storage class; step 2 shows how to create one if needed.
Enter the storageClassName in the appropriate .yaml files (see step
3).
Verify whether a storage class has been created, by running the
command:
oc get storageclass
If no storage class has been defined, create a manifest for one, and
then deploy it.
For example, a manifest could be named
sysdigcloud-storageclass.yaml and contain the following contents
(for a storage class using GP2 volumes in AWS):
Using either the existing storage class name from step 1, or the
storage class name defined in step 2, edit the storageClassName in
the following .yaml files:
Create the datastore statefulsets for Elasticsearch and Cassandra.
Elasticsearch and Cassandra are automatically set up with
--replica=3 generating full clusters.
Apply the appropriate ingress yaml. (The API_DNS name was entered in
step 7, in Step 2: Configure Backend
Components
This configures the route to the Sysdig UI.
After updating the configmap, the Sysdig components must be restarted
for the changed parameters to take effect. This can be done by forcing a
rolling update of the deployments.
A possible way to do so is to change something innocuous, which forces a
rolling update. E.g.:
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.
Infrastructure Managers: To install Sysdig on-premises,
administrators choose one of two infrastructure managers:
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.
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.
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.
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:
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.
Continue with “Setting the Replication Management Password” and the rest
of the installation steps in Install Components
(Replicated).
2.5.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.
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.
Log into the designated server instance with SSH.
Run the following commands:
a. To install the Replicated Infrastructure and Docker:
Log In to Replicated Admin Console/ “admin console” and Set SSL Certificate
As prompted, open the Replicated Client at
https://<yourserver>:8800.
Supply the DNS hostname for the Replicated Admin Console.
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.
Click the Choose License button, and upload the Sysdig license
file supplied from Sysdig Sales.
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.
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:
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.
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.
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
Log into Quay:
Locate your Quay pull_secret. Contact Support if you are unable
to locate it.
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:
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.
Run the Agent container with the new additional config. For example:
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.
Click the Open link to navigate to the Sysdig Monitor login panel.
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.
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:
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.
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.
Repeat this procedure on all desired hosts.
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.
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
2.5.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)
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:
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:
When experiencing issues, you can collect troubleshooting data that can
help the support team. The data can be collected by hand, or Sysdig
provides a very simple get_support_bundle.sh script that takes as an
argument the namespace where Sysdig is deployed and will generate a
tarball containing some information (mostly log files). The script is
located in the GitHub repository.
$ ./scripts/get_support_bundle.sh sysdigcloudGetting support logs for sysdigcloud-api-1477528018-4od59Getting support logs for sysdigcloud-api-1477528018-ach89Getting support logs for sysdigcloud-cassandra-2987866586-fgcm8Getting support logs for sysdigcloud-collector-2526360198-e58uyGetting support logs for sysdigcloud-collector-2526360198-v1eggGetting support logs for sysdigcloud-mysql-2388886613-a8a12Getting support logs for sysdigcloud-redis-1701952711-ezg8qGetting support logs for sysdigcloud-worker-1086626503-4cio9Getting support logs for sysdigcloud-worker-1086626503-sdtrcSupport bundle generated:1473897425_sysdig_cloud_support_bundle.tgz
Docker Connectivity Issues (IPv4/IPv6)
Some issues with IPv4 and IPv6 interconnectivity between on-premises
containers and the outside world have been detected.
IP packet forwarding is governed by the ip_forward system parameter.
Packets can only pass between containers if this parameter is 1.
Usually, you will simply leave the Docker server at its default setting
--ip-forward=true and Docker will go set ip_forward to 1 for you
when the server starts up. If you set --ip-forward=false and your
system’s kernel has it enabled, the --ip-forward=false option has no
effect.
File Write Permissions Issues (SELINUX or APP ARMOR)
During the install, you may see errors writing to volumes such as
(/var or /opt) from either the onprem install scripts or Docker. You
should disable SELINUX (CENTOS/RHEL) or Apparmor (UBUNTU/DEBIAN)
during the course of the install so the valid directories can be
created. This can be accomplished by:
Centos (SELINUX)
From the command line, edit the /etc/sysconfig/selinux file. This file
is a symlink to /etc/selinux/config. The configuration file is
self-explanatory. Changing the value of SELINUX or
*SELINUXTYPE*changes the state of SELinux and the name of the policy
to be used the next time the system boots.
[root@host2a ~]# cat /etc/sysconfig/selinux# This file controls the state of SELinux on the system.# SELINUX= can take one of these three values:# enforcing - SELinux security policy is enforced.# permissive - SELinux prints warnings instead of enforcing.# disabled - SELinux is fully disabled.SELINUX=permissive# SELINUXTYPE= type of policy in use. Possible values are:# targeted - Only targeted network daemons are protected.# strict - Full SELinux protection.SELINUXTYPE=targeted# SETLOCALDEFS= Check local definition changesSETLOCALDEFS=0
This section describes how to upgrade an on-premise installation,
depending on whether it was installed using a Kubernetes or a Replicated
orchestrator.
As needed, version-specific upgrade or migration instructions will be
added to this section.
Oversight Services Now Offered for All Installs and Upgrades
As part of our continued focus on our customers, we are now offering
oversight services for all on-premise installs and upgrades. Your
Technical Account Manager (TAM), in conjunction with our support
organization and Professional Services [where applicable], will work
with you to:
Assess your environment to ensure it is configured correctly
Review your infrastructure to validate the appropriate storage
capacities are available
Review and provide recommendations for backing up your Sysdig data
Work with you to ensure our teams are ready to assist you during the
install and upgrade process
Provide the software for the install
Be available during the process to ensure a successful deployment
You can always review the process in the documentation on
GitHub (v. 3.6.0+) or
the standard docs site
(for older versions).
If you are a new customer looking to explore Sysdig, please head over
here to sign up for a trial on
our SaaS Platform. Alternatively, you can contact us
here.
Explore the Upgrade Topics
This section provides roadmaps for upgrading Sysdig Platform components.
Review the topics appropriate to your environment.
Upgrading Sysdig Platform v2.5.0 - 3.2.2 by using the Installer tool. As of version 2.5.0, the Sysdig platform on Kubernetes or OpenShift should be upgraded using the Installer tool.
Upgrading the mandatory components of the Sysdig Platform on a Replicated environment.
Supported Migration Paths
In general, Sysdig tests and supports direct upgrade from five
releases
back to the current version. Release-specific requirements are listed in
the table below.
For Kubernetes Environments
Install Version
Incl. Hotfixes
Supported Upgrade From
Notes
Baseline Documentation
3.6.0 (by request)
3.2.2, 3.5.1
Platform changes: new inline scanner version, interactive session expiration. Sysdig Secure modules added/changed, including Compliance, Event Forwarding, Capture improvements, Image Scan results. Sysdig Monitor improvements in UI.
New/changed modules in both Sysdig Secure and Sysdig Monitor, including: New Getting Started and Overview, new Dashboards, overhauled Secure Events Feed, new navigation bar icons and layout, changed Image scanning navigation and usage, new Secure vulnerability feed and benchmark test,
In Sysdig Secure: Data retention limits for scan results, vulnerabiity comparison in scan results, redesigned Captures page, RBAC capability, activity audit improvement. In Sysdig Monitor and Secure: S3-compatible storage for Capture files.
For customers, the instructions in this section are for review purposes only.
Overview
With version 3.5.0, both installing and upgrading with the installer has
been simplified from previous versions. Upgrade differs from Install in
that you run an installer diff to discover the differences between the
old and new versions and then installer deploy for the new version.
Some guidance from Sysdig Support may be warranted in highly customized
installations.
Upgrade Steps
Upgrading is performed just like a fresh install, with the addition of
the generate diff step. Refer to the appropriate workflow, depending
on your environment:
Version 3.5.0 upgrade includes an automatic Postgres version upgrade.
Depending on the size of your database, that can take some time.
The data migration takes approximately 1 min per 1 GiB of data. The
speed of data migration ultimately depends on the underlying storage
media.
To complete the Postgres upgrade, you must also ensure there is
sufficient disk space in the volume when using a local-disk storage
provisioner in Kubernetes. For example, if your current Postgres size is
100 GiB, ensure there is at least another 100 GiB space free in the
volume. This is required temporarily for copying the data during the
upgrade.
3.5.0 - 3.5.1 Elasticsearch Upgrade
Upgrading from version 3.5.0 to 3.5.1 also upgrades Elasticsearch. Due
to the Elasticsearch update strategy of ondelete, the pods will only
be upgraded when they are restarted:
For customers, the instructions in this section are for review purposes only.
The Installer tool can be used to upgrade a Sysdig implementation. Just
as in an installation, you must meet the prerequisites, download the
values.yaml, edit the values as indicated, and run the installer. The
main difference is that you run it twice: once to discover the
differences between the old and new versions and the second time to
deploy the new version.
As this is a new feature, some guidance from Sysdig Professional
Services may be warranted in highly customized installations.
This setting will generate the differences between the installed
environment and the upgrade version. The changes will be
displayed in your terminal.
size: Specifies the size of the cluster. Size defines CPU,
Memory, Disk, and Replicas. Valid options are: small, medium and
large
quaypullsecret: quay.io provided with your Sysdig purchase
confirmation mail
storageClassProvisioner: The name of the storage class
provisioner to use when creating the configured
storageClassName parameter. When installing, if you use AWS or
GKE as your storage provisioner for Kubernetes, enter aws or
gke in the storageClassProvisioner field. If you do not use
one of those two dynamic storage provisioners, enter: hostPath
and then refer to the Advanced examples for how to configure
static storage provisioning using this option.
sysdig.license: Sysdig license key provided with your Sysdig
purchase confirmation mail
sysdig.anchoreLicensePath: The path relative to the
values.yaml where the Anchore enterprise license yaml is
located. (For Sysdig Secure users only.)
sysdig.dnsname: The domain name the Sysdig APIs will be
served on. Note that the master node may not be used as the DNS
name when using hostNetwork mode.
sysdig.collector.dnsName: (OpenShift installs only) Domain
name the Sysdig collector will be served on. When not configured
it defaults to whatever is configured for sysdig.dnsName. Note
that the master node may not be used as the DNS name when using
hostNetwork mode.
deployment: (OpenShift installs only) Add
deployment: openshift to the root of the values.yaml file.
sysdig.ingressNetworking: The networking construct used to
expose the Sysdig API and collector.Options are:
hostnetwork: sets the hostnetworking in the ingress
daemonset and opens host ports for api and collector. This
does not create a Kubernetes service.
loadbalancer: creates a service of type loadbalancer and
expects that your Kubernetes cluster can provision a load
balancer with your cloud provider.
nodeport: creates a service of type nodeport.The node
ports can be customized with:
sysdig.ingressNetworkingInsecureApiNodePort
sysdig.ingressNetworkingApiNodePort
sysdig.ingressNetworkingCollectorNodePort
If doing an airgapped install , you would also edit the
following values:
- **airgapped\_registry\_name:** The URL of the airgapped
(internal) docker registry. This URL is used for installations
where the Kubernetes cluster can not pull images directly from
Quay
- **airgapped\_registry\_password:** The password for the
configured airgapped\_registry\_username. Ignore this parameter
if the registry does not require authentication.
- **airgapped\_registry\_username:** The username for the
configured airgapped\_registry\_name. Ignore this parameter if
the registry does not require authentication.
Run the installer.
For environments with access to the internet:
docker run -e HOST_USER=$(id -u) -e KUBECONFIG=/.kube/config-v ~/.kube:/.kube:Z -v $(pwd):/manifests:Zquay.io/sysdig/installer:<version>
For customers, the instructions in this section are for review purposes only.
Sysdig platform on-premise releases are listed
here. Each
release has a version number and specific release notes.
This release has the following significant changes:
Added NATS service to deliver events to the Sysdig backend
Added services for the beta Policy Advisor, which permits a user to
auto-generate Pod Security Policies and perform dry tests or
“simulations” of them before committing them to an environment.
Added services for activity audit, which allows users to view
different data sources in-depth for monitoring, troubleshooting,
diagnostics, or to meet regulatory controls
Some Anchore reporting components are not needed anymore and have
been removed.
Download the New Version
Download the new version from Sysdig’s GitHub and unzip it.
wget https://github.com/draios/sysdigcloud-kubernetes/archive/<version_number>.tar.gz && tar xvf <version_number>.tar.gz
Edit New Files to Match Your Customized Files
It is important to use the latest YAML files for a successful upgrade.
Edit the following files within the sysdigcloud directory to match any
customizations you may have made in your existing production system.
Please do not edit the image: property.
Sysdig Component Files
Ensure that any passwords or user names are transferred from your
existing config.yaml to the new one. Suggested areas to review are
listed below.
config.yaml:
The following variables are always customized in Sysdig
installations:
Check deployment YAML files for CPU/memory settings.
Update the spec.replicas definition in the following files:
sysdigcloud/api-deployment.yaml
sysdigcloud/collector-deployment.yaml
sysdigcloud/worker-deployment.yaml
If running Sysdig Secure:
sysdigcloud/anchore-core-config.yaml
sysdigcloud/anchore-worker-config.yaml
sysdigcloud/anchore-core-deployment.yaml
sysdigcloud/anchore-worker-deployment.yaml
sysdigcloud/scanning-api-deployment.yaml
sysdigcloud/scanning-alertmgr-deployment.yaml
Postgres File (Sysdig Secure Only)
postgres-statefulset.yaml : Edit the storage class name in this
file.
The file is located in
datastores/as_kubernetes_pods/manifests/postgres/postgres-statefulsets.yaml
Storage class name appears as
spec.volumeClaimTemplates[].spec.storageClassName
Elasticsearch and Cassandra Files
elasticsearch-statefulset.yaml: For example, your environment may
have customized the values for the number of replicas, resource
constraints, amount of storage, and the storage class name:
spec.replicas and spec.template.spec.containers[elasticsearch].env[ELASTICSEARCH_GOSSIP_NODES_NUM].valuespec.template.spec.containers[].resourcesspec.volumeClaimTemplates[].spec.resources.requests.storagespec.volumeClaimTemplates[].spec.storageClassName
cassandra-statefulset.yaml: As with Elasticsearch, your
environment may have customized the values for the number of
replicas, resource constraints, amount of storage, and the storage
class name:
For customers, the instructions in this section are for review purposes only.
Sysdig platform on-premise releases are listed
here. Each
release has a version number and specific release notes.
This release has the following significant component change:
The Report service is now available for Sysdig Secure. Installing it
requires first applying an Anchore license and then applying the
appropriate report yamls, as listed below.
Download the New Version
Download the new version from Sysdig’s GitHub and unzip it.
Note that as of this release, versioning standards have changed from a
single build number (e.g. v1929) to semantic versioning (e.g. 2.3.0)
wget https://github.com/draios/sysdigcloud-kubernetes/archive/<version_number>.tar.gz && tar xvf <version_number>.tar.gz
Edit New Files to Match Your Customized Files
It is important to use the latest YAML files for a successful upgrade.
Edit the following files within the sysdigcloud directory to match any
customizations you may have made in your existing production system.
Sysdig Cloud Files
Customization involves copying the existing settings from your
environment and modifying the files listed in this section.
Update the following files with customizations from your existing
environment:
sysdigcloud/config.yaml: Pull configurations from your
sysdigcloud-config configmap to the downloaded
sysdigcloud/config.yaml.
The following variables are mandatory for Sysdig installations:
api.urlcollector.endpointsysdigcloud.license
The following variables are optional but commonly modified for
Sysdig installations:
If you have modified the previous config.yaml, copy the modified
options such as the external endpoints. You must also check
deployment YAML files for CPU/memory settings.
Copy configurations from your existing deployment and update the
spec.replicas definition in the following files:
Update the following file with customizations from your existing
environment:
Please do not edit the image: property.
Modify the storage class name,
spec.volumeClaimTemplates[].spec.storageClassName in the
datastores/as_kubernetes_pods/manifests/postgres/postgres-statefulset.yaml
file.
Elasticsearch and Cassandra Files
In version 2.3.0, Elasticsearch and Cassandra yaml configurations have
been updated. Update the new files with customizations from your
existing environment.
Please do not edit the image: property.
elasticsearch-statefulset.yaml - For example, your environment may
have customized the values for the number of replicas, resource
constraints, amount of storage, and the storage class name:
spec.replicas and spec.template.spec.containers[elasticsearch].env[ELASTICSEARCH_GOSSIP_NODES_NUM].valuespec.template.spec.containers[].resourcesspec.volumeClaimTemplates[].spec.resources.requests.storagespec.volumeClaimTemplates[].spec.storageClassName
cassandra-statefulset.yaml - As with Elasticsearch, your
environment may have customized the values for the number of
replicas, resource constraints, amount of storage, and the storage
class name:
For versions 2.4.1 and higher: To use the Reports functionality in
Sysdig Secure, it is necessary to enter a license key in the
anchore-license.yaml. If you are upgrading or installing and do not
have an anchore license please contact support. This license is used for
additional 3rd party vulnerability feed entitlements.
Edit the license YAML
file: sysdigcloud/anchore-enterprise-license.yaml. Replace <LICENSE> with
the key received from Sysdig.
---apiVersion:v1kind:Secretmetadata:name:anchore-enterprise-licensedata:# <LICENSE> is derived from `cat anchore-license.yaml | base64`anchore-license.yaml:<LICENSE>type:Opaque
For customers, the instructions in this section are for review purposes only.
Sysdig platform on-premise releases are listed
here. Each
release has a version number and specific Release
Notes.
This release has the following significant component changes:
Includes the option of securing Elasticsearch and/or Cassandra with
username/password authentication and TLS-encrypted data in transit.
This prevents both unauthorized access to the clusters and network
eavesdropping. The upgrade instructions below incorporate this new
capability when using the Sysdig-provided Cassandra and
Elasticsearch components.
Updates of the Postgres database and Anchore engine (if you are
running Sysdig Secure).
The following parameter has been renamed in config.yaml:
elasticsearch.url to elasticsearch.hostname
The value of elasticsearch.hostname does not include the protocol
(e.g.http://); just use the hostname itself. For example, if you had
elasticsearch.url: ``http://sysdigcloud-elasticsearch, it would
now be elasticsearch.hostname: sysdigcloud-elasticsearch.
Download the New Version
Download the new version from Sysdig’s GitHub and unzip it.
Note that as of this release, versioning standards have changed from a
single build number (e.g. v1929) to semantic versioning (e.g. 2.3.0)
wget https://github.com/draios/sysdigcloud-kubernetes/archive/<version_number>.tar.gz && tar xvf <version_number>.tar.gz
Edit New Files to Match Your Customized Files
It is important to use the latest YAML files for a successful upgrade.
Edit the following files within the sysdigcloud directory to match any
customizations you may have made in your existing production system.
Sysdig Cloud Files
Customization involves copying the existing settings from your
environment and modifying the files listed in this section.
Update the following files with customizations from your existing
environment:
sysdigcloud/config.yaml: Pull configurations from your
sysdigcloud-config configmap to the downloaded
sysdigcloud/config.yaml.
The following variables are mandatory for Sysdig installations:
api.urlcollector.endpointsysdigcloud.license
The following variables are optional but commonly modified for
Sysdig installations:
If you have modified the previous config.yaml, copy the modified
options such as the external endpoints. You must also check
deployment YAML files for CPU/memory settings.
Copy configurations from your existing deployment and update the
spec.replicas definition in the following files:
Update the following file with customizations from your existing
environment:
Please do not edit the image: property.
Modify the storage class name,
spec.volumeClaimTemplates[].spec.storageClassName in the
datastores/as_kubernetes_pods/manifests/postgres/postgres-statefulset.yaml
file.
Elasticsearch and Cassandra Files
In version 2.3.0, Elasticsearch and Cassandra yaml configurations have
been updated. Update the new files with customizations from your
existing environment.
Please do not edit the image: property.
elasticsearch-statefulset.yaml - For example, your environment may
have customized the values for the number of replicas, resource
constraints, amount of storage, and the storage class name:
spec.replicas and spec.template.spec.containers[elasticsearch].env[ELASTICSEARCH_GOSSIP_NODES_NUM].valuespec.template.spec.containers[].resourcesspec.volumeClaimTemplates[].spec.resources.requests.storagespec.volumeClaimTemplates[].spec.storageClassName
cassandra-statefulset.yaml - As with Elasticsearch, your
environment may have customized the values for the number of
replicas, resource constraints, amount of storage, and the storage
class name:
Run the kubectl commands to apply the relevant files to your cluster.
Note: if you run into an error replacing the statefulsets, you may need
to delete the existing one before applying the new configuration. See
the Statefulset Deletion and Creation section below.
The replace command above only replaces the Kubernetes configuration,
but not the running pods themselves. For the changes to take effect,
perform the following steps:
For Elasticsearch, run:
kubectl -n $NAMESPACE delete pod -l role=elasticsearchkubectl -n $NAMESPACE delete pod -l role=cassandra# If running Sysdig Securekubectl -n $NAMESPACE delete pod -l role=postgresql
Check that all the new pods come up Ready by running the commands
below separately:
kubectl -n $NAMESPACE get pod -l role=elasticsearchkubectl -n $NAMESPACE get pod -l role=cassandra# If running Sysdig Securekubectl -n $NAMESPACE get pod -l role=postgresql
This may take a few minutes.
3.6 - Manual Upgrade (v2435)
As of August 2020, Sysdig has changed its upgrade procedure.
Run the kubctl commands to apply the relevant files to the
environment.
This upgrade updates dashboards from v1 to v2. The process requires
20-30 minutes on large systems, and the environment remains live
throughout the rolling upgrade.
DO NOT create or delete dashboards during the upgrade.
The Replicated infrastructure installs its own container based agents
that deploy and manage the various Sysdig back-end components. To
confirm the currently running version of the Replicated agent, perform
replicated --version at the command line on each host. [Reference
Replicated.com]
Upgrade Replicated Client
Log in to the Replicated Management Console and stop the Sysdig
application (Sysdig Monitor and Sysdig Secure, if applicable) before
upgrading the Replicated client.
Run the following command on the management host to upgrade the
replicated infrastructure:
Pre-Version 860: Install upgrades sequentially, one version at a
time.
Version 860 - 1091: You can directly install the version you
want.*
Version 1091 - Sept 2018 release: All users must upgrade from
1091 - Sept 2018 and run the Unified Events migration tool.
Version 2266: See Note, below.
*Sequential installs (even when not strictly required) ensure
consistent database migrations and allow for easier troubleshooting,
should problems occur. Sysdig recommends staying fairly up-to-date on
the release cycle to avoid “stacking up” upgrades.
Log in to the Replicated Management Console > Dashboards.
Click View Update.
The release history is listed, and “New” for any new releases.
Click Install for the desired release.
Upgrades to version 2304
After upgrading to version 2304, you must add a node for emailrenderer
and nginxfrontend to the replicated cluster, and then run a command on
the node.
Private and Public IP Addresses: Provide the IPs where the
containers will run.
Select emailrenderer and nginxfrontend.
Run the curl command as noted in the image above, including the
optional parameters as needed for your environment.
Airgapped Installation
Upgrade Replicated Components
Check Current Version
The Replicated infrastructure installs its own container based agents
that deploy and manage the various Sysdig back-end components. To
confirm the currently running version of the Replicated agent, perform
replicated --version at the command line on each host. See also
Replicated.com.
Upgrade Replicated Client
Download the latest Replicated agent installation package:
Download the new Sysdig application .airgap installer, using the
link and password supplied for the initial installation.
Copy the .airgap file to the update directory on the management
host.
To check or configure the update path, log in to the Replicated
Management Console and click Console Settings > Airgapped Settings
section under the gear icon.
In the Replicated Management Console, select the Dashboard tab and
click Check Now.
Click Install for the desired version.
4 - Find the Super Admin Credentials and API Token
Sysdig on-premises installations contain several configuration options
only available to the initial admin user, or “super” admin user. This
section outlines the steps for locating the super admin user (if you do
not know who it is) and using the super user login token.
The Sysdig Monitor web interface does not currently provide a way to
identify the super user. If you are trying to use the API to make a
configuration change and it fails due to insufficient privileges, you
can use the API to locate the super user.
Find Super Admin Credentials
Two approaches:
1. Access the API endpoint to list users directly via curl and parse
the JSON output to locate the user with “ROLE_ADMIN” listed in the
“roles” section.
As with any user, you can then obtain the API token by logging in as the
“super” admin to the Sysdig UI.
When using the Sysdig API with custom scripts or applications, an API
security token (specific to each team) must be supplied.
Log in to Sysdig Monitor or Sysdig Secure and select Settings.
Select User Profile.The Sysdig Monitor or Sysdig Secure API token
is displayed (depending on which interface and team you logged in
to).
You can Copy the token for use, or click the Reset Token button
to generate a new one.
When reset, the previous token issued will immediately become
invalid and you will need to make appropriate changes to your
programs or scripts.
5 - Configure Interactive Session Expiration
(For On-Premises installations): When you want inactive sessions to
deactivate after a time-out period, you need to set four interlinked
configuration parameters with the installer. Two of these parameters
handle the session expiration in the backend and two of them control the
frontend tracker that handles the session expiration when the user’s
browser is idle. To achieve session expiration for a specific period of
time (for example, 30 minutes), these parameters should be aligned to
the same value.
On-premises environments may require a license upgrade to renew, extend
an expiration date, enable new features, add a service (Sysdig Secure),
or change the number of licensed agents.
For Kubernetes On-Prem Installations
As described in the Kubernetes
installation instructions,
the license file is simply entered as one of many configuration user
settings in the ConfigMap
(config.yaml)
(manual install) or values.yaml (installer-based).
To apply the new license, update the yaml file with the new license
and then restart all Sysdig API, Worker, and Collector pods.
Note If you are using Sysdig backend version 5.0.x that syncs the vulnerability feeds database from the internet, restart the following pods: anchore-api, anchore-catalog, anchore-core, and anchore-policy-engine
If you are running an airgapped environment, you must download the
license file to a local directory, then follow the steps below.
Log in to the Replicated Management Console and choose Console
Settings from the gear icon drop-down menu.
Review the current airgapped settings and note the pathname to the
license file.
If you followed the Airgapped
Installation
instructions, your current .rli license file will be in
the/var/tmp/sysdig directory as shown below.
(The name of your .rli file will vary.)
From the Linux shell, cd to the directory shown as the Update
Path and replace your prior RLI license file with the new one,
saving the prior one to a backup filename.
NOTE: the new license file may have a different name than the
prior one, and may have a non-RLI extension if it was sent to you as
an email attachment (to avoid being removed by firewalls).
The steps below are an example of renaming the license as necessary
for the environment shown above (your filenames will vary).
Continue in the Replicated Management Console to sync the license
and restart the Sysdig application, as described in the
non-airgapped instructions below.
Upgrade a Non-Airgapped License
If your environment can access the Internet, upgrading the license is a
simple sync and restart.
Log in to the Replicated Management Console.
Select View License from the Gear drop-down menu.
Click Sync License.
For license terms to take effect, restart the Sysdig application
from the Replicated Management Console.
Navigate to the Dashboard on the pull-down menu and click
theStop Nowbutton, followed by theStart Nowbutton.
7 - Authentication and Authorization (On-Prem Options)
This section is for the Sysdig On-Premises software platform only. If
you are using SaaS (cloud-based) Sysdig applications, see
Authentication and Authorization
(SaaS) instead.
Sysdig Monitor and Sysdig Secure are designed to work with several user
authentication/authorization methods:
Type
Enabled by Default
Integration Steps Required
User email/password
Yes
No
Google OAuth
No
Yes
SAML
No
Yes
OpenID Connect
No
Yes
LDAP
No
Yes
A sample user’s view:
The pages in this section describe the integration and enablement steps
required for SAML or OpenID Connect, and the Identity Provider (IdP)
services
that support these protocols, such as Okta, OneLogin, Keycloak.
In the SaaS environment,
Googlelogin can be enabled
with a simple drop-down selection; the integration has already been
performed.
To enable a third-party authentication method for both Sysdig Monitor
and Sysdig Secure, you must configure the SSO settings separately for
each.
Workflow
With the new Authorization UI, the basic process of enabling a Single
Sign-On (SSO) option is:
Determine which SSO option (GoogleOAuth, SAML, OpenID, LDAP) your
enterprise uses, and which IdP service (Okta, OneLogin, etc.) is
used if any.
Configure any associated IdP settings on the IdP side.
Enter the required connection settings for the chosen SSO on the
appropriate Authentication tab in Sysdig Settings.
You can also configure the settings using a script, if preferred.
Select the SSO option from the Enabled Single Sign-On drop-down
and click Save Authentication.
If enabling for both Sysdig Monitor and Sysdig Secure, perform the
necessary steps on the second application.
View of the Authentication page for Google OAuth in the on-prem
environment.
7.1 - Google OAuth (On-Prem)
These instructions are specific to On-Premises
Deployments of the Sysdig
platform. If you are using the cloud-based (SaaS) Sysdig platform, refer
to Google OAuth (SaaS)
instead.
Google supports OAuth 2.0, which allows users to log in to third-party
applications such as Sysdig using Google credentials. By default, the
created user will not have Admin rights within the Sysdig application,
though these rights can be subsequently assigned.
Prerequisites
The Sysdig platform on-premises installation must have a DNS name
associated with it. Google does not support applications that do not
have an associated DNS name.
For Kubernetes-based installations, ensure the api.url ConfigMap
element
contains your hostname (older installations), or use the sysdig.dnsname
(newer Installer-based).
For the examples that follow, DNS_NAME refers to this hostname you
configured in your platform settings.
In Google Console: Obtain OAuth Client Credentials
Select Credentials from the left-hand navigation, and choose the
OAuth consent screen from the navigation bar.
When prompted, select Internal or External User Type and click
Create.
Choosing Internal will limit the users to those with accounts
belonging to the same domain as the email used to create the
project, e.g. mycompany.com. Note that if some of your users have
a different domain, e.g. mycompany.uk, you will want to choose the
External user type.
On the subsequent Oauth Consent screen, enter the required Email
address and Product name, as well as other additional optional
information, then click Save.
From the Credentials tab, click the Create Credentials drop-down
and select OAuth client ID.
When prompted for Application type, select Web application,
then enter the following parameters:
Name: Use a meaningful name, such as “Sysdig”.
Authorized Javascript Origins: Enter
https://DNS_NAME:API_PORT
Authorized Redirect URLs: Enter one or more of the following
values:
If configuring Sysdig Monitor, enter:
https://DNS_NAME:API_PORT/api/oauth/google/auth
If configuring Sysdig Secure, enter:
https://DNS_NAME:API_PORT/api/oauth/google/secureAuth
Click Create.
A success message with client ID and client secret will be
displayed. Copy these to a safe place, as you will need them in the
next step.
Configure Settings in Sysdig Platform
There are three options for configuring OAuth settings on the Sysdig
side: a UI page, scripts, or entries in your Replicated or Kubernetes
orchestrator.
Option 1 UI-Based: Configure Google OAuth in Settings
To enable baseline Google Oauth functionality:
Enter Google OAuth Basic Settings
Log in to Sysdig Monitor or Sysdig Secure as “super”
Admin and select
Settings.
Select Authentication.
Select the Google OAuth tab.
Enter the relevant parameters and click Save.
Application ID: the Client ID you were sent.
Application Secret: the Client Secret you were sent
URL Redirect:
If configuring Sysdig Monitor, enter:
https://DNS_NAME:API_PORT/api/oauth/google/auth
If configuring Sysdig Secure, enter:
https://DNS_NAME:API_PORT/api/oauth/google/secureAuthAllowed Domains: Comma-separated list of domains permitted to
log in. For example, mycompany.com,
myxompanyalias.com.
Select Google OAuth for SSO
Select Google Oauth from the Enabled Single Sign-On
dropdown
Click Save Authentication.
Repeat for Sysdig Monitor or Sysdig Secure, if you want to enable on
both applications.
Option 2 Script-Based: Configure OAuth Using Scripts
The configuration of the Google OAuth feature can be viewed, updated,
and deleted by the “super”
Admin. A
google_oauth_config.sh helper script is available in the
SSO
folder at sysdig-cloud-scripts repository to assist in completing
this configuration. Invoking the script with no options will display
help text.
# ./google_oauth_config.sh -hUsage:./google_oauth_config.sh [OPTIONS]Affect Google Oauth login settings for your Sysdig software platform installation
To use the helper script, modify env.sh to set the required values
for API_TOKEN of the “super” Admin user and the URL for
accessing the Sysdig platform API (which will be the same URL that your
users access for the Sysdig Monitor application).
Depending if the API_TOKEN has been obtained from the Sysdig Monitor or
Sysdig Secure application UI, the settings will be applied to the
consequent product.
Initially no Google Oauth settings are set. A initial run of the script
would confirm that:
# ./google_oauth_config.shNogoogle-oauth settings are setRun for further info:./google_oauth_config.sh -h
Add the -s option to set the Google Oauth configuration for a
particular Sysdig application. When setting the config, you’ll use
additional options to provide the config details you saved in the
earlier Google Oauth step.
Config Detail
Option
Client ID
-i
Client Secret
-e
Allowed Domains
-a
Redirect URL
-r
If the configuration is successfully posted to the Sysdig platform, the
new configuration will be echoed back.
Depending if the API_TOKEN has been obtained from the Sysdig Monitor or
Sysdig Secure application UI, the settings will be applied to the
relevant product.
Once you’ve completed this configuration, clicking the Google Login
button at the login screen of the appropriate Sysdig application(s)
should redirect to Google Oauth login page.
If you wish to delete your Google Oauth configuration, invoke the
-d option. If successful, the disabled configuration will be
printed.
Option 3 Orchestrator-Based: Enter Settings Using Orchestrator
Replicated
If you used the Replicated
infrastructure manager to install the Sysdig platform:
Log in to the Replicated Management Console, click to the Settings
tab, then check the box to expand theAdvanced Settings.
Enter the Google OAuth client ID and Google OAuth client Secret
in the appropriate fields.
(Optional) In a comma-separated list, enter the
OAuth-allowed email domains that should be permitted to
authenticate. If set, only Google users whose email addresses are in
these domains will be able to login to your Sysdig installation. If
this setting is left blank, any user that successfully authenticates
via Google will be permitted to login to your Sysdig installation.
Click Save.The Sysdig platform will then restart to enable the
settings.
Kubernetes
Enter the OAuth allowed domains, Client ID, and Client Secret
into the appropriate elements of the Kubernetes
ConfigMap.
Use appropriate Kubernetes methods to push the updated settings and
restart the backend containers to make the changes take effect.
# Optional: OAuth allowed domains (comma separated list of domains)sysdigcloud.oauth.allowed.domains.list:""# Optional: Sysdig Cloud Google OAuth Client IDsysdigcloud.google.oauth.client.id:""# Optional: Sysdig Cloud Google OAuth Client Secretsysdigcloud.google.oauth.client.secret:""
User Experience
Note the following requirements for successful Google OAuth login:
The user must have already logged in successfully at least once to
your environment (such as via email-based Invitation and having set
an initial password)
The user’s login username in the Sysdig platform must precisely
match the user’s Google email address (that is, it cannot be a
shortened/altered Google email alias)
For such a user to log in via Google OAuth, click the
Log in with Google button.
If the user’s browser has not already successfully authenticated via
Google and/or has multiple Google profiles known by their browser, they
will be presented a Google page to select a profile and enter a password
(if necessary) before being redirected back to your Sysdig environment.
These instructions are specific to On-Premises
Deployments of the Sysdig
platform. If you are using the cloud-based (SaaS) Sysdig platform, refer
to SAML (SaaS) instead.
The Sysdig platform ordinarily maintains its own user database to hold a
username and password hash. SAML instead allows for redirection to your
organization’s IdP to validate username/password and other policies
necessary to grant access to Sysdig application(s). Upon successful
authentication via SAML, a corresponding user record in the Sysdig
platform’s user database is automatically created, though the password
that was sent to the IdP is never seen nor stored by the Sysdig
platform.
This section describes how to integrate and enable SAML with both Sysdig
Monitor and Sysdig Secure.
For specific IdP integration information, refer to:
If you intend to configure IDP-initiated login flow, have your Sysdig customer number on hand. It will be referenced in later configuration steps as CUSTOMER_ID_NUMBER. Normally 1.
4 a. Log in to Sysdig Monitor (as "super" admin) and enter the necessary configuration information in the UI. Enable SAML as your SSO.
4b. Log in to Sysdig Secure (as "super" admin) and repeat the above.
Administrator Steps
Configure IdP
Select the appropriate IdP from the list below, and follow the
instructions:
At this time, the Authorization UI is available only for Sysdig Monitor.
To enable baseline SAML functionality:
Enter SAML Connection Settings
Log in to Sysdig Monitor or Sysdig Secure as administrator and
select Settings.
Select Authentication.
Select the SAML tab.
Enter the relevant parameters (see table below) and click Save.
It is strongly recommended that "Signed Assertion" and "Validate Signature" are enabled to ensure that the SAML SSO process is as secure as possible.
Connection Setting
Options
Description
Sample Entry
Metadata
URL
The URL provided at the end of the IdP configuration steps.
XML
An option that can be used for an IdP that doesn’t support extracting metadata XML via URL.
Signed Assertion
off/on
Should Sysdig check for assertions signed in responses (to assist in validating correct IdP).
ON
Email Parameter
email
Name of parameter in the SAML response for user email ID. Sysdig uses this to extract the user’s email from the response.
email
Validate Signature
off/on
Sysdig backend should verify that the response is signed.
ON
Verify Destination
off/on
Flag to control whether Sysdig should check the “destination” field in the SAMLResponse. Recommend ON, as a security measure. May be OFF in special cases, such as a proxy in front of the Sysdig back end.
ON
Select SAML for SSO
Select SAML from the Enabled Single Sign-On dropdown
Click Save Authentication.
Repeat entire enablement process for Sysdig Monitor or Sysdig
Secure, if you want to enable on both applications.
Script-Based: Configure SAML Using Scripts
The configuration of the SAML feature can be viewed, updated, and
deleted by the “super”
Admin. A saml_config.sh
helper script is available in the
SSO
folder at sysdig-cloud-scripts repository to assist in completing
this configuration. Invoking the script with no options will display
help text.
# ./saml_config.shMust specify the Sysdig App whose SAML configuration will be viewed/setUsage:./saml_config.sh [OPTIONS]Affect SAML login settings for your Sysdig software platform installationIf no OPTIONS are specified, only the help output is displayed.
To use the helper script, modify env.sh to set the required values
for API_TOKEN of the “super” Admin user and the URL for
accessing the Sysdig platform API (which will be the same URL that your
users access for the Sysdig Monitor application).
Depending if the API_TOKEN has been obtained from the Sysdig Monitor or
Sysdig Secure application UI, the settings will be applied to the
relevant product.
Initially no SAML settings are set. A initial run of the script would
confirm that:
# ./saml_config.shNosaml settings are setRun for further info:./saml_config.sh -h
Add the -s option to set the SAML configuration for a particular
Sysdig application. When setting the config, you’ll also include the
metadata URL you saved in the earlier IDP configuration step (-m
option) and specify the name of a supported IDP configuration (-i
option), which will tailor other details of your SAML configuration to
the specifics of that IDP. If the configuration is successfully posted
to the Sysdig platform, the new configuration will be echoed back.
An example of creating the two separate SAML configurations for both
Monitor and Secure, each using Okta IDP settings:
If you are using an IDP other than those available with the -i
option, contact Sysdig Support for assistance with determining the
correct settings.
Once you’ve completed this configuration, clicking the SAML button at
the login screen of the appropriate Sysdig application(s) should
redirect to your IDP for authentication.
If you wish to delete your SAML configuration, invoke the -d
option. If successful, the disabled configuration will be printed.
SLO is a feature in federated authentication where Sysdig users can sign
out of both their Sysdig session (Service Provider) and associated IdP
(Identity Provider) simultaneously. SLO allows you to terminate all
sessions established via SAML SSO by initiating a single logout process.
Closing all user sessions prevents unauthorized users from gaining
access to Sysdig resources.
SLO Process
When a user initiates a logout, Sysdig sends a digitally-signed logout
request to the IdP. The IdP validates the request and terminates the
current login session, then redirects the user back to the Sysdig login
page.
Caveats
SLO is currently supported only in US-West and EU-Central regions.
Sysdig does not support HTTP Post binding for single logout, and
therefore, SLO with Okta is not functional at this point.
Configure IdP
Configure logout URLs:
Monitor: <base_URL>/api/saml/slo/logout
Secure: <base_URL>/api/saml/slo/secureLogout
Choose HTTP Redirect as the binding method.
This option is an alternative to the HTTP POST method, which Sysdig
does not support currently.
If your IdP mandates, upload the public key for Sysdig.
Contact Sysdig Support to retrieve the public key associated with
your deployment.
Certain IDPs, such as Azure, don’t require uploading the public key.
Configure Sysdig
Log in to Sysdig Monitor or Sysdig Secure as an administrator and
select Settings.
For on-prem deployments, log in as the super admin.
Navigate to Settings > Authentication, and
select SAML under Connection Settings.
Enter the SAML configuration.
Ensure that Enable SAML single logout is toggled on.
Click Save.
Ensure that you select SAML from the Enable Single Sign
On drop-down.
Optional: Auto-creation of user records
When a user successfully authenticates via SAML, if a user record does
not yet exist in the Sysdig platform database for their email address,
one will be created at that time (default behavior). Some environments
may not like this approach and may instead only want to permit logins
for users whose records already exist (such as may have been already
created via email invite
or creation via the
API).
To disable the auto-creation of user records after SAML authentication,
add the -n option to your command line when applying your
settings. This will set createUserOnLogin to false .
You can configure an IdP-initiated login flow when configuring your
IdP. The users then select the Sysdig application from your IDP’s
app directory and do not browse directly to a Sysdig application URL
at all.
Users that complete their first successful SAML login to Sysdig Secure
may receive the error message “User doesn’t have permission to login in
Sysdig Secure”. This is because only members of the Secure
Operations team are permitted access to Sysdig Secure, and
newly-created logins are not in this team by default. Such a user should
contact an Administrator for the Sysdig environment to be added to the
Secure Operations team.
Environments that wish to have all users access Secure by default
could use this example
script
to frequently “sync” the team memberships.
Configure Sysdig Monitor and/or Sysdig Secure as a SAML application
using Okta’s documentation for Setting Up a SAML Application in
Okta.
The notes below call out specific steps that require additional action.
Sysdig-Specific Steps for Okta Configuration
IDP-Initiated Login Flow
If you don’t intend to configure IDP-initiated login flow, check the
boxes for “Do not display application icon to users” and “Do not display
application icon in the Okta Mobile app”.
SSO, URI, and RelayState Values
Enter the values shown in the table below, replacing HOSTNAME with
the hostname through which your users access the Sysdig application(s)
and PORT with the TCP port # (typically 443).
To configure IDP-initiated login flow, replace CUSTOMER-ID-NUMBER
with the number retrieved as described in Find Your Customer
Number. (Normally the
Customer ID will be 1 in on-prem installations.)
Setting
Value for Sysdig Monitor
Value for Sysdig Secure
Single sign on URL
https://HOSTNAME:PORT/api/saml/auth
https://HOSTNAME:PORT/api/saml/secureAuth
Audience URI (SP Entity ID)
https://HOSTNAME:PORT/api/saml/metadata
https://HOSTNAME:PORT/api/saml/metadata
Default RelayState
(optional - only configure if you intend to use IDP-initiated login flow)
#/&customer=CUSTOMER-ID-NUMBER
#/&customer=CUSTOMER-ID-NUMBER
You must include the port number in the IDP-side configuration,even though port 443 is the typical default for https:// URLs.
Email and Name Values
Instead of those shown in the Okta example, add these values:
Name
Value
email
user.email
first name
user.firstName
last name
user.lastName
Note that the attributes are case sensitive, so use caution when
entering them.
Only email is required. However, including first/last name is
recommended, since these values will now be included in the records
created in the Sysdig platform’s database when new users successfully
login via SAML for the first time.
URL Metadata Value
Copy the URL and paste in the Metadata entry on the SAML
Configuration page in the SAML connection settings.
Test Metadata (Optional)
To ensure the metadata URL you copy at the end of the IDP configuration
procedure is correct, you can test it by directly accessing it via your
browser.
When accessing the URL, your browser should immediately download an XML
file that begins similarly to the example shown below. No entry of
credentials or other security measures should be required to
successfully download it. If this is not the case, revisit the IDP
configuration steps.
Configure Sysdig Monitor and/or Sysdig Secure as a SAML application
using OneLogin’s article titled Use the OneLogin SAML Test
Connector.
The notes below call out specific steps that require additional action.
Sysdig-Specific Steps for OneLogin Configuration
Adding the SAML Test Connector
At the step for “Adding the SAML Test Connector”, select SAML Test
Connector (IdP w/ attr w/ sign response). If you don’t intend to
configure IDP-initiated login flow, uncheck the slider so it will no
longer be “Visible in portal”.
Test Connector Configuration Page Settings
At the “Test Connector Configuration Page”, enter the values shown in
the table below. If you wish to configure IDP-initiated login flow,
replace CUSTOMER-ID-NUMBER with the number retrieved as described
in the Find Your Customer
Number article.
Field
Value for Sysdig Monitor
Value for Sysdig Secure
RelayState
(optional - only configure if you intend to use IDP-initiated login flow)
#/&customer=CUSTOMER-ID-NUMBER
#/&customer=CUSTOMER-ID-NUMBER
Recipient
https://HOSTNAME:PORT/api/saml/auth
https://HOSTNAME:PORT/api/saml/secureAuth
ACS (Consumer) URL Validator
https://HOSTNAME:PORT
https://HOSTNAME:PORT
ACS (Consumer) URL
https://HOSTNAME:PORT/api/saml/auth
https://HOSTNAME:PORT/api/saml/secureAuth
You must include the port number in the IDP-side configuration,
even though port 443 is the typical default for https:// URLs.
(Optional) If you want the user’s First Name and Last Name to be
included in the records created in the Sysdig platform’s database when
new users successfully login via SAML for the first time, click to the
Parameters tab. Click Add parameter and create each of two New
Fields, checking the box each time to Include in SAML assertion.
Then click to Edit each field and select the Value shown from
the drop-down menu before clicking Save.
Field Name
Value
first name
First Name
last name
Last Name
Note that the Field Names are case sensitive , so be careful to
enter them as all lowercase.
The following shows an example of a correctly-configured field for First
Name:
Issuer URL
Click to the SSO tab, copy the Issuer URL, and paste in the
Metadata entry on the SAML Configuration page in the SAML
connection settings.
Test Metadata (Optional)
To ensure the metadata URL you copy at the end of the IDP configuration
procedure is correct, you can test it by directly accessing it via your
browser.
When accessing the URL, your browser should immediately download an XML
file that begins similarly to the example shown below. No entry of
credentials or other security measures should be required to
successfully download it. If this is not the case, revisit the IDP
configuration steps.
This topic explains how to configure SAML Single Sign On (SSO) with
Azure Active Directory (AD) and helps you configure Sysdig to allow
users to access Sysdig application by using SSO.
Prerequisites
Administrator privileges on Sysdig and Azure.
Configure the Sysdig Application in Azure AD
Log in to the Azure AD portal.
Select Azure Active Directory, then click Enterprise
Applications.
The Enterprise applications - All application screen is displayed.
Click New Application.
On the Add an Application screen, select Non-gallery
application.
Give your application a name, and click Add at the bottom of the
page.
On the menu, select Single sign-on.
Choose SAML as the sign-on method.
Edit the Basic SAML Configuration as follows:
In the configuration page, click the edit icon.
Specify the following:
Identifier (Entity ID): Uniquely identifies the Sysdig
application. Azure AD sends the identifier to the Sysdig
application as the audience parameter of the SAML token.
Sysdig validates this as part of the SSO process.
Relay State: Specifies to the application where to
redirect the user after authentication is completed.
Typically the value is a valid URL for Sysdig. If you are
configuring SSO for SaaS, change the relay state to reflect
the correct customer number associated with your Sysdig
application. For on-prem installations, the customer number
is always 1.
The format is:
#/&customer=1234
Sign on URL: It is the sign-in page for the Sysdig
application that will perform the service provider-initiated
SSO. Leave it blank if you want to perform
identity-provider-initiated SSO.
In the Sysdig application, you need to set the email to
emailaddress which is what Azure AD sends to Sysdig in the
SAML assertion. Alternatively, Azure AD can be modified to send
another attribute.
Click Save.
Select SAML from the Enable Single Sign On drop-down.
Create a User in Azure Active Directory Domain
Log in to the Azure AD portal.
Click Azure Active Directory, and note down the domain name.
Select Azure Active Directory, then Users.
The Users - All Users screen is displayed.
Select New Users .
You can either create a new user or invite an existing AD.
Enter name, username, and other details, then click Create.
In the Profile page, add the Email and Alternate Email
parameters. The values can match
Assign the User to the Sysdig Application
Navigate to the Sysdig application.
Click Users and Group, then click the Add user button.
Select the Users and Groups checkbox, then choose the newly
created user to add to the application.
Click Select, then Assign at the bottom of the screen.
Enable Authentication Settings in the Sysdig Instance
Ensure that Flag to enable/disable create user on login is enabled.
Typically this setting is enabled by default.
If you are using both Sysdig Monitor and Secure, ensure that the user
accounts are created on both the products. A user that is created only
on one Sysdig application will not be able to log in to another by using
SAML SSO.
if you are on Sysdig Platform versions 2.4.1 or prior, contact Sysdig
Support to help with user creation.
(Optional) Configure Sysdig as a New Application
If Azure Active Directory does not allow you to create Sysdig as a
Non- Gallery application, perform the following:
In Azure AD, click Enterprise Applications > New
Application.
Select Application you’re developing.
You will be taken to the app registration page:
Select New Registration:
Provide a name for the application you are registering.
These instructions assume you already have a working, Internet-accessible ADFS ( Active Directory Federation Service) server. Interoperability testing has been performed specifically with ADFS on Windows Server 2012 R2.
Follow the instructions below to configure ADFS with the ADFS
Management tool in the Windows Server Manager.
For Service-Provider-Initiated Login Flow
Right-click to Service > Edit Federation Service Properties.
Note the hostname in the Federation Service Identifier, as this will
be used in the metadata URL that you paste in the Metadata entry on
the SAML Configuration page in the Sysdig authentication settings.
Specifically, the metadata URL will be of the format
https://HOSTNAME/FederationMetadata/2007-06/FederationMetadata.xml.
Also, so that the Sysdig platform can access this URL directly, this
host must resolve in DNS and have a valid (not self-signed)
SSL/TLS certificate.
Add a Relying Party Trust configuration for the Sysdig application.
Right-click to Relying Party Trusts > Add Relying Party
Trust and click Start to begin the wizard.
In the Select Data Source step, click the button to Enter
data about the relying party manually, then click Next
Enter a Display name of your choosing (e.g. “Sysdig Monitor”
or “Sysdig Secure”), then click Next
Click Next to accept the default option to use AD FS
profile
Click Next to skip the selection of an optional token
encryption certificate (Sysdig does not support this option)
Check the box to Enable support for the SAML 2.0 Web SSO
protocol, then enter one of the following values for Relying
party SAML 2.0 SSO service URL:
If configuring Sysdig Monitor in the US East, enter:
https://<hostname>/api/saml/auth
If configuring Sysdig Secure in the US East, enter:
https://<hostname>/api/saml/secureAuth
Replace <hostname> with the unique hostname associated
with your on-prem deployment. For other regions, the format is
https://<region>.<hostname>/api/saml/auth and
https://<region>.<hostname>/api/saml/secureAuth.
Then click Next.
For the Relying party trust identifier, enter one of the
following values:
If configuring Sysdig Monitor in the US East, enter:
https://<hostname>
If configuring Sysdig Secure in the US East, enter:
https://<hostname>/secure/
Replace <hostname> with the unique hostname associated
with your on-prem deployment. For other regions, the format is
https://<region>.<hostname>/api/saml/auth and
https://<region>.<hostname>/api/saml/secureAuth.
Then click Add, then click Next
Click Next to skip configuration of multi-factor
authentication
Choose a policy for whether users will be permitted to login to
the Sysdig application. The default to Permit all users to
access the relying party will typically be acceptable. Click
Next.
Review the summary and click Next to complete the
configuration of the Relying Party Trust
The next step will involve adding Claim Rules, so you can leave
the box checked to Open the Edit Claim Rules dialog and
click the Close button to be brought immediately into the
Claim Rules editor
Ensure that the SamlResponseSignature option matches the Sysdig
authentication configuration.
Use the
Set-AdfsRelyingPartyTrust/Get-AdfsRelyingPartyTrust cmdlets
via PowerShell to configure SamlResponseSignature .
-SamlResponseSignatureSpecifies the response signatures that the relying party expects. The acceptable values for this parameter are:AssertionOnlyMessageAndAssertionMessageOnly
Navigate to Settings > Authentication on the Sysdig
app and check the Sysdig authentication setting maps to the
SamlResponseSignature :
For MessageAndAssertion, enable both the options.
Next, use the Claim Rules to ensure that login data is sent as
needed to the Sysdig platform. A user’s login to the Sysdig platform
is based on an email address, and a default ADFS configuration would
not send the email address as required. The following configuration
ensures the correct field from Active Directory is delivered in the
claim.
If not already in the Claim Rules editor from the previous step,
navigate to it by right-clicking on the Relying Party Trust that
was just created and selecting Edit Claim Rules
Click Add Rule. At the following screen, accept the default
rule template to Send LDAP Attributes as Claims and click
Next.
Enter a name for the rule, select Active Directory as the
Attribute store, then use the pull-down selectors to pick
E-Mail Address as both the LDAPAttribute and
Outgoing Claim Type, then similarly make pull-down
selections for Given Name and Surname. Once these
selections are made, click Finish.
Now click Add Rule again, this time selecting the template
for Transform an incoming claim
Enter a name for the rule, then use the pull-downs to select an
Incoming claim type of E-Mail Address, an Outgoing
claim type of Name ID, and an Outgoing name ID format
of Email, then click Finish.
(Optional) If you want the user’s First Name and Last Name to be
included in the records created in the Sysdig platform database
when new users successfully login via SAML for the first time,
additional Transform rules must also be created. Only the
email-based username is strictly required and we already created
a rule for this, so this step is optional.
If you wish to do this, click Add Rule and once again select
the template for Transform an incoming claim. Enter a name
for the rule, then use the pull-down to select an Incoming
claim type of Given Name, and for the Outgoing claim
type, directly type first name into the field. After
clicking Finish, click Add Rule and create a similar
rule to transform the Incoming claim type of Surname to
the Outgoing claim type of last name.
Having clicked Finish after creating your last rule, you
will see all rules now in the editor. Click Ok, and your
ADFS configuration for your Sysdig application is complete.
For IdP-Initiated Login Flow (Optional)
(Optional) The steps above represent a Service-Provider-Initiated
SAML configuration. If you would prefer an IdP-initiated SAML
configuration, this is also possible with ADFS, but requires the
additional steps described below.
The Sysdig platform requires a specific setting of RelayState in
order to accept IdP-initiated login flows. On the ADFS versions
tested, we’ve found this use of RelayState is disabled by default,
and a Microsoft
article
describes the topic in detail. To enable it, as described in a
Microsoft forum
thread,
on your ADFS host, edit
%systemroot%\ADFS\Microsoft.IdentityServer.Servicehost.exe.config
and add <useRelayStateForIdpInitiatedSignOn enabled="true" />
to the <microsoft.identityserver.web> section. Once the
modification is saved, restart ADFS services for the change to take
effect.
You will need to retrieve your Sysdig customer number as described
in the Find Your Customer
Number article.
You will then need to generate an IdP-initiated login URL.
In addition to having the correct settings, it must be properly URL
encoded. To ease this configuration, use this ADFS RelayState
Generator
tool. When launched, enter the values below, then hit the Generate
URL button.
For the IDP URL String, enter
https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx
For the Relying Party Identifier, enter one of the following
values if you are in the US East region:
If configuring Sysdig Monitor, enter
https://<hostname>.
If configuring Sysdig Secure, enter
https://<hostname>/secure/
Replace <hostname> with the unique hostname associated with
your on-prem deployment.
For other regions, the format is https://<region>.<hostname> for Sysdig Monitor and
https://<region>.<hostname>/secure/
for Sysdig Secure. Replace <region> with the region
where your Sysidig application is hosted.
For the Relay State/Target App, enter
#/&customer=CUSTOMER-ID-NUMBER, substituting the
CUSTOMER-ID-NUMBER you retrieved in the previous step
This Results URL will be used in the metadata URL that you paste
in the Metadata entry in the SAML connection
settings.
Use the Results URL from the tool to test your IdP-initiated
login. Note that per this Microsoft forum
thread,
it is apparently not possible to configure ADFS to use such a URL
when your users select the application from the pull-down menu at
https://YOUR_ADFS_SERVER/adfs/ls/idpinitiatedsignon.aspx.
However, you may embed the URL into a custom portal or bookmarks
list.
Now you can test login using an Active Directory user that has an
Email address configured.
Test Metadata (Optional)
To ensure the metadata URL you copy at the end of the IDP configuration
procedure is correct, you can test it by directly accessing it via your
browser.
When accessing the URL, your browser should immediately download an XML
file that begins similarly to the example shown below. No entry of
credentials or other security measures should be required to
successfully download it. If this is not the case, revisit the IDP
configuration steps.
These instructions are specific to On-Premises
Deployments of the Sysdig
platform. If you are using the cloud-based (SaaS) Sysdig platform, refer
to OpenID Connect (SaaS)
instead.
This section describes how to integrate and enable OpenID Connect with
both Sysdig Monitor and Sysdig Secure.
Overview
Summary of OpenID Functionality in Sysdig
The Sysdig platform ordinarily maintains its own user database to hold a
username and password hash. OpenID instead allows for redirection to
your organization’s IdP to validate username/password and other policies
necessary to grant access to Sysdig application(s). Upon successful
authentication via OpenID, a corresponding user record in the Sysdig
platform’s user database is automatically created, though the password
that was sent to the IdP is never seen nor stored by the Sysdig
platform.
Basic Enablement Workflow
Step
Options
Notes
1. Know which IdP your company uses and will be configuring.
These are the OpenID Providers for which Sysdig has performed detailed interoperability testing and confirmed how to integrate using their standard docs. If your OpenID Provider is not listed (including ones that do not support OpenID Connect Discovery), it may still work with the Sysdig platform. Contact Sysdig Support for help.
2. Decide the login flow you want users to experience: 3 options
Replace <hostname> with the hostname of your deployment.
3. Perform the configuration steps in your IdP interface and collect the resulting config attributes.
Collect metadata URL (or XML) and test it.
If you intend to configure IDP-initiated login flow find your Customer Name. Contact Sysdig if you do not know the customer name corresponding to your account.
4a. Log in to Sysdig Monitor and configure authentication.
4b. Log in to Sysdig Secure and configure authentication.
Log in to Sysdig Monitor Settings (as super admin) and enter the necessary configuration information in the UI. Save and Enable OpenID as your SSO.
Log in to Sysdig Secure Settings (as super admin) and enter the necessary configuration information in the UI. Save and Enable OpenID as your SSO.
Administrator Steps
Configure IdP
Select the appropriate IdP link below, and follow the instructions:
Required. Endpoint that contains key credentials for token signature verification
Token Auth Method
Authentication method.
Supported values:
client_secret_basic ,
client_secret_post . (case insensitive)
Select OpenID for SSO
Select OpenID from the Enabled Single Sign-On dropdown.
Click SaveAuthentication.
Script-Based: Configure OpenID Using Scripts
The configuration of the OpenID Connect feature can be viewed, updated,
and deleted by the “super”
Admin. An
oidc_config.sh helper script is available in the
SSO
folder at sysdig-cloud-scripts repository to assist in completing
this configuration. Invoking the script with no options will display
help text.
# ./oidc_config.shMust specify the Sysdig App whose OpenID Connect configuration will be viewed/setUsage:./oidc_config.sh [OPTIONS]Affect OpenID Connect login settings for your Sysdig software platform installation
To use the helper script, modify env.sh to set the required values
for API_TOKEN of the “super” Admin user and the URL for
accessing the Sysdig platform API (which will be the same URL that your
users access for the Sysdig Monitor application).
Depending if the API_TOKEN has been obtained from the Sysdig Monitor or
Sysdig Secure application UI, the settings will be applied to the
consequent product.
Initially no OpenID settings are set. A initial run of the script would
confirm that:
# ./oidc_config.shNoopenid settings are setRun for further info:./oidc_config.sh -h
Add the -s option to set the OpenID Connect configuration for a
particular Sysdig application. When setting the config, you’ll use
additional options to provide the config details you saved in the
earlier OpenID Provider configuration step.
Config Detail
Option
Issuer URL
-u
Client ID
-i
Client Secret
-e
If the configuration is successfully posted to the Sysdig platform, the
new configuration will be echoed back.
An example of creating the two separate OpenID Connect configurations
for both Monitor and Secure, each using Okta as an OpenID Provider:
Once you’ve completed this configuration, clicking the OpenID button at
the login screen of the appropriate Sysdig application(s) should
redirect to your OpenID Provider for authentication.
If you wish to delete your OpenID Connect configuration, invoke the
-d option. If successful, the disabled configuration will be
printed.
You can configure an IdP-initiated login flow when configuring your
IdP. The users then select the Sysdig application from your IDP’s
app directory and do not browse directly to a Sysdig application URL
at all.
The notes below describe minimal steps to be taken in Okta. You may need
to adjust the steps based on the specifics of your environment.
Log in to your Okta organization as a user with administrative
privileges and click the Admin page.
Click Add Applications, then click the Create New App button.
Select Web as the Platform type, then click OpenID Connect as
the Sign-on method, then click Create.
Create a new application
Enter your choice of General Settings
For Login redirect URIs, enter one of the following values,
replacing HOSTNAME with the hostname through which your
users access the Sysdig application(s) and PORT with the
TCP port # (typically 443):
If configuring Sysdig Monitor, enter:
https://HOSTNAME:PORT/api/oauth/openid/auth
If configuring Sysdig Secure, enter:
https://HOSTNAME:PORT/api/oauth/openid/secureAuth
Click Save.
You should next be placed in a General tab. Take note of the
Client ID and Client secret that are shown, as you will need
them to complete the configuration in the Sysdig platform.
Click the Sign On tab. Take note of the Issuer URL that is
shown, as you will need it to complete the configuration in the
Sysdig platform.
Return to the bottom section of the OpenID Connect
(On-Prem) article for
instructions on using the helper script to complete the
configuration in the Sysdig platform.
The notes below describe minimal steps to be taken in OneLogin. You may
need to adjust the steps based on the specifics of your environment.
Login to your OneLogin organization as a user with administrative
privileges and click to Apps > Custom Connectors, then click the
New Connector button.
Create a new Connector
Enter your choice of connector name
Select a Sign on Method of OpenID Connect
For Redirect URI to, enter one of the following values,
replacing HOSTNAME with the hostname through which your
users access the Sysdig application(s) and PORT with the
TCP port # (typically 443):
If configuring Sysdig Monitor, enter:
https://HOSTNAME:PORT/api/oauth/openid/auth
If configuring Sysdig Secure, enter:
https://HOSTNAME:PORT/api/oauth/openid/secureAuth
Click the Save button
From the More Actions pull-down menu, select
Add App to Connector.
Click Save to add the app to your catalog. Once clicked,
additional tabs will appear.
Click to the SSO tab. Change the setting in the Token Endpoint
drop-down to POST, then click Save.
While still on the SSO tab, take note of the Client ID and
Client Secret that are shown (click Show client secret to
reveal it), as you will need them to complete the configuration in
the Sysdig platform.
Note that the Issuer URL you will need to complete the Sysdig
platform configuration will consist of
https://YOUR-ONELOGIN-DOMAIN.onelogin.com/oidc
Return to the bottom section of the OpenID Connect
(On-Prem) article for
instructions on using the helper script to complete the
configuration in the Sysdig platform.
The notes below describe minimal steps to be taken in Keycloak. You may
need to adjust the steps based on the specifics of your environment.
Login to your Keycloak server’s Administrative Console.
Select a realm or create a new one.
Click Clients, then click the Create button.
Enter the Client ID of your choosing (e.g. “SysdigMonitor”) and
take note of it, as you will need it later to complete the
configuration in the Sysdig platform.
Make sure the Client Protocol drop-down has openid-connect
selected. Click the Save button.
Configure OpenID Connect client
Click the toggle for Authorization Enabled to ON
For Valid Redirect URI, enter one of the following values,
replacing HOSTNAME with the hostname through which your
users access the Sysdig application(s) and PORT with the
TCP port # (typically 443):
If configuring Sysdig Monitor, enter:
https://HOSTNAME:PORT/api/oauth/openid/auth
If configuring Sysdig Secure, enter:
https://HOSTNAME:PORT/api/oauth/openid/secureAuth
Click the Save button
Click to the Credentials tab. Take note of the Secret that is
shown, as you will need it to complete the configuration in the
Sysdig platform.
Note that the Issuer URL you will need to configure in the
Sysdig platform will consist of
https://{KEYCLOAK-SERVER-ADDRESS}/auth/realms/{REALM_NAME},
where {KEYCLOAK-SERVER-ADDRESS} and {REALM-NAME} are derived
from your environment where you just created the configuration.
Return to the bottom section of the OpenID Connect
(On-Prem) article for
instructions on using the helper script to complete the
configuration in the Sysdig platform.
7.3.4 - Azure (OpenID On-Prem)
OpenID Connect
is a security-token based extension of the OAuth
2.0 authorization protocol to do single sign-on. Azure Active Directory
provides an
implementation
of OpenID Connect (OIDC) protocol and Sysdig supports it for single
sign-on and API access to Sysdig application.
Enabling Azure OpenID Connect for single sign-on to Sysdig applications
include configuration on the Microsoft Active Directory as well as on
the Sysdig application.
Prerequisites
Administrator privileges on Sysdig and Azure Active Directory (AD).
Select your Azure Active Directory service or create a new one.
Click App registration > New registration.
In the Register an application page, specify the following:
Name: Display name to identify your Sysdig application. For
example, Sysdig Secure.
Supported account types: Choose an account type that is
appropriate for your deployment. If you choose single-tenant,
all user and guest accounts created in your active directory can
use Sysdig application and API. If you choose multi-tenant, all
users with a work or school account from Microsoft can use
Sysdig application and API.
Redirect URI: Authenticated Sysdig users are redirected to
this URI.
For Login redirect URIs, enter one of the following values,
replacing HOSTNAME with the hostname through which your
users access the Sysdig applications and PORT with the TCP
port number, typically 443:
For Sysdig Monitor:
https://HOSTNAME:PORT/api/oauth/openid/auth
For Sysdig Secure:
https://HOSTNAME:PORT/api/oauth/openid/secureAuth
You can add only a single redirect URL on this page. Use the
Authentication page associated with your application to add
additional redirect URIs.
Click Register.
Add additional redirect URIs.
Select your application from App registration.
Click Authentication from the left navigation.
Add the redirect URIs corresponding to Monitor and Secure.
Create a Secret for the Sysdig application.
It is a string that the Sysdig application uses to prove its
identity when requesting a token.
Click Certificates & secrets.
Under Client Secrets, click New client secret.
Enter a description that identifies the secret and choose an
expiration period.
Click Add.
Copy the client secret. You will need the client secret while
configuring OpenID Connect SSO on the Sysdig application.
Copy the Client ID and OpenID Connect endpoints corresponding to the
application that you have created.
Select your application from App registration.
Copy the Application (client) ID.
You will need the client ID while configuring OpenID Connect SSO
on the Sysdig application.
Click Endpoints.
Copy the OpenID Connect metadata document and open it in a
browser.
LDAP
support in the Sysdig software platform allows user authentication using
credentials in a customer’s own directory server. LDAP support is not
currently available the cloud-based (SaaS) Sysdig platform.
The configuration and functionality of LDAP has changed significantly in
recent releases of the platform. It is recommended to upgrade to the
newest on-prem release to take advantage of improvements. However, if
you are running an older release and cannot yet upgrade, contact Sysdig
Support if you need further assistance.
General LDAP Tips
Testing Configurations With ldapsearch
Small typos in fields such as search filters can cause failures that are
difficult to debug. You may want to perfect your more complex
configurations before applying them via the helper scripts. This will
help “divide & conquer” as to whether an issue is generic to LDAP syntax
and/or the directory vs. a possible bug in the Sysdig platform.
If you have an Ubuntu Linux host at your disposal that can access your
directory server via LDAP, install the ldap-utils package:
# sudo apt install ldap-utils
If accessing LDAP over SSL/TLS, edit the file /etc/ldap/ldap.conf
and add the following line:
TLS_REQCERT allow
Then copy the CA certificate (the same one that was uploaded in the
Settings of the Replicated console) to a location on the host, such as
/tmp/cert.pem .
Excluding Classes of Users (e.g. Disabled Accounts)
Per this
post,
Active Directory admins may leverage certain queries to easily exclude
certain classes of users from being able to authenticate to the Sysdig
platform. For example, the following will filter out users whose
accounts have been disabled in Active Directory.
(!(userAccountControl:1.2.840.113556.1.4.803:=2))
This can be combined with other config via AND logic, such as by
extending one of our searchFilter examples:
If you are running GA Releases 1149-1511, refer to this other
article
instead.
LDAP
support in the Sysdig software platform is used to allow user
authentication using credentials in an enterprise’s own directory
server.
This document describes how to configure base LDAP settings, as well as
the limitations of the LDAP support.
Overview
Functionality
The Sysdig platform ordinarily maintains its own user database to hold a
username and password hash, as well as settings for Admin privileges,
Sysdig team membership, and a user’s configured dashboards and alerts.
Sysdig’s LDAP authentication feature provides a means to allow the
Sysdig platform to query your separate directory server to validate
username/password. Upon successful authentication, a corresponding user
record in the Sysdig platform’s user database is automatically created.
When the LDAP feature is in use, the user’s directory password is not
stored in the Sysdig user database.
Once LDAP authentication is enabled, all normal user authentication
will be performed against your configured directory server. Other local,
non-LDAP users that were created before LDAP was enabled can still
authenticate via LDAP as long as their username in your directory
matches with the username of their pre-existing record in the Sysdig
user database. For example, consider a user jdoe@example.com who
had been a user in the Sysdig environment before LDAP was enabled. Once
LDAP authentication is enabled, if a user jdoe exists in the
directory server and is able to authenticate successfully via LDAP, they
will be permitted to log in to the Sysdig platform as the pre-existing
jdoe@example.com user. Any user-specific configuration (Alerts,
Dashboards, etc.) that were attached to jdoe@example.com will
still be visible to this user. Any password previously set for such a
pre-existing user record will not be used for authentication to the
Sysdig platform unless LDAP authentication is disabled.
LDAP can be complex to configure. Sysdig strongly recommends that you
first refine your LDAP configuration in a separate test setup before
applying the LDAP settings in your production environment.
Prerequisite: Have the “Super” Admin User Credentials and Token
In an environment enabled for LDAP authentication, the one user still
subject to direct email+password authentication is the “super” Admin
user.
Creation of this user is a required initial install step.
You can find the credentials either in the Replicated console
(screenshot below) or your Kubernetes
ConfigMap
element sysdigcloud.default.user .
This user is required and cannot be deleted. This login provides:
A way to access the Sysdig platform when LDAP connectivity is
severed.
The first Admin user in the install, essential for assigning Admin
rights to other users once they’ve authenticated via your directory
and their user records have been added to the Sysdig user database.
The user whose token can be used to perform further LDAP
configurations.
There are two ways to configure the basic LDAP settings for Sysdig: via
the Sysdig UI, or via the API endpoint using scripts and HTTP methods.
Whichever method is used, it will apply LDAP settings globally, to both
Sysdig Monitor and Sysdig Secure.
UI-Based: Configure LDAP in Settings
At this time, the Authorization UI is available only for Sysdig Monitor.
Enter LDAP Connection Settings
Log in to Sysdig Monitor or Sysdig Secure as the “super” Admin
user. and select
Settings.
Select Authentication.
Select the LDAP tab.
Enter the relevant parameters (see tables below) and click Save.
Table_loginConnectionSettings
Setting
Required
Description
server
Yes
URL of the directory server for the Sysdig platform to query. An example for LDAP over SSL:
ldaps://172.16.0.1:636
For cleartext LDAP:
ldap://176.16.0.1
Note that to use LDAPS, you'll also need to use the Replicated console (or equivalent approach in Kubernetes-based installs) to upload a Certificate Authority (CA) PEM-format certificate that the Sysdig platform will use to validate its SSL connection to the server. If you have a host with OpenSSL tools installed that can reach the directory server, you can obtain the certificate by running:
The command output will typically show the server certificate first and the CA certificate second, both in PEM format. Into a text file, paste the CA certificate portion of the output that looks like:
Under LDAP CA certificate in the PEM format in the Replicated console, click the "Choose File" button and browse to the file you just created to select and upload it. Note that when you click Save, the Sysdig platform will restart. This is the only setting related to LDAP that requires a platform restart.
Note: For environments using self-signed certificates, the openssl command shown above will return only one certificate.
managerDn
Yes
The distinguished name of a user that the Sysdig platform can authenticate as via LDAP in order to perform further queries about the users attempting to login to the Sysdig platform. Example:
cn=Administrator,cn=Users,dc=example,dc=local
This setting is required, as the Sysdig platform does not support connection to servers via anonymous bind.
managerPassword
Yes
The password for the managerDn.
rootDn
No
The distinguished name for the point in the LDAP tree below which all search queries will begin. Example:
dc=example,dc=local
referral
No
Defines whether the Sysdig platform will chase referrals found in LDAP query responses. If not specified, this will be set to "IGNORE" in your configuration and referrals will not be chased. See the section below on Multi-Server Directories for more details on this option.
Table_loginFilter
Setting
Required
Description
searchBase
Yes
A relative distinguished name (from the rootDn) below which queries about users should be performed. Example:
cn=Users
If specified as an empty string (""), the search will be performed across everything below the rootDn, in which case the rootDn setting must be configured.
Note that if the rootDn setting was not specified, the searchBase setting must provide a full distinguished name. Example:
cn=Users,dc=example,dc=local
searchFilter
No
An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify the user record. The marker token {0} represents where the username will appear when LDAP queries are constructed. An example that targets the attribute sAMAccountName in Active Directory:
While this setting is optional, if not specified, no users will be able to authenticate via LDAP.
Select LDAP for SSO
Select LDAP from the Enabled Single Sign-On dropdown
Click Save Authentication.
Repeat entire enablement process for Sysdig Monitor or Sysdig
Secure, if you want to enable on both applications.
Script-Based: Configure LDAP Using Scripts
The configuration of the LDAP feature can be viewed, updated, and
deleted by the “super” Admin via the API endpoint
/api/admin/ldap/settings using HTTP methods for GET,
POST, and DELETE, respectively.
Access login_config.sh and verify_user.sh
helper scripts available in the
SSO
folder at sysdig-cloud-scripts repository, to assist in completing
this configuration.
Modify the
env.sh
to enter the API_TOKEN and the URL of your environment.
Modify settings_login_simple.json file with Login Connection
settings and Login Filter settings.
Execute various scripts
# get current settings: initially empty./login_config.sh# set settings we have detailed above./login_config.sh -s settings_login_simple.json# verify an existing user information is retrieved./verify_user.sh -u jdoe# verify a non existing user information is not retrieved./verify_user.sh -u nothere# optionally delete the settings# ./login_config.sh -d
See Advanced Use Cases (below) if you have a multi-server
environment, or want to create LDAP users before they log in.
Details of this workflow are as follows:
Configure env.sh
To use the helper script, modify the env.sh
to set the required values for API_TOKEN and URL for your
environment. Once set, invoking login_config.sh (at the
sysdig-cloud-scripts
repository
in GitHub) helper script with no options will print the current
configuration. Initially empty.
Retrieve Current LDAP Settings
# ./login_config.shNoldap settings are setRun for further info:./login_config.sh -h
Configure settings_login_simple.json and set withlogin_config.sh
In the sysdig-cloud-scripts
repository
in GitHub, find the example settings_login_simple.json and
modify it for your environment, following the Tables above.
To apply the new LDAP settings invoke login_config.sh with the
-s option and specify the filename containing the JSON config:
Using the specific example settings_login_simple.json and the
minimal Active Directory configuration in the screenshot below, login to
the Sysdig platform would now be permitted for a user jdoe that
has the following distinguishedName:
CN=John Doe,CN=Users,DC=example,DC=local
Test User Login
To test the login configuration, the “super” Admin
user
can confirm if a particular user would be permitted to login given
current LDAP login connection settings. To do this, perform an HTTP
GET to the API endpoint
/api/admin/ldap/settings/verify/USERNAME . A verify_user.sh
helper script is provided to easily perform this. If invoked with the
-u option and a username, and the user’s login would be
successful, it will return the user’s information from the directory.
If the user would not be able to login, an error message will be
returned.
# ./verify_user.sh -u nothereCould not verify user "nothere". Check LDAP login config settings and/or system log.
Note that if LDAP authentication is disabled this method for testing
user login is not available.
Optional: Delete LDAP settings
To delete LDAP settings, invoke login_config.sh with the -d
option. After running the following command all LDAP users will not be
able to login to the Sysdig platform.
When a user accesses the Sysdig interface, they are prompted to enter
their LDAP credentials (in the fields normally used for email/password).
Monitor: https://HOSTNAME/ or Secure: https://HOSTNAME/secure
Advanced Use Cases
Multi-Server Directories
Data about your users that need to access the Sysdig platform may be
stored across many directory servers in your environment. As the Sysdig
platform is only able to query one LDAP server endpoint, you would need
to take extra steps to ensure successful authentication for such users.
The simplest approach to achieve this is to query against a Global
Catalog.
As the Global Catalog stores a copy of all Active Directory objects in a
forest, this provides a fast and convenient target for the Sysdig
platform to find all users that may need to authenticate. Since queries
against the Global Catalog are also performed via LDAP, you simply need
to ensure your LDAP configuration specifies the appropriate address and
TCP port for the Global Catalog, e.g. ldap://176.16.0.1:3268 for
cleartext LDAP or ldaps://172.16.0.1:3269 for LDAP over SSL. If querying
against a Global Catalog, the referral option of the Sysdig
platform’s LDAP configuration can remain at its default setting of
"IGNORE".
If a Global Catalog is not available, another approach is to leverage
referral
chasing.
Such chasing depends on complex interplay of configuration settings, DNS
resolution, and network connectivity to multiple servers. If you require
this option, carefully read the tips in this section and validate your
configuration in a test environment before attempting its use in
production. Contact Sysdig support for assistance as necessary.
For our example configuration, we’ve added another Domain Controller to
our environment that holds users a separate set of users for the child
domain eu.example.local.
We’d like to permit login for a user “eurodude” in the child
domain. This user has distinguishedName:
CN=Euro Dude,CN=Users,DC=eu,DC=example,DC=local
In the example configuration settings_login_referral_follow.json
shown below, the Sysdig platform still begins its LDAP queries at the
same top-level server target. However, the referral option is set
to "FOLLOW", which will cause the Sysdig platform to perform
subsequent queries if a query returns one or more referrals.
Note also how in this case the rootDn option is left unspecified
and the searchBase is set to the distinguished name of the
top-level domain. This is necessary to ensure the scope of the chased
referral queries will include the child domain. If **rootDn **and
searchBase had been left as they were set in the
settings_login_simple.json example, the initial query would have
been targeted only within cn=Users,dc=example,dc=local and hence
the referral would never have been returned by the top-level server.
Note these other caveats of referral chasing in the Sysdig platform:
Referrals may only be successfully chased to child domains. If
referrals point to parallel domains (e.g. for our example,
dc=adjacent,dc=local) the queries will not succeed and users
stored in the directory servers for such domains will not be able to
authenticate.
The LDAP library used by the Sysdig platform does not log
information about each referral it attempts to chase. Therefore, if
you enable referral chasing, it is important that you understand the
server targets that may be chased in your environment and ensure the
network connectivity (routing/firewalls) will permit the Sysdig
platform to query these server targets. If LDAP queries are failing
due to a network connectivity issue, this will typically be
accompanied by delays during Sysdig user logins of approximately 30
seconds followed by a login failure with an HTTP 504 error
message shown in the login screen. If this occurs, contact Sysdig
support for assistance.
Creating LDAP Users Before They Login
The default behavior of the LDAP feature is to create a new record in
the Sysdig user database when a user authenticates successfully via LDAP
for the first time. However, it may be desirable to add such user
records in advance of their first login, such as if you wish to use
automation to change user permissions, assign team membership, or
pre-populate Dashboard/Alert configurations. A create_user.sh
helper script is available in the sysdig-cloud-scripts
repository to create such user records via the API. This script can also
be used to enable/disable this functionality in the Sysdig platform. See
the
README
for details.
Additional details regarding this type of user creation in conjunction
with LDAP authentication:
This method allows creation of any username, even if it doesn’t
currently exist in the directory that is queried via LDAP.
When LDAP authentication is enabled, such users can be created with
a simple username (e.g. jdoe ) or with an email-style postfix
(as is typical for non-LDAP Sysdig user, e.g.
jdoe@example.com ). In this latter case only the username
portion ( jdoe ) is used when the Sysdig platform is
performing an LDAP query during attempted login.
While the password must be included in the config you
POST to create the user, it is not used by the Sysdig platform
when LDAP is enabled, as authentication will always be performed via
LDAP. For this same reason, if a user has been created in this way,
they will not be able to login unless there is a matching user in
the directory that is queried via LDAP.
The firstName and lastName values as specified in the
example are optional and independent from any equivalent name
settings in the directory that is queried via LDAP.
Limitations and Caveats
LDAP support has been tested with Active Directory in Windows Server
2012 R2. It may work with AD versions that ship with other versions
of Windows, or other directory servers that use the LDAP protocol.
If you are intending to use LDAP with something other than Active
Directory, please contact Sysdig Support.
The LDAP feature is only present in Sysdig software platform
installs (not the SaaS version).
Only one LDAP config can exist per deployment (i.e. the platform can
only query one directory server endpoint).
Because the Sysdig software platform is based on the same technology
as the SaaS-based Sysdig service, it theoretically supports the
configuration of multiple “customers” using the same install.
However, the multi-customer option is not supported when the LDAP
feature is enabled.
When LDAP authentication is enabled, adding users via email
“invites” is not possible.
LDAP authentication for directory usernames that begin or end with a
space character (e.g. " jdoe" or "jdoe " ) are not
supported.
Configuration entries that contain special characters (for instance,
a managerPassword that contains a backslash character) are
supported, but note that you will need to perform proper JSON
escaping in the configuration you POST to the API. If you
attempt to post invalid JSON, the helper scripts will return an
error message. If this occurs, you can use tools such as
JSONLint to narrow down the source of the
problem and/or JSON String
Escape to learn how
to properly escape your text.
The LDAP feature does not attempt any ongoing “sync” back from the
Sysdig platform user database to the directory server. Note how this
impacts the following:
If a user is deleted from the directory server, their user
record will remain in the Sysdig user database until a Sysdig
Admin deletes it. Of course, that user will not be able to login
since they will no longer be able to authenticate successfully
via LDAP.
If an Admin deletes a user from the Sysdig user database, but
the user can still authenticate successfully via LDAP, their
Sysdig user record will be recreated if they login again via
LDAP.
If a person’s username should change in the directory server
(e.g. the value for sAMAccountName in our examples above),
the next time they login, a new user record will be created for
them in the Sysdig user database. Settings they previously had
in the Sysdig platform such as Admin rights and Alerts/Dashboard
configurations will not be present for this recreated user.
Other LDAP-centric functionality that is not currently supported
(not an exhaustive list):
Mapping a user in the directory server to the Sysdig “super”
Admin (such as to
avoid the need to configure the this “super” Admin user).
Session expiry based on configuration in the directory server
(such as to set a user account to only be valid until a certain
date).
Login policies based on configuration in the directory server
(such as to restrict login to certain hours).
User timeout functionality (such as to remove a user from the
Sysdig user database if they have not logged in for a certain
amount of time).
LDAP
support in the Sysdig software platform is often leveraged to allow user
authentication using credentials in a customer’s own directory server.
This document describes how to configure base LDAP settings, as well as
the limitations of the LDAP support.
LDAP can be complex to configure. Sysdig strongly recommends that you
first refine your LDAP configuration in a separate test setup before
applying the LDAP settings in your production environment. If you do not
have a “development license” for test purposes or have misplaced your
license information, contact <billing@sysdig.com.>
Summary of Functionality
Independent of the LDAP feature, the Sysdig platform ordinarily
maintains its own user database to hold not only a username and password
hash but also settings for Admin privileges, Sysdig team membership, and
a user’s configured Dashboards and Alerts. Sysdig’s LDAP authentication
feature provides a means to allow the Sysdig platform to query your
separate directory server to validate username/password. Upon successful
authentication, a corresponding user record in the Sysdig platform’s
user database is automatically created. When the LDAP feature is in use,
the user’s directory password is not stored in the Sysdig user database.
Once LDAP authentication is enabled, all normal user authentication
will be performed against your configured directory server. Other local,
non-LDAP users that were created before LDAP was enabled can still
authenticate via LDAP as long as their username in your directory
matches with the the username of their pre-existing record in the Sysdig
user database. For example, consider a user jdoe@example.com who
had been a user in the Sysdig environment before LDAP was enabled. Once
LDAP authentication is enabled, if a user jdoe exists in the
directory server and is able to authenticate successfully via LDAP, they
will be permitted to log in to the Sysdig platform as the pre-existing
jdoe@example.com user. Any user-specific configuration (Alerts,
Dashboards, etc.) that were attached to jdoe@example.com will
still be visible to this user. Any password previously set for such a
pre-existing user record will not be used for authentication to the
Sysdig platform unless LDAP authentication is disabled.
Upgrades - Migration of Settings
Note: This section is only relevant if you have already been using
LDAP support as it existed in Sysdig platform version 858 and earlier
and are upgrading to version 1149 or newer. If you are configuring LDAP
for the first time and are running version 1149 or newer, skip this
section.
LDAP support in version 858 and older was configured exclusively via the
Replicated console or Kubernetes ConfigMap, depending on your
installation type. This required the Sysdig platform to be restarted
after any changes to the LDAP settings. When you upgrade your
environment to version 1149 or newer, your existing settings will be
migrated to a new API-based configuration described below. The only
LDAP-related setting that remains in the Replicated console is the
optional CA certificate for LDAPS connectivity.
For Kubernetes-based installs, you should leave the prior LDAP settings
intact to ensure successful migration upon upgrade. But once you are
successfully running version 1149 or newer, all elements that begin with
sysdigcloud.ldap can be removed from your ConfigMap.
Prerequisite: The “Super” Admin user
In an environment enabled for LDAP authentication, the one user still
subject to direct email+password authentication is the “super” Admin
user. Creation of this user
is a required initial install step either via the Replicated console
(see screenshot below) or Kubernetes
ConfigMap
element sysdigcloud.default.user.
This user is required and cannot be deleted. This login provides:
A way to access the Sysdig platform when LDAP connectivity is
severed.
The first Admin user in the install, essential for assigning Admin
rights to other users once they’ve authenticated via your directory
and their user records have been added to the Sysdig user database.
The user whose REST
API Token
can be used to perform further LDAP configurations via the Sysdig
platform API.
Once other directory-authenticated users have been promoted to Admins,
those Admins can promote other directory-authenticated users to Admin,
and so on.
Configuration of Base LDAP Settings
The configuration of the LDAP feature can be viewed, updated, and
deleted by the “super” Admin via the API endpoint
/api/admin/ldap/settings using HTTP methods for GET,
POST, and DELETE, respectively.
NOTE: See the REST
API page for
general info on the API, and the the Locating the “Super” Admin
User page for guidance on
finding the token for the appropriate “super” Admin user.
A version of a login_config.sh helper script is available in a
beta branch of the sysdig-cloud-scripts
repository
for your use along with an example settings_login_simple.json that
can be modified for your environment. Refer to the tables for
details on config options. Example command-lines below the table
describe how to enable LDAP with these settings.
The follow settings are in the required loginConnectionSettings
section.
Setting
Required
Description
server
Yes
URL of the directory server for the Sysdig platform to query. An example for LDAP over SSL:
ldaps://172.16.0.1:636
For cleartext LDAP:
ldap://176.16.0.1
Note that to use LDAPS, you'll also need to use the Replicated console (or equivalent approach in Kubernetes-based installs) to upload a Certificate Authority (CA) PEM-format certificate that the Sysdig platform will use to validate its SSL connection to the server. If you have a host with OpenSSL tools installed that can reach the directory server, you can obtain the certificate by running:
The command output will typically show the server certificate first and the CA certificate second, both in PEM format. Into a text file, paste the CA certificate portion of the output that looks like:
Under LDAP CA certificate in the PEM format in the Replicated console, click the "Choose File" button and browse to the file you just created to select and upload it. Note that when you click Save, the Sysdig platform will restart. This is the only setting related to LDAP that requires a platform restart.
Note: For environments using self-signed certificates, the openssl command shown above will return only one certificate.
managerDn
Yes
The distinguished name of a user that the Sysdig platform can authenticate as via LDAP in order to perform further queries about the users attempting to login to the Sysdig platform. Example:
cn=Administrator,cn=Users,dc=example,dc=local
This setting is required, as the Sysdig platform does not support connection to servers via anonymous bind.
managerPassword
Yes
The password for the managerDn.
rootDn
No
The distinguished name for the point in the LDAP tree below which all search queries will begin. Example:
dc=example,dc=local
referral
No
Defines whether the Sysdig platform will chase referrals found in LDAP query responses. If not specified, this will be set to "IGNORE" in your configuration and referrals will not be chased. See the section below on Multi-Server Directories for more details on this option.
The following settings are in the optional loginFilter section:s
Setting
Required
Description
searchBase
Yes
A relative distinguished name (from the rootDn) below which queries about users should be performed. Example:
cn=Users
If specified as an empty string (""), the search will be performed across everything below the rootDn, in which case the rootDn setting must be configured.
Note that if the rootDn setting was not specified, the searchBase setting must provide a full distinguished name. Example:
cn=Users,dc=example,dc=local
searchFilter
No
An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify the user record. The marker token {0} represents where the username will appear when LDAP queries are constructed. An example that targets the attribute sAMAccountName in Active Directory:
While this setting is optional, if not specified, no users will be able to authenticate via LDAP.
To use the helper script, modify the env.sh to set the required
values for API_TOKEN and URL for your environment. Once set,
invoking login_config.sh with no options will print the current
configuration. If you were running Sysdig platform version 858 or older
and have just upgraded to version 1149 or newer, you will see your
migrated settings. Otherwise, the LDAP feature will start out disabled
("enableLdapAuthentication": false) and other configuration
settings will not be shown.
Using the guidance in the settings table above, modify the
settings_login_simple.json as necessary to allow for connectivity
and querying of users in your directory server. To apply the new LDAP
settings, invoke login_config.sh with the -s option and
specify the filename containing the JSON config, . If successful, the
applied configuration will be echoed back by the API.
Using the specific example settings_login_simple.json and the
minimal Active Directory configuration in the screenshot below, login to
the Sysdig platform would now be permitted for a user jdoe that
has distinguishedName:
CN=John Doe,CN=Users,DC=example,DC=local
To delete LDAP settings, invoke login_config.sh with the -d
option. This should be used with caution, as this will prevent all
LDAP users from being able to log in to the Sysdig platform!
The LDAP feature as it existed in version 858 and earlier included
optional additional settings that, when specified, ensured that
authenticated users were also members of one or more groups before
permitting them to login to the Sysdig platform. These settings are
documented here for the benefit of those who used these settings in the
past and have had their settings migrated to the newer API-based
configuration, where they become part of the **loginFilter **section.
See below for details on how to use the searchFilter instead to
achieve equivalent functionality.
For use with the login_config.sh helper script, an example
settings_login_group_deprecated.json is provided that can be
modified for your environment based on the table below. Example
command-lines are shown below the table.
Setting
Required
Description
groupSearchBase
No
A relative distinguished name (from the rootDn) below which queries about groups should be performed. Example:
ou=Planets
groupSearchFilter
No
An LDAP search filter (in RFC2254 format) that the Sysdig platform will use in constructing the query to identify a group to which the user must belong. An example that only permits users that are in the Mars group in Active Directory:
(&(cn=Mars)(objectclass=group))
If this setting is left blank, group membership is not required, and hence any user that successfully authenticates via LDAP using only username/password will be permitted to login to the Sysdig platform.
groupMembershipFilter
No
An LDAP search filter (in RFC2254 format) that the Sysdig platform will use to determine group membership. If no setting is specified, the following default filter is applied, which should work for most environments:
Using the specific example settings_login_group_deprecated.json
and the minimal Active Directory configuration in the screenshot below,
login to the Sysdig platform would be permitted for this user who
belongs to the Mars group.
But jdoe user who is not a member would be prevented from logging
in.
To simplify your configuration and avoid use of these deprecated
options, an equivalent configuration can be achieved by making the group
membership part of the searchFilter:
See the example settings_login_group.json for an updated
configuration that can be compared side-by-side with
settings_login_group_deprecated.json.
Multi-Server Directories
Data about your users that need to access the Sysdig platform may be
stored across many directory servers in your environment. As the Sysdig
platform is only able to query one LDAP server endpoint, you would need
to take extra steps to ensure successful authentication for such users.
The simplest approach to achieve this is to query against a Global
Catalog.
As the Global Catalog stores a copy of all Active Directory objects in a
forest, this provides a fast and convenient target for the Sysdig
platform to find all users that may need to authenticate. Since queries
against the Global Catalog are also performed via LDAP, you simply need
to ensure your LDAP configuration specifies the appropriate address and
TCP port for the Global Catalog, e.g. ldap://176.16.0.1:3268 for
cleartext LDAP or ldaps://172.16.0.1:3269 for LDAP over SSL. If querying
against a Global Catalog, the referral option of the Sysdig
platform’s LDAP configuration can remain at its default setting of
"IGNORE".
If a Global Catalog is not available, another approach is to leverage
referral
chasing.
Such chasing depends on the complex interplay of configuration settings,
DNS resolution, and network connectivity to multiple servers. If you
require this option, carefully read the tips in this section and
validate your configuration in a test environment before attempting its
use in production. Contact Sysdig support for assistance as necessary.
For our example configuration, we’ve added another Domain Controller to
our environment that holds users a separate set of users for the child
domain eu.example.local.
We’d like to permit login for a user “eurodude” in the child
domain. This user has distinguishedName:
CN=Euro Dude,CN=Users,DC=eu,DC=example,DC=local
In the example configuration settings_login_referral_follow.json
shown below, the Sysdig platform still begins its LDAP queries at the
same top-level server target. However, the referral option is set
to "FOLLOW", which will cause the Sysdig platform to perform
subsequent queries if a query returns one or more referrals.
Note also how in this case the rootDn option is left unspecified
and the searchBase is set to the distinguished name of the
top-level domain. This is necessary to ensure the scope of the chased
referral queries will include the child domain. If **rootDn **and
searchBase had been left as they were set in the
settings_login_simple.json example, the initial query would have
been targeted only within cn=Users,dc=example,dc=local and hence
the referral would never have been returned by the top-level server.
Note these other caveats of referral chasing in the Sysdig platform:
Referrals may only be successfully chased to child domains. If
referrals point to parallel domains (e.g. for our example,
dc=adjacent,dc=local) the queries will not succeed and users
stored in the directory servers for such domains will not be able to
authenticate.
The LDAP library used by the Sysdig platform does not log
information about each referral it attempts to chase. Therefore, if
you enable referral chasing, it is important that you understand the
server targets that may be chased in your environment and ensure the
network connectivity (routing/firewalls) will permit the Sysdig
platform to query these server targets. If LDAP queries are failing
due to a network connectivity issue, this will typically be
accompanied by delays during Sysdig user logins of approximately 30
seconds followed by a login failure with an HTTP 504 error
message shown in the login screen. If this occurs, contact Sysdig
support for assistance.
Testing User Login
To test the login configuration, the “super” Admin
user can confirm if a
particular user would be permitted to login given current LDAP login
connection settings. To do this, perform an HTTP GET to the API
endpoint /api/admin/ldap/settings/verify/USERNAME . A verify_user.sh
helper script is provided to easily perform this. If invoked with the
-u option and a username, and the user’s login would be
successful, it will return the user’s information from the directory.
If the user would not be able to login, an error message will be
returned.
# ./verify_user.sh -u nothereCould not verify user "nothere". Check LDAP login config settings and/or system log.
Note that if LDAP authentication is disabled this method for testing
user login is not available.
Creating LDAP Users Before They Login
The default behavior of the LDAP feature is to create a new record in
the Sysdig user database when a user authenticates successfully via LDAP
for the first time. However, it may be desirable to add such user
records in advance of their first login, such as if you wish to use
automation to change user permissions, assign team membership, or
pre-populate Dashboard/Alert configurations. A create_user.sh
helper script is available in the sysdig-cloud-scripts
repository to create such user records via the API. This script can also
be used to enable/disable this functionality in the Sysdig platform. See
the
README
for details.
Additional details regarding this type of user creation in conjunction
with LDAP authentication:
This method allows creation of any username, even if it doesn’t
currently exist in the directory that is queried via LDAP.
When LDAP authentication is enabled, such users can be created with
a simple username (e.g. jdoe ) or with an email-style postfix
(as is typical for non-LDAP Sysdig user, e.g.
jdoe@example.com ). In this latter case only the username
portion ( jdoe ) is used when the Sysdig platform is
performing an LDAP query during attempted login.
While the password must be included in the config you
POST to create the user, it is not used by the Sysdig platform
when LDAP is enabled, as authentication will always be performed via
LDAP. For this same reason, if a user has been created in this way,
they will not be able to login unless there is a matching user in
the directory that is queried via LDAP.
The firstName and lastName values as specified in the
example are optional and independent from any equivalent name
settings in the directory that is queried via LDAP.
Limitations and Caveats
LDAP support has been tested with Active Directory in Windows Server
2012 R2. It may work with AD versions that ship with other versions
of Windows, or other directory servers that use the LDAP protocol.
If you are intending to use LDAP with something other than Active
Directory, please contact Sysdig Support.
The LDAP feature is only present in Sysdig software platform
installs (not the SaaS version).
Only one LDAP config can exist per deployment (i.e. the platform can
only query one directory server endpoint).
Because the Sysdig software platform is based on the same technology
as the SaaS-based Sysdig service, it theoretically supports the
configuration of multiple “customers” using the same install.
However, the multi-customer option is not supported when the LDAP
feature is enabled.
When LDAP authentication is enabled, adding users via email
“invites” is not possible.
LDAP authentication for directory usernames that begin or end with a
space character (e.g. " jdoe" or "jdoe " ) are not
supported.
Configuration entries that contain special characters (for instance,
a managerPassword that contains a backslash character) are
supported, but note that you will need to perform proper JSON
escaping in the configuration you POST to the API. If you
attempt to post invalid JSON, the helper scripts will return an
error message. If this occurs, you can use tools such as
JSONLint to narrow down the source of the
problem and/or JSON String
Escape to learn how
to properly escape your text.
The LDAP feature does not attempt any ongoing “sync” back from the
Sysdig platform user database to the directory server. Note how this
impacts the following:
If a user is deleted from the directory server, their user
record will remain in the Sysdig user database until a Sysdig
Admin deletes it. Of course, that user will not be able to login
since they will no longer be able to authenticate successfully
via LDAP.
If an Admin deletes a user from the Sysdig user database, but
the user can still authenticate successfully via LDAP, their
Sysdig user record will be recreated if they login again via
LDAP.
If a person’s username should change in the directory server
(e.g. the value for sAMAccountName in our examples above),
the next time they login, a new user record will be created for
them in the Sysdig user database. Settings they previously had
in the Sysdig platform such as Admin rights and Alerts/Dashboard
configurations will not be present for this recreated user.
Other LDAP-centric functionality that is not currently supported
(not an exhaustive list):
Mapping a user in the directory server to the Sysdig “super”
Admin (such as to
avoid the need to configure the this “super” Admin user).
Session expiry based on configuration in the directory server
(such as to set a user account to only be valid until a certain
date).
Login policies based on configuration in the directory server
(such as to restrict login to certain hours).
User timeout functionality (such as to remove a user from the
Sysdig user database if they have not logged in for a certain
amount of time).
7.4.3 - Mapping LDAP Users to Sysdig Teams
LDAP
support in the Sysdig on-premises platform allows user authentication
via credentials stored in your own directory server. Once LDAP
authentication is
configured, the optional
mapping feature can be used to map groups of users from your directory
to Sysdig teams.
How It Works
After basic LDAP
integration, records in the
Sysdig user database are automatically created when users successfully
authenticate via LDAP the first time. Then a Sysdig Admin could
add/remove them from Sysdig teams and change their roles in those teams.
To eliminate this manual workflow, LDAP mapping provides a
policy-driven, automated way to use relevant information from your
directory to affect the lifecycle of such users/teams. This is achieved
by creating LDAP-mappingrules that identify groups of users in
your directory and port them to Sysdig’s database, specifying teams in
which they should be members and their roles in those teams.
LDAP-mapping rules trigger the automatic creation of such users and
teams in the Sysdig platform database, and ongoing synchronization
ensures the Sysdig platform database always reflects the current state
of your directory, such as when users are deleted from your directory or
are no longer members of a group.
Process Overview
Configure Basic LDAP.
Note that in the process, you modify env.sh with token and
authentication credentials.
The group of mapped users found via the searchFilter will be made members of all these teams. The named team will be auto-created the first time synchronization is performed for a mapping rule that references it.
Example:
"teams": [
"Web Devs",
"DBAs"
}
teamRole
Defines the Roles that will be assigned to users who are mapped to the Sysdig teams defined in this rule.
The LDAP attribute containing the username for users that may be auto-created in the Sysdig database as a result of this rule.
If LDAP authentication is enabled, shorter non-email-based usernames (such as typically found in the sAMAccountName attribute of Active Directory) may be used.
Email-based usernames (such as mail in Active Directory) are also supported.
NOTE: If using LDAP/SAML Hybrid Authentication, you should use an email-based attribute for this setting to ensure successful matching against email-based usernames authenticated via SAML.
ldapTeamMapping Parameters
The Settings below define when and how synchronization is performed
between your directory and the Sysdig database:
LDAP Sync Process Settings
Setting
Required
Description
dryRun
No
Options:truefalse
If set to true, the configuration will be applied, but any subsequent sync will perform the LDAP query and update the report/log without actually performing the changes.
If not specified in the config, dryRun is set to false.
The sample mapping configurations set it to true to help you avoid mistakes while getting acquainted with configuring LDAP mappings. A good workflow would be
- set dryRun to true when iterating new config changes,
- check the sync report to see if it achieves the desired state,
- apply the config again with dryRun set to false to trigger the actual changes to users/teams in the Sysdig database during the next sync.
maxAllowedMappedUsers
No
Options: A number 0 - 1000. Default = 100.
If specified, any sync that would result in greater than this number of LDAP-mapped users in the Sysdig database will be treated as a dry run. This is to protect against unintended creation of excess user counts as a result of syntax errors in filters. If not specified, will always be set to 100.
syncIntervalMinutes
No
Default value: 10 minutes
Set to 0 to disable sync completely
Defines how often the Sysdig platform will perform the queries defined in the mapping rules against your directory to ensure all user/team settings in the Sysdig database are current with recent updates to your directory.
syncTimeoutSeconds
No
Default value: 120 seconds
The maximum number of seconds to permit each LDAP synchronization operation to run. If the running time of a sync exceeds this amount, the backend log of the Sysdig platform will record an exception and all changes from the attempted sync will be rolled back.
teamDefinitions
Yes
An array that defines additional configurations for each Team referenced in the set of rules in the ldapTeamMapping array.
At minimum, this array must reference each Team by name in an element of the array, along with a Scope By setting (set to either "host" or "container") for that Team. Example:
A number, automatically generated. User cannot set.
name
Name of the team
Sysdig team name to be used (self-defined)
show
The scope to be shown
Options:
"host" or "container"
"container" if the team is based on scope of labels from containers, "host" if the team is based on scope of labels from hosts
products
Sysdig Monitor or Sysdig Secure
Options:
["SDC"] for Monitor
["SDS"] for Secure
Note that even though this field is an array, you CANNOT assign something like ["SDC", "SDS"]. If you want to sync both Monitor and Secure teams; you need to set them up separately
Apply the LDAP configuration settings the JSON file using the
mapping.config.sh.
For example:
mapping_config.sh -s settings_mapping_simple.json
The following sections provide examples for applying settings, forcing
synchronization, deleting settings, and reporting status using
mapping_config.sh.
Once set, invoking mapping_config.sh with no options will print the
current configuration. If you haven’t yet configured any mapping rules,
the config shown will start out empty:
To apply new mapping settings, invoke mapping_config.sh with the
-s option and specify the filename containing the JSON config. If
successful, the applied configuration will be echoed back by the API.
To see the mapped users/teams state and changes/problems from the most
recent sync operation, view the report using the -r option, which
performs a GET on the /api/admin/ldap/syncReport endpoint.
This same report information is in the system log for every sync
operation.
(Note that the Warning in this report is discussed in the Error
Messages
section below.)
The sample settings_mapping_simple.json illustrates some common use
cases.
Consider a minimal Active Directory with the following users:
sAMAccount
Distinguished Name
msmith
CN=Mary Smith,CN=Users,DC=example,DC=local
mpeterson
CN=Mary Peterson,CN=Users,DC=example,DC=local
jdoe
CN=John Doe,CN=Users,DC=example,DC=local
Presume the groups Sysdig Viewers and Sysdig Editors are defined in
the Active Directory with the listed memberships:
Mapping Users to Teams 1:1
The first mapping rule shows a simple 1-to-1 mapping of all the users in
the Sysdig Viewers group in our directory to a Sysdig team called
Viewers in which these users will have Read-only permission.
The second mapping rule illustrates how to map the Sysdig Editors
group of users to more than one Sysdig team (Editors1 and Editors2),
granting Read/Write access in both teams.
The third and fourth rules illustrate the flexibility of how groups are
handled by the Sysdig LDAP Mapping feature.
The third rule shows how users targeted by a mapping rule can ultimately
be anything specified by a searchFilter. In this contrived example,
we’ve targeted all users with the first name “Mary” and mapped them to a
Sysdig team called “Mixed” where they will have Read/Write permissions.
The fourth rule builds on the third, showing how to combine multiple
rules to target different groups of users from the directory and
potentially assign them different permissions in the same Sysdig team.
Here we target our single “John Doe” user and also map him to the
“Mixed” team, but with Read-Only access.
As the examples show, the LDAP mapping configuration is flexible and
powerful. However, misconfigurations (such as mistakes in filter syntax)
may trigger the unintentional creation/deletion of excess user and/or
team data. It is recommended to use the dryRun option extensively,
particularly when first becoming familiar with the feature. The
following notes about the constraints and side-effects of LDAP mapping
should also be considered.
During sync, if a user from the directory matches on a mapping rule
and does not yet exist in the Sysdig user database, it will be
auto-created in the Sysdig database at that time. These will start
out as non-Admin users, but could be promoted to Admin by a Sysdig
Admin once their record has been auto-created.
As with other Sysdig teams, all Sysdig Admin users will
automatically be members of all LDAP-mapped teams.
During sync, if a mapped team specified in a rule and
teamDefinitions array does not yet exist in the Sysdig
database, it will be auto-created in the Sysdig database at that
time. If a sync would result in the creation of a team that has the
same name as a non-mapped team that already exists (i.e. one that
was created previously by a Sysdig Admin), the mapped team will not
be created and no mapping of users to that team will be performed.
This will also be noted in the system log.
If an LDAP-mapped user is no longer a match in a particular
LDAP-mapped team, they will be removed from that team. Any
team-specific data attached to that user (e.g. Dashboards) will
not be deleted.
Dashboards that were Shared by that user within the team will
remain visible to other team members.
Personal Dashboards for that user will effectively be hidden,
though if the user is mapped to the team again, they will be
visible to that user again.
An LDAP-mapped user that no longer is a match on their last
remaining LDAP-mapped team will be moved to the Default Team. This
is to ensure against accidental deletion of the user’s data in the
event of configuration mistakes. If desired, a Sysdig Admin can
perform a final delete of the user record through the UI or API,
which would result in deletion of all data attached to that user in
all teams.
If a user is mapped to the same team via multiple rules, and the
teamRole settings differ between the rules, the most generous
setting will apply (i.e. ROLE_TEAM_EDIT).
Membership of LDAP-mapped teams is controlled exclusively via
mapping rules. The Sysdig web UI will prevent membership changes in
such teams.
The searchFilter entries in LDAP mapping rules are independent
from the base LDAP loginFilter that is used for
authentication. It is therefore possible for LDAP mapping rules to
trigger creation of Sysdig user records for users that may not yet
be able to login to the Sysdig platform.
No changes made within the Sysdig database will result in any
modifications to the directory being queried via LDAP (i.e. sync is
a “one-way” operation from directory to the Sysdig database).
See General LDAP
Tipsfor
more guidance to assist with debugging or perfecting your LDAP
configuration.
"warnings": ["LDAP mapping LdapMapping(ldapFilterSettings=LdapFilterSettings(searchBase=cn=Users, searchFilter=(&(objectClass=organizationalPerson)(memberOf=CN=Sysdig Editors,CN=Users,DC=example,DC=local)(sAMAccountName=*)), groupSearchBase=null, groupSearchFilter=null, groupMembershipFilter=null), teams=[Editors1, Editors2], teamRole=ROLE_TEAM_EDIT, usernameAttribute=mail) matched 2 entities that has no requested username attribute"]
This was because two of the user records that matched
our searchFilter (that is, they were members of the “Sysdig Editors”
group in Active Directory) each had an empty mail attribute in AD. The
LDAP Mapping configuration would have ordinarily resulted in the
creation of these user records in the Sysdig platform user database, but
since the usernameAttribute setting pointed the Sysdig platform at
these empty mail values, the error message alerts us to this fact.
If these sort of empty attributes are typical for your AD environment,
the error message can be ignored.
Similarly, if such attributes were not unique (i.e., multiple Mapped
users were found to have the same email address), the error message
would be:
"warnings": ["Duplicate username founds. They will be ignored in mapping: [duplicates@example.local]"]
7.4.4 - LDAP/SAML Hybrid Authentication
This is an advanced option wherein LDAP
Mapping is used to trigger
the creation of user records in Sysdig, but authentication of those
users is actually performed via
SAML (with LDAP-based
authentication disabled). In this configuration, if a user successfully
authenticates via SAML, and the platform finds a user record with a
matching email address in the Sysdig platform, they will be permitted to
log in.
The process involves:
Enable SAML
login
and disable automatic user creation via SAML.
Follow the instructions for SAML (On-Prem)
configuration for your
IdP. Use the UI in Sysidg Platform version 3.5.0, or the
script-based
option for earlier versions.
To ensure that user records are created solely via LDAP mapping,
disable user-creation-on-demand and (optionally) password
authentication.
UI-based option: Use the toggles in the UI to disable “create
user on login” and “user name and password login.”
With this configuration, if a user successfully logs in via SAML but
does not have an existing username/email record in the Sysdig
database, they will receive an error message.
Enable LDAP User Creation using LDAP Mapping
Configure the settings_mapping_hybrid.json file.
The only difference between the _simple and the _hybrid files is
the userAttributeName value. In _hybrid, this is set to email,
because SAML-derived usernames in the Sysdig platform area always
based on email address.
Apply the settings using the mapping_config.sh script:
If you want to ensure your user records are derived only from LDAP
hybrid mapping, then use the -d option with the api_user_creation.sh
script, as described in the
Readme.
Optional: Disable Password Login
You may have pre-existing records in your Sysdig platform database for
users who have previously authenticated via simple email/password. If
you want to prevent such logins and ensure 100% authentication via SAML,
you can disable password login.
In this configuration, only the “super” Admin can still login via
email/password.
When all configurations are complete, log in to the Settings in the
Sysdig user interface and Select SAML for
SSO,
if it is not already selected.
7.5 - Disable Password Authentication
Sysdig Platform supports disabling password-based authentication on both
SaaS and on-prem deployments. As an administrator (super administrator
for on-prem), you can use an API to achieve it. This configuration is
applicable to those who use single sign-on.
GET https://<URL-installation>/api/admin/auth/settings
Replace <URL-installation> with the URL of your on-prem
deployment.
Retrieve the specific settings associated with the SSO setup. In a
typical scenario, only one IDP exists per deployment.
GET https://<URL-installation>/api/auth/settings/{id}
The setting is displayed in a JSON file.
In the JSON file, change the following from false to true:
settings/forbidPasswordLogin:True
Update the setting with a request to the same URL with the same
JSON, with the changed parameter. URL depends on the type of
deployment.
PUT https://app.sysdigcloud.com/api/admin/auth/settings/{id}
Migrating from the ConfigMap Method
Previously, the sysdigcloud.restrict.password.login parameter in the
Kubernetes ConfigMap has been used to disable password authentication.
After installing 3.2.0, deployments utilizing the
sysdigcloud.restrict.password.login settings will be automatically
migrated to use the new settings.
7.6 - Configure Split DNS
Split Domain Name System (Split DNS) is a configuration in which two DNS
servers (sub-domains) are created for the same domain, one for the
internal network and the other for the external, as a means to tighten
the security. In this setting, internal hosts are directed to an
internal domain name server and external hosts are directed to an
external domain name server for name resolution.
In environments where Sysdig Platform is available through an Identity
Provider (IDP) on two DNS records (split DNS), one set of users may not
be able to log in to Sysdig, as the IDP redirects them only to a single
DNS. In order to redirect users to the original DNS name they have
requested, configure your deployment as given below.
Prerequisites
You have the administrator privileges to configure Split DNS.
Sysdig Platform is installed on-premises.
Sysdig Platform is available on two or more DNS names.
Users are accessing the Sysdig Platform by using two DNS names.
Users are required to be redirected to the original DNS name.
Supported IDP Protocols
SAML
OpenID Connect
Sysdig Platform Configuration
The topic assumes the request flows through the following setup: Browser
> Application Load Balancer (optional) > Kubernetes Ingress
Controller > Sysdig NGINX > Sysdig API.
Configure the Ingress Controller.
Open the Ingress Controller.
kubectl get ingress -o yaml > ingress.yaml
Edit the ingress.yaml file as follows:
apiVersion:extensions/v1beta1kind:Ingressmetadata:annotations:ingress.kubernetes.io/affinity:cookieingress.kubernetes.io/session-cookie-name:INGRESSCOOKIEAPIkubernetes.io/ingress.class:haproxycreationTimestamp:"2019-12-23T14:45:07Z"generation:1labels:app.kubernetes.io/managed-by:ingress-configapp.kubernetes.io/name:ingress-configapp.kubernetes.io/part-of:sysdigcloudrole:ingress-configtier:infraname:sysdigcloud-api-ingressnamespace:sysdigcloudresourceVersion:"156675"selfLink:/apis/extensions/v1beta1/namespaces/sysdigcloud/ingresses/sysdigcloud-api-ingressuid:891a0a46-ce64-41e0-906b-31627306a844spec:rules:- host:<REPLACE WITH EXTERNAL DNS FQDN>http:paths:- backend:serviceName:sysdigcloud-apiservicePort:8080path:/- backend:serviceName:sysdigcloud-scanning-apiservicePort:80path:/api/scanning- host:<REPLACE WITH INTERNAL DNS FQDN>http:paths:- backend:serviceName:sysdigcloud-apiservicePort:8080path:/- backend:serviceName:sysdigcloud-scanning-apiservicePort:80path:/api/scanningtls:- hosts:- <REPLACE WITH EXTERNAL DNS FQDN>- <REPLACE WITH INTERNAL DNS FQDN>secretName:sysdigcloud-ssl-secretstatus:loadBalancer:ingress:- {}
Apply the changes:
kubectl apply -f ingress.yaml
Configure Nginx in the Kubernetes API pod.
Open the configuration file corresponding to the sysdig-api
deployment.
Add the following snippet to the Nginx environment variables
section:
- name:NGINX_NOT_ON_EDGEvalue:"true"
Apply the changes.
Ensure that the following snippet is added to the Ngnix
configuration file at /etc/nginx/conf.d/api.conf:
