Get Started Sign In

Cyral Sidecar Deployment on a Linux Host

Cyral sidecars are usually deployed using an automation service like Cloudformation, Helm, or Terraform, but you can also install it manually on a Linux instance. Follow the steps below to install the sidecar manually.


This document walks you through the steps required to get Cyral's local sidecar package installed and running in order to protect a data repository.





Control plane URL

This is the URL for the customer’s Cyral control plane such as

Service account

This is an account the customer creates in the Cyral control plane that can be used to create additional sidecars. The service account consists of a service account ID and service account secret. When creating a Service Account in the Cyral control plane, the account must be assigned at least the role Modify Sidecars and Repositories.

Sidecar ID

When creating a new sidecar, the Cyral control plane will assign a unique identifier for the sidecar

Sidecar client ID

Unique identifier used to authenticate the sidecar instance to the Cyral control plane

Sidecar client secret

Unique 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


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

Cyral Packages

  • cyral-sidecar-<VERSION>.rpm or cyral-sidecar-<VERSION>.deb

Cyral Installer


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

Installation steps

Generate a secret for the sidecar

Tip! This step will only need to be performed once per sidecar. If you are installing new instances of the same sidecar, you will not need to perform these steps. You can simply reuse the sidecar_id and secrets generated during these steps.

Note: These instructions explain how to add a sidecar and generate the secrets via the Cyral control plane’s web UI. In order to do this via API, refer to the Generate a Secret for the Sidecar section within the API Calls and Examples section of this document.

In order to have the sidecar call home properly, you will need to provide it with credentials that it can use to contact the Cyral control plane. The below steps will guide you through generating the needed credentials.

  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 Deploying a sidecar using a custom template

  5. Click the Generate button

  6. Enter a name for the sidecar

  7. Click the Generate button

  8. On the resulting Generate private key pair screen, make a note of the Sidecar ID as this is needed for configuring the deployed sidecars.

  9. Once you have recorded the Sidecar ID, click Done.

  10. Click the Back button to return to the list of sidecars

  11. Click on the sidecar that you just created

  12. Click on the Client Secrets

  13. Click the + (plus sign) to generate a new secret

  14. On the resulting New Client Secret Generated page, make a note of the Client ID and Client Secret as these are needed for configuring the deployed sidecars.

  15. Once you have recorded the Client ID and Client Secret, click the Done button.

Installing the sidecar locally using a package

These steps should be performed on any host that will be running a sidecar. If multiple hosts will be configured as instances of the same sidecar, then repeat these steps using the same Sidecar ID, Client ID, and Client Secret obtained above. 

If you are planning to have each host operate as an individual sidecar with separate configurations in the Cyral control plane, then you will also need to perform the steps above to obtain separate Sidecar ID, Client ID, and Client Secret for each host.

  1. Copy the Cyral package(s) and installer over to the server that will become a sidecar

  2. SSH to the new server

  3. Edit the using a text editor like vi


  1. Modify the global variables at the top of the installer and add the values shown below:


Value to use


You Cyral control plane URL like


Sidecar ID from the steps above


Client ID from the steps above


Client Secret from the steps above


<VERSION> from the package version : cyral-sidecar-<VERSION>.rpm

Below is an example:

# Our Global Variables that we'll need for the install







  1. Save your changes to the

  2. Make the executable:

chmod +x

  1. Run the installer to install the sidecar

$ sudo ./ –local_package=./cyral-sidecar-v2.30.1.rpm

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-rest-wire/config.yaml: No such file or directory

sed: can't read /etc/cyral/cyral-s3-wire/config.yaml: No such file or directory

sed: can't read /etc/cyral/cyral-rest-wire/config.yaml: No such file or directory

sed: can't read /etc/cyral/cyral-s3-wire/config.yaml: No such file or directory

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


Validation steps

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

  1. Log in to your control plane

  2. Navigate to the Sidecars link on the left menu

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

Note! A validation step here is to confirm that the sidecar is showing with a green checkmark. See the Troubleshooting section if the sidecar is not green.

  1. Click on the sidecar name and go to the Instances tab to confirm the new sidecar is showing with a green checkmark.

Note! The new instance should be identified by its IP address. This could be a private IP address depending upon the local IP of the server.

Configuration steps

  1. Track a repository to the Cyral control plane, including any identity provider integrations and identity mappings. (See Cyral's Quickstart for more information.)

  2. Assign the repository to the Cyral sidecar.

  3. Configure your application to connect through the Cyral sidecar.

Optional steps for SSO integrations

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

  1. 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_DBSECRETS_REPO_ADMIN='{"username":"admin", "password": "Some-S3cure_Pa$$word!"}'

  1. Save the file.

  2. Restart the cyral-authenticator to load the new changes.

sudo systemctl restart cyral-authenticator

API calls and examples

Generate a secret for the sidecar

POST /v1/sidecars











JSON containing the name of your new sidecar

Sample JSON Request Body


   "name": "new-side-name"


Sample JSON Response


   "ID": "1s5DCG5DYhUtCiWQl5PtgDSg41M",

   "accessKey": "",

   "clientID": "s/salgatt/1s5DCG5DYhUtCiWQl5PtgDSg41M/1620153427782515947",

   "clientSecret": "Cz5iMRu4xCYep3CfPnDvdWzJhOPitG0y2S4_Uvu8qGUealF8"



Sidecar has not registered

This will display upon the initial creation and should disappear once a sidecar has been installed.

Sidecar is unhealthy

This will happen when all of the services are still being configured and brought online.

Sidecar is healthy but instance counts don't match

If the number of instances listed on the sidecars page does not match the number of instances showing in the instance tab of the sidecar you just set up, like the below screenshots:

Sidecars list

Sidecar instance tab

This means that the sidecar exporter service is not running or is improperly configured

Health monitoring information

This section provides useful information regarding monitoring Cyral services.


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 from our Cyral Docs. 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 Port

Metrics Port





















Process monitoring

In addition to metrics monitoring, some customers may also leverage a local service that checks for the existence of expected processes. In order to help customers 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 Name





Used to establish connectivity from the sidecar to the Cyral control plane



Layer 4 service that handles connections through the sidecar for clients connecting to the database.



This service catalogs and sends notifications for alert-worthy events



Layer 7 service that provides inspection of MySQL specific queries and commands.



Layer 7 service that provides inspection of Oracle specific queries and commands.



This service talks to identity and MFA providers on behalf of other Cyral services



Layer 7 service that provides inspection of Postgres specific queries and commands.



Layer 7 service that provides inspection of SQL Server specific queries and commands.



Exports sidecar's information, like its endpoint, cloud, region, sidecar version, etc…



Service that sends metrics and other information to the Cyral control plane.



Layer 7 service that provides inspection of Dremio specific queries and commands.



Layer 7 service that provides inspection of S3 specific queries and commands.



Layer 7 service that provides inspection of Mongo DB specific queries and commands.



Layer 7 service that provides inspection of REST API specific queries and commands.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.