Skip to main content
Version: v4.15

Manage sidecar-repository bindings

A Cyral sidecar provides protection and access control to the data repositories bound to it. Below we explain how to bind repositories and manage the set of repositories bound to a sidecar.

Bind a repository to a sidecar​

To protect a repository and control how users connect to it, you must associate the tracked repository with a Cyral sidecar. We refer to this as binding the data repository to a sidecar. You may bind many repositories to a single sidecar.

Prerequisites​

Procedure​

When you bind a repository to a sidecar, you're associating the repository with the Cyral interception service that will secure and monitor it, and you're establishing a listener port where data users can safely and easily connect to the repository using the authentication method you specify.

  1. In the Sidecars tab, select the sidecar to which you'd like to bind the repository and click its name to reveal the configuration options for the sidecar.

  2. In the Data Repositories section of the Sidecars tab, click the Bind Data Repo button.

  3. In the Bind Data Repo window, choose the repository you want to protect with this sidecar.

  4. Specify the Sidecar port(s) where data users and applications will connect to this repository. All connections established through the port(s) specified here will be authenticated and monitored by Cyral.

    Note the following, based on your repo type:

    Smart Ports may allow you to re-use a port: On a given sidecar, you may choose to reuse a port number that's already in use for another repository of the same type. Such shared ports are called Smart Ports. A single Smart Port gives users access to as many repositories as you have assigned to that port. If a port has already been created for your repository type on this sidecar, its port number will appear in the drop-down list. For example, you can bind a new MySQL database on a sidecar port that's already bound to one of your other MySQL databases. For some repository types, Cyral does not support the Smart Ports feature. For these, you must choose a port number that's not in use on this sidecar.

    Smart Ports on MySQL and MariaDB: For a MySQL or MariaDB repository that uses a Smart Port, you must specify the version of MySQL/MariaDB that the sidecar will advertise to connecting clients.

    MongoDB replica sets: For a MongoDB replica set, you can set port numbers for all replicas. See Port ranges for MongoDB clusters

    S3 ports: For S3 repositories, you must specify a proxy port and, if the S3 Browser is enabled, an S3 browser port. See Track an S3 or DynamoDB storage location.

    info

    How is the Sidecar port used? Users and applications will connect to the repository at the sidecar host address and this Sidecar port number. Data users can look up the sidecar host address and listener port in the Data Access Portal panel in the Cyral UI.

    Must this Sidecar port match the native port exposed by the repository? No, you can choose a different port here. For information about the repository's native port, see Track a repository.

  5. Click Bind.

tip

If the sidecar is behind a VPN or load balancer, please verify that the port is exposed/open in your VPN or load balancer configuration.

You've configured your data repository to be monitored by a Cyral sidecar.

Next steps​

Smart Ports​

Smart Ports let you bind as many repositories as you wish to a single Cyral sidecar port. This can help:

  • minimize the amount of infrastructure you need to deploy/manage for sidecars; and
  • avoid the tricky task of aligning the set of ports on your sidecar instance with the ports needed by the repositories it protects.
info

Smart Ports are currently supported on MySQL, MariaDB, PostgreSQL, Denodo, Redshift and SQL Server repositories. For other repository types, each time you bind a new repository to a given sidecar, that repository must be given a unique port number on the sidecar.

Create a Smart Port​

A Smart Port is created automatically when you bind a repository to a port number that's already in use for another repository of the same type (for example, a MySQL database) on this sidecar. This applies only to MySQL, MariaDB, PostgreSQL, Denodo, Redshift and SQL Server repositories.

Once created, the Smart Port will be available for assignment to any other repository of the same type on this sidecar. You can choose it when you bind a repository to the sidecar.

note

MySQL, MariaDB and SQL Server users: Because a single Smart Port can provide access to multiple repositories whose database versions may differ, you must specify the advertised server version when assigning Smart Ports for MySQL and MariaDB and Smart Ports for SQL Server.

Manage Smart Ports​

To view and manage all the Smart Ports on a sidecar, follow these steps:

  1. Click Sidecars ➡️ click the name of your sidecar ➡️ Advanced.

  2. The Smart Ports section contains a tile for each Smart Port that's been created on this sidecar. Each Smart Port tile shows:

    • the port number where data users can connect
    • the repository type associated with this port
    • the number of repository bindings that currently use this port
    • if the Smart Port belongs to a repository type that includes additional properties (such as Advertised Version on MySQL ports), an edit button allows you to view and change those properties.

Ports for MySQL, MariaDB & SQL Server​

A single Smart Port can serve access to multiple repositories, and these repositories can have different database versions. As a result, it becomes essential to specify the advertised server version when assigning Smart Ports.

Advertised server version​

A Smart Port for MySQL, MariaDB, or SQL Server propagates an advertised server version in the network protocol. This is how the sidecar presents itself to client applications. The format consists of three numbers separated by dots, such as 8.0.4 (MySQL example), 10.6.7 (MariaDB example), or 14.0.3281 (SQL Server example).

The version advertised by the sidecar can be identical to the underlying database’s version. However, when multiple databases with different versions are connected to the same sidecar Smart Port, there can be discrepancies.

Always aim to have the underlying databases behind a single Smart Port at the same version. Ensure the advertised server version in the Smart Port configuration matches this version.

To correctly set up and manage these configurations, refer to the instructions below:

If your underlying MySQL database server versions are different:

  • Different major numbers (first digit), e.g., 8.x.x vs 5.x.x: Create individual Smart Ports for each major version.
  • Different minor numbers (second digit), e.g., x.0.x vs x.1.x: Create individual Smart Ports for each minor version.
  • Different patches (third digit), e.g., 8.0.1 vs 8.0.4: You can share the same Smart Port, with a few observations:
    • Use the lowest value across all MySQL database versions to configure the Smart Port advertised version. For example, between the two versions 8.0.1 and 8.0.4 we would configure the Smart Port with version 8.0.1. This helps prevent the client application from relying on changes only present in the newer version.
    • Refer to the following table that brings together server patch versions that are expected to present similar functionalities and can be multiplexed behind the same Smart Port.
MySQL versionVersion to advertise on Smart Port
5.5.40 - 5.5.625.5.40
5.6.17 - 5.6.515.6.17
5.7.1 - 5.7.35.7.1
5.7.4 - 5.7.45.7.4
5.7.5 - 5.7.165.7.5
5.7.17 - 5.7.405.7.17
8.0.0 - 8.0.08.0.0
8.0.1 - 8.0.28.0.1
8.0.3 - 8.0.178.0.4
8.0.18 - 8.0.228.0.18
8.0.23 - 8.0.268.0.23
8.0.27 - 8.0.318.0.27
note
By default, the Cyral sidecar shows an advertised server version of8.0.4 for MySQL repos.

Ports for MongoDB clusters​

For a MongoDB replica set cluster, Cyral's repository tracking page specifies the number of required ports for the cluster, and the Bind Data Repo page shows the list of ports, in the sidecar, that will be used.

The image below shows sidecar port assignments for a MongoDB replica set that was configured with 3 replication nodes on the repository tracking page.

Turn sidecar coverage on or off for a repository​

You can turn on and turn off the sidecar's coverage for a repository. Once a sidecar's coverage is turned off for a repository, the sidecar stops accepting connections for that repository. This means that the sidecar will not see requests and will not handle authentication or authorization for the repository. (Keep in mind that another sidecar might be providing coverage for the repository.)

tip

Don't confuse turning off coverage with passthrough mode. See Passthrough mode.

To turn a sidecar's coverage on or off for a given repository, you will disable its binding. Follow these steps:

  1. Click Sidecars ➡️ click the name of your sidecar ➡️ Repositories.

  2. Find your data repository in the list and click the more icon (three stacked dots) on the right side, and choose Edit.

  3. In the Edit Binding window, toggle the Enable binding setting to the desired position.

    warning

    You cannot disable the binding if the sidecar is designated for the Access Gateway. To remove the Access Gateway designation, see the Access Gateway instructions.

  4. Click Save.

Change the sidecar port for a repository​

To change a repository's assigned port(s) where the sidecar allows connections, follow these steps:

  1. Click Sidecars ➡️ click the name of your sidecar ➡️ Data Repositories.

  2. Find your data repository in the list and click the more icon (three stacked dots) on the right side, and choose Edit.

  3. In the Edit Binding window, set the Sidecar port to the desired port number. Note the following:

    • You may choose to assign a port number that's already in use for another repository on this sidecar. If you do this, Cyral converts the port into a Smart Port.
    • For a MySQL repository that uses a Smart Port, you must specify the Advertised version of MySQL that the sidecar will offer to connecting clients.
    • For a MongoDB replica set, you can set port numbers for all replicas. See Port ranges for MongoDB clusters

Unbind a repository from a sidecar​

tip

To temporarily disable a sidecar's coverage for a repository, you can turn sidecar coverage off for the repository.

To unbind a repository from a sidecar, follow the steps below. This ensures the sidecar will no longer handle traffic for the repository.

  1. Click Sidecars ➡️ click the name of your sidecar ➡️ Repositories.

  2. Find your data repository in the list and click the more icon (three stacked dots) on the right side, and choose Delete.