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.
Summary
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
Terminology
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 Packages
cyral-sidecar-<VERSION>.rpm or cyral-sidecar-<VERSION>.deb
Cyral Installer
install-deb-rpm.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
Installation steps
Generate a secret for the sidecar
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.
Log in to your Cyral control plane as an administrator
Go to Sidecars
Click on the + (plus sign) to create a new sidecar
Choose Deploying a sidecar using a custom template
Click the Generate button
Enter a name for the sidecar
Click the Generate button
On the resulting Generate private key pair screen, make a note of the Sidecar ID as this is needed for configuring the deployed sidecars.
Once you have recorded the Sidecar ID, click Done.
Click the Back button to return to the list of sidecars
Click on the sidecar that you just created
Click on the Client Secrets
Click the + (plus sign) to generate a new secret
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.
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.
Copy the Cyral package(s) and installer over to the server that will become a sidecar
SSH to the new server
Edit the install-deb-rpm.sh using a text editor like vi
Modify the global variables at the top of the installer and add the values shown below:
Below is an example:
Save your changes to the install-deb-rpm.sh.
Make the install-deb-rpm.sh executable:
Run the installer to install the sidecar
Validation steps
Perform the following steps to confirm your sidecar has been installed correctly.
Log in to your control plane
Navigate to the Sidecars link on the left menu
Identify the sidecar you just installed from the list and open it
Click on the sidecar name and go to the Instances tab to confirm the new sidecar is showing with a green checkmark.
Configuration steps
Track a repository to the Cyral control plane, including any identity provider integrations and identity mappings. (See Cyral's Quickstart for more information.)
Assign the repository to the Cyral sidecar.
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.
SSH to the sidecar.
Edit the environment variables for the Cyral authenticator server.
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.
Save the file.
Restart the cyral-authenticator to load the new changes.
API calls and examples
Generate a secret for the sidecar
POST /v1/sidecars
Parameters
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 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.
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 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:
Similar metrics are available for each service. The below table provides a subset of services that might be present and their corresponding 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:
