Skip to main content
Version: v4.5

Install a sidecar using a Linux-based OS

Cyral sidecars are usually deployed using an automation service like Cloudformation, Helm, or Terraform, but you can also install them manually on a Linux instance or as a container. This document explains the manual steps to install and run Cyral's local sidecar package.

Terminology​

TermDefinition
Control plane URLThis is the URL for your Cyral control plane such as mycompany.cyral.com
API access keyThis is an account you create in the Cyral control plane that can be used to create additional sidecars. The API access key consists of a client credential ID and a client credential secret. When creating an API access key in the Cyral control plane, the account must be assigned at least the role Modify Sidecars and Repositories.
Sidecar IDWhen creating a new sidecar, the Cyral control plane will assign a unique identifier for the sidecar
Sidecar client IDUnique identifier used to authenticate the sidecar instance to the Cyral control plane
Sidecar client secretUnique secret used to authenticate the sidecar instance to the Cyral control plane

Sidecar server requirements​

Operating System​

These instructions have been fully tested on the following operating systems:

  • Ubuntu 20.04.2 LTS
  • RHEL 8.3.0
  • CentOS Linux release 8.3.2011
  • Oracle Linux 8

Permissions​

You will either need to be root or have sudo permissions on the target machine in order to run this install script.

Cyral sidecar Installer​

Download the Cyral sidecar installer, install-linux.sh, from the Cyral quickstart linux repository. You can access the file directly: install-linux.sh

Control plane access requirements​

In order to create a new sidecar and generate the secrets for the forward proxy, you will need to make sure that users have at least the following permissions:

  • Modify Sidecars and Repositories

Sidecar installation​

Get the sidecar installation script​

  1. Log in to your Cyral control plane as an administrator

  2. Go to Sidecars

  3. Click on the ➕ (plus sign) to create a new sidecar

  4. Choose Deploy a sidecar using a Linux package

  5. Click the Generate button

  6. Enter a Sidecar Name for the sidecar. This is the name your administrators will use when they associate the sidecar with repositories.

  7. Click the Generate button. The window will display a set of environment variable settings. Keep this window open.

Set variables​

Next you will log in to the machine where you'll install the sidecar and set the required environment variables.

info

A note on running multiple nodes of one sidecar, or multiple sidecars:

The installation steps on this page should be performed on any host that will be running a sidecar. Take care to note the difference between multiple instances of a sidecar vs. multiple sidecars:

  • If multiple hosts will be configured as instances of the same sidecar, then repeat the installation procedure using the settings you got in the steps above.

  • If you are planning to have each host operate as an individual sidecar (each with its own configuration in the Cyral control plane), then you will also need to repeat the steps above to get a unique Sidecar ID, Client ID, and Client Secret for each host.

  1. Open a terminal window in the location where you will install the sidecar.

    • Assume the role of super user (sudo su on Ubuntu, or su root on Debian)
    • If needed, move the sidecar installation script to that location.

  2. Copy and paste the export commands from the Create sidecar window. This sets the environment variables such as CYRAL_SIDECAR_ID.

    Below, we list the required sidecar parameters. Set these as needed for your deployment:

    • CYRAL_SIDECAR_ID: Required. Unique id of this sidecar. Provided by the Create sidecar window.
    • CYRAL_SIDECAR_CLIENT_ID: Required. Provided by the Create sidecar window.
    • CYRAL_SIDECAR_CLIENT_SECRET: Required. Secret value used to prove this sidecar's identity in control plane communication. Provided by the Create sidecar window.
    • CYRAL_SIDECAR_VERSION: Required. The version number of this Cyral sidecar.
    • CYRAL_CONTROL_PLANE: Required. URL of the Cyral control plane.

Install the sidecar​

  1. Copy the Cyral installation script to the server that will become a sidecar.

  2. Make the install-linux.sh executable:

    chmod +x install-linux.sh

  3. Install the sidecar by running the installation script:

    $ sudo ./install-linux.sh 
    Getting access to the CP
    Downloading the binaries
    % Total  % Received % Xferd [...]  Current Speed
    100        305M       100   [...]   952k
    Binaries were downloaded correctly.
    Doing a Red Hat Install
    Running Post Install Tasks
    Updating Configuration Files
    sed: can't read /etc/cyral/cyral-dremio-wire/config.yaml: No such file or directory
    sed: can't read /etc/cyral/cyral-mongodb-wire/config.yaml: No such file or directory
    sed: can't read /etc/cyral/cyral-dynamodb-wire/config.yaml: No such file or directory

  4. The installer gives you the option to disable the sidecar services you don't want to use. For each available repository type, you'll see a prompt like the following:

    Do you want to disable the cyral-mysql-wire? (yes/no) [no]:

    Type yes to disable the repository type, or no to keep it available, and hit Enter. 

    Asking for services to disable
    Do you want to disable the cyral-mongodb-wire? (yes/no) [no]:
    [...]
    Do you want to disable the cyral-s3-wire? (yes/no) [no]:
    Restaring Cyral Services...
    Restarting: cyral-alerter
    Restarting: cyral-authenticator
    Restarting: cyral-dispatcher
    Restarting: cyral-forward-proxy
    Restarting: cyral-mysql-wire
    Restarting: cyral-oracle-wire
    Restarting: cyral-pg-wire
    Restarting: cyral-push-client
    Restarting: cyral-sidecar-exporter
    Restarting: cyral-sqlserver-wire

Your sidecar should now be running and reachable. See the next section for help assessing the health of your sidecar.

Check your installation​

Perform the following steps to confirm your sidecar has been installed correctly.

Check connectivity​

Run a TCP health check probe on port 8888 of the sidecar host.

Check the sidecar's status​

  1. Log in to your control plane

  2. Navigate to the Sidecars link on the left menu

  3. Check the sidecar: Identify the sidecar you just installed from the list and open it.

    Confirm that the sidecar is shown in the list with a green checkmark. If a green checkmark does not appear, check the sidecar's metrics and logs.

  4. Check each sidecar instance: Click on the sidecar's name and go to the Instances tab.

    Confirm that the sidecar instance is shown with a green checkmark. If a green checkmark does not appear, check the sidecar's metrics and logs.

note

Each sidecar instance can be identified by its IP address. Depending on the local IP address of the server, this might be a private IP address.

Track a repository​

  1. Track a repository to the Cyral control plane, including any identity provider integrations and access rules. (See the quickstart section for more information.)
  2. Assign the repository to the Cyral sidecar.
  3. Configure your application to connect through the Cyral sidecar.

Configure the sidecar for SSO​

Some environments might require the use of environment variables to store native credentials. Additional details regarding setting up native credentials for a repository can be found here.

When using environment variables to store native credentials on the local server, you will need to supply the variable(s) to the Cyral Authenticator service (cyral-authenticator). Perform the following steps to make sure the cyral-authenticator is configured to use these credentials.

  1. SSH to the sidecar.
  2. Edit the environment variables for the Cyral authenticator server.
    sudo vi /etc/default/cyral-authenticator
  3. Add a new line that contains the secret credentials. In the below example, the new line containing the credentials is in blue text. The name of the environment variable should match the name configured in the Cyral control plane.
    CYRAL_AUTHENTICATOR_CONTROLPLANE_HOST=
    CYRAL_AUTHENTICATOR_CONTROLPLANE_PORT=
    CYRAL_AUTHENTICATOR_WRAPPER_NAME=
    CYRAL_DBSECRETS_REPO_ADMIN='tk"username":"admin", "password": "Some-S3cure_Pa$$word!"tkend'
  4. Save the file.
  5. Restart the cyral-authenticator to load the new changes.
    sudo systemctl restart cyral-authenticator

Troubleshooting​

Check sidecar health in the Cyral control plane UI as follows:

Health monitoring information​

This section provides useful information regarding monitoring Cyral services.

Metrics​

Each Cyral service that is deployed by the installer generates various metrics in Prometheus format. Details regarding these metrics can be found in the metrics specification.

Each of the deployed services exposes a HTTP service that provides metrics on the /metrics path.

Below is an example of querying the metrics service associated with the dispatcher service:

# curl localhost:9015/metrics

# HELP cyral_bypass_wire_count The total count of connection bypassed to repository directly grouped by bypass_reason.

# TYPE cyral_bypass_wire_count counter

cyral_bypass_wire_count{asg_instance="i-abc123",bypass_reason="dial_failed",repo_id="repo123",repo_name="Oracle-DB-1",repo_type="oracle",service="dispatcher",service_type="",sidecar_id="sidecar1234",sidecar_name="aws-cft",sidecar_version="unknown",start_timestamp="1643723971633447036"} 0

cyral_bypass_wire_count{asg_instance="i-abc123",bypass_reason="dial_failed",repo_id="repo456",repo_name="sql2019-srss",repo_type="sqlserver",service="dispatcher",service_type="",sidecar_id="sidecar1234",sidecar_name="aws-cft",sidecar_version="unknown",start_timestamp="1643723971633447036"} 0

cyral_bypass_wire_count{asg_instance="i-abc123",bypass_reason="dial_failed",repo_id="repo789",repo_name="sql2016-srss",repo_type="sqlserver",service="dispatcher",service_type="",sidecar_id="sidecar1234",sidecar_name="aws-cft",sidecar_version="unknown",start_timestamp="1643723971633447036"} 0

cyral_bypass_wire_count{asg_instance="i-abc123",bypass_reason="dial_failed",repo_id="repo101112",repo_name="Snowflake",repo_type="snowflake",service="dispatcher",service_type="",sidecar_id="sidecar1234",sidecar_name="aws-cft",sidecar_version="unknown",start_timestamp="1643723971633447036"} 0

Similar metrics are available for each service. The below table provides a subset of services that might be present and their corresponding metrics port:

Cyral Service PortMetrics Port
cyral-dispatcherTCP/9015
cyral-oracle-wireTCP/9032
cyral-sqlserver-wireTCP/9022
cyral-sidecar-exporterTCP/9023
cyral-dremio-wireTCP/9019
cyral-mysql-wireTCP/9018
cyral-pg-wireTCP/9016
cyral-s3-wireTCP/9024
cyral-mongodb-wireTCP/9017
cyral-rest-wireTCP/9036
cyral-dynamodb-wireTCP/9038

Process monitoring​

In addition to metrics monitoring, you may also leverage a local service that checks for the existence of expected processes. In order to help you determine which processes to monitor, the below table defines the various services that are installed by this installer. The table provides a brief description of each service along with whether it is critical to the proper operation of the sidecar:

Cyral Service NameCriticalDescription
cyral-forward-proxyYes1Used to establish connectivity from the sidecar to the Cyral control plane.
cyral-dispatcherYesLayer 4 service that handles connections through the sidecar for clients connecting to the database.
cyral-certificate-managerYesThis service renders TLS certificates to cyral-dispatcher.
cyral-alerterNoThis service catalogs and sends notifications for alert-worthy events.
cyral-mysql-wireYesLayer 7 service that provides inspection of MySQL specific queries and commands.
cyral-oracle-wireYes2Layer 7 service that provides inspection of Oracle specific queries and commands.
cyral-authenticatorNo3This service talks to identity and MFA providers on behalf of other Cyral services.
cyral-pg-wireYes2Layer 7 service that provides inspection of Postgres specific queries and commands.
cyral-sqlserver-wireYes2Layer 7 service that provides inspection of SQL Server specific queries and commands.
cyral-sidecar-exporterNoExports sidecar's information, like its endpoint, cloud, region, sidecar version, etc…
cyral-push-clientNoService that sends metrics and other information to the Cyral control plane.
cyral-dremio-wireYes2Layer 7 service that provides inspection of Dremio specific queries and commands.
cyral-s3-wireYes2Layer 7 service that provides inspection of S3 specific queries and commands.
cyral-mongodb-wireYes2Layer 7 service that provides inspection of Mongo DB specific queries and commands.
cyral-rest-wireYes2Layer 7 service that provides inspection of REST API specific queries and commands.
cyral-dynamodb-wireYes2Layer 7 service that provides inspection of Dynamo DB specific queries and commands.

Footnotes:

  1. This service is not critical for the proper operation of the sidecar and its ability to support connections to databases. This service is required for all other components to communicate with the Cyral control plane for configuration updates.

  2. This service is critical for the proper logging and policy enforcement on the sidecar if the respective repo is added to the sidecar.

  3. If you integrate with an identity provider such as Okta, Azure, GSuite, or similar, for authenticating users through the sidecar, then this service would become critical for this purpose.