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.
|Control plane URL||This is the URL for your Cyral control plane such as |
|API access key||This 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 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
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 sidecar 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
Get the sidecar installation script
Log in to your Cyral control plane as an administrator
Go to Sidecars
Click on the ➕ (plus sign) to create a new sidecar
Choose Deploy a sidecar using a Linux package
Click the Generate button
Enter a Sidecar Name for the sidecar. This is the name your administrators will use when they associate the sidecar with repositories.
Click the Generate button. The window will display a set of environment variable settings. Keep this window open.
Next you will log in to the machine where you'll install the sidecar and set the required environment variables.
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.
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.
Copy and paste the export commands from the Create sidecar window. This sets the environment variables such as
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
Copy the Cyral installation script to the server that will become a sidecar.
Make the install-linux.sh executable:
chmod +x install-linux.sh
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
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...
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.
Run a TCP health check probe on port 8888 of the sidecar host.
Check the sidecar's status
Log in to your control plane
Navigate to the Sidecars link on the left menu
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.
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.
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
- Track a repository to the Cyral control plane, including any identity provider integrations and access rules. (See the quickstart section for more information.)
- Assign the repository to the Cyral sidecar.
- 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.
- SSH to the sidecar.
- Edit the environment variables for the Cyral authenticator server.
sudo vi /etc/default/cyral-authenticator
- 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='tk"username":"admin", "password": "Some-S3cure_Pa$$word!"tkend'
- Save the file.
- Restart the cyral-authenticator to load the new changes.
sudo systemctl restart cyral-authenticator
Check sidecar health in the Cyral control plane UI as follows:
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.
Each of the deployed services exposes a HTTP service that provides
metrics on the
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
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|
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 Name||Critical||Description|
|cyral-forward-proxy||Yes1||Used to establish connectivity from the sidecar to the Cyral control plane.|
|cyral-dispatcher||Yes||Layer 4 service that handles connections through the sidecar for clients connecting to the database.|
|cyral-certificate-manager||Yes||This service renders TLS certificates to cyral-dispatcher.|
|cyral-alerter||No||This service catalogs and sends notifications for alert-worthy events.|
|cyral-mysql-wire||Yes||Layer 7 service that provides inspection of MySQL specific queries and commands.|
|cyral-oracle-wire||Yes2||Layer 7 service that provides inspection of Oracle specific queries and commands.|
|cyral-authenticator||No3||This service talks to identity and MFA providers on behalf of other Cyral services.|
|cyral-pg-wire||Yes2||Layer 7 service that provides inspection of Postgres specific queries and commands.|
|cyral-sqlserver-wire||Yes2||Layer 7 service that provides inspection of SQL Server specific queries and commands.|
|cyral-sidecar-exporter||No||Exports sidecar's information, like its endpoint, cloud, region, sidecar version, etc…|
|cyral-push-client||No||Service that sends metrics and other information to the Cyral control plane.|
|cyral-dremio-wire||Yes2||Layer 7 service that provides inspection of Dremio specific queries and commands.|
|cyral-s3-wire||Yes2||Layer 7 service that provides inspection of S3 specific queries and commands.|
|cyral-mongodb-wire||Yes2||Layer 7 service that provides inspection of Mongo DB specific queries and commands.|
|cyral-rest-wire||Yes2||Layer 7 service that provides inspection of REST API specific queries and commands.|
|cyral-dynamodb-wire||Yes2||Layer 7 service that provides inspection of Dynamo DB specific queries and commands.|
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.
This service is critical for the proper logging and policy enforcement on the sidecar if the respective repo is added to the sidecar.
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.