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

Requirements

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

Cyral Packages

  • cyral-product_cyral-sidecar.<VERSION>.rpm

  • cyral-sidecar-exporter_cyral-sidecar-exporter.<VERSION>.rpm

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 Forward Proxy

NOTE: 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 Control Plane’s web UI. In order to do this via API, refer to the Generate a Secret for the Forward Proxy 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 + 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 + 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 a separate Sidecar ID, Client ID, and Client Secret for each host.

  1. Copy the Cyral package(s) over to the new server

  2. Install the packages using the appropriate package manager (yum, dpkg, etc.)

    1. This will automatically start the services but they won’t function properly until they are properly configured.

  3. Configure each service by editing each config.yaml file. Only change the entries noted in the tables below. All other variables/values should not be changed.

    1. Cyral Forward Proxy (/etc/cyral/cyral-forward-proxy/config.yaml)

NOTE: This step assumes that you will be storing the forward proxy credentials locally on the machine in the config.yaml file. As an alternate installation step, you can follow the instructions located in the AWS Specific Install Steps section of this document. This alternate process stores the secret within AWS secrets instead.

The below table uses the example Control Plane URL of “salgatt.apdev.cyral.com”. You will need to substitute this url with your Control Plane’s URL such as mycompany.cyral.com. The ports and paths listed below should remain the same. 


The <CLIENT_ID> and <CLIENT_SECRET> should be replaced with the Client ID and Client Secret generated in the previous section.

tls-type

"tls"

grpc-gateway-address

"salgatt.apdev.cyral.com:9080"

http-gateway-address

"salgatt.apdev.cyral.com:8000"

token-url

"https://salgatt.apdev.cyral.com:8000/v1/users/oidc/token"

secret-manager-type

"direct"

secret-manager-meta

"{\"clientId\":\"<CLIENT_ID>\",\"clientSecret\":\"<CLIENT_SECRET>\"}"


  1. Cyral Alerter (/etc/cyral/cyral-alerter/config.yaml)

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

storage-endpoints

["localhost:8068"]

controlplane_host

localhost

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"

alert-catalog-host

localhost

alert-catalog-port

8068


  1. Cyral Authenticator (/etc/cyral/cyral-authenticator/config.yaml)

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

service

localhost

storage-endpoints

["localhost:8068"]

controlplane_host

localhost

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"

token-svc-port

8068


  1. Cyral * Wire (/etc/cyral/cyral-*-wire/config.yaml) - It depends upon which database types are supported by your sidecar, but this step should be repeated for each wire service. (See Appendix A - Wire Specific Configuration later in this guide for any changes required for each specific wire service.)

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

service

"localhost"

storage-endpoints

["localhost:8068"]

controlplane_host

"localhost"

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"


  1. Cyral Dispatcher (/etc/cyral/cyral-dispatcher/config.yaml)

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

service

"localhost"

storage-endpoints

["localhost:8068"]

controlplane_host

"localhost"

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"


  1. Cyral Push Proxy (/etc/default/cyral-push-client)

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

CYRAL_PUSH_CLIENT_FQDN

<SIDECAR_ID>

CYRAL_PUSH_CLIENT_PROXY_URL

http://localhost:8069


  1. Cyral Exporter (/etc/cyral/cyral-sidecar-exporter/config.yaml) - Config #1

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

service

"localhost"

controlplane_host

"localhost"

controlplane_port

8068

sidecar-version

“v2.18.1”

metrics-port

9023


  1. Cyral Exporter (/etc/default/cyral-sidecar-exporter) - Config #2

The <SIDECAR_ID> should be replaced with the Sidecar ID generated in the previous section.

API_ADDRESS

localhost

SIDECAR_ID

"<SIDECAR_ID>"

CYRAL_SIDECAR_EXPORTER_CONTROLPLANE_PORT

8068


  1. Restart the Push Client to reload its configuration

    1. sudo service cyral-push-client restart

  2. Enable the Explorer Service

    1. sudo systemctl enable cyral-sidecar-exporter

  3. Start the Explorer Service

    1. sudo service cyral-sidecar-exporter start

  4. Check the Cyral Control Plane and the sidecar should now be listed as healthy. There might be a few second delay for this status to change.

  5. You can also check the Instances list under the sidecar as these should begin showing up after a few minutes.


At this point, you should be able to manage this sidecar in the Cyral Control Plane by adding repos.

AWS Specific Install Steps

The previous steps assume that you are configuring the forward proxy credentials locally in the configuration files. If you are running on EC2, then we suggest that you follow the below steps to leverage AWS Secrets for storing the forward proxy’s credentials.

Create an AWS Secret

Create an AWS secret in the AWS secrets manager with a name that follows this convention:

/cyral/sidecars/{SIDECARID}/secrets


Be sure to create the secret within the same account and region as the EC2 instance(s) that will need to access it. The contents of the AWS Secret should be similar to the below example. Note that empty values need to be filled.


{

 "clientId": "",

 "clientSecret": ""

}

Assign IAM Role to EC2 Instance(s)

Give sidecar ec2 instance(s) permission to read from the AWS Secrets Manager. This requires attaching a policy to the ec2's IAM role. The policy should look similar to:


{

   "Version": "2012-10-17",

   "Statement": [

       {

           "Action": [

               "ec2:AssociateAddress",

               "ec2:DescribeAddresses"

           ],

           "Resource": "*",

           "Effect": "Allow"

       },

       {

           "Action": [

               "secretsmanager:GetSecretValue"

           ],

           "Resource": [

               "arn:aws:secretsmanager:us-west-2:XXXXXXXXXXXX:secret:/cyral/*",

               "arn:aws:secretsmanager:us-west-2:XXXXXXXXXXXX:secret:/cyral/sidecars/{SIDECARID}/secrets*"

           ],

           "Effect": "Allow"

       }

   ]

}


Configure Forward Proxy

Configure the forward proxy service by editing its config.yaml file. Only change the entries noted in the tables below. All other variables/values should not be changed.

Cyral Forward Proxy (/etc/cyral/cyral-forward-proxy/config.yaml): The below table uses the example Control Plane URL of “salgatt.apdev.cyral.com”. You will need to substitute this url with your Control Plane’s URL such as mycompany.cyral.com. The ports and paths listed below should remain the same. 

The <AWS_REGION> should be replaced with the region hosting your secret and EC2 instance(s). <SIDECAR_ID> should be replaced with the Sidecar ID generated in the control plane.

tls-type

"tls"

grpc-gateway-address

"salgatt.apdev.cyral.com:9080"

http-gateway-address

"salgatt.apdev.cyral.com:8000"

token-url

"https://salgatt.apdev.cyral.com:8000/v1/users/oidc/token"

secret-manager-type

"aws"

secret-manager-meta

"{\"region\":\"<AWS_REGION>\"}"

client-secret-name

"/cyral/sidecars/<SIDECAR_ID>/secrets"

Configure Service Start Delay

On AWS, we need to also add a delay for two of the services that attempt to establish a communications channel back to the Cyral Control Plane.

Cyral Forward Proxy Service

  1. Edit the /usr/lib/systemd/system/cyral-forward-proxy.service file

  2. Change the ExecStartPre

    1. From

/bin/touch /var/log/cyral/cyral-forward-proxy.log

  1. To

/bin/bash -c 'sleep 60;/bin/touch /var/log/cyral/cyral-forward-proxy.log'

Cyral Push Client Service

  1. Edit the /usr/lib/systemd/system/cyral-push-client.service file

  2. Change the ExecStartPre

    1. From

/bin/touch /var/log/cyral/cyral-push-client.log

  1. To

/bin/bash -c 'sleep 60;/bin/touch /var/log/cyral/cyral-push-client.log'



Configuration Steps

  1. Add an Oracle repo to the CP including any IDP integrations and identity mappings

  2. Add repo to sidecar

  3. Configure application to connect through sidecar



API Calls and Examples

Generate a Secret for the Forward Proxy

POST /v1/sidecars

Parameters

Name

In

Type

Required

Description

body

body

JSON

True

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"

}



Troubleshooting

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 Instances Do Not 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 setup, like the below screenshots:


Sidecars List

Sidecar Instance Tab


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

Appendix A - Wire Specific Configuration

MySQL Wire


service

"localhost"

storage-endpoints

["localhost:8068"]

controlplane_host

"localhost"

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"

metrics-port

9018

data-use-uds

true

secondary-data-unix-socket-file

"/etc/cyral/conf.d/secmysqluds"


PG Wire


service

"localhost"

storage-endpoints

["localhost:8068"]

controlplane_host

"localhost"

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"


Oracle Wire


service

"localhost"

storage-endpoints

["localhost:8068"]

controlplane_host

"localhost"

controlplane_port

8068

sidecar-id

"<SIDECAR_ID>"

metrics-port

9032


Did you find it helpful? Yes No

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