Prepare VMs for Conjur deployment and configuration
Provisioned VMs require some additional setup before a Conjur container can be deployed and configured. This topic describes the steps needed to prepare and set up your provisioned VMs before deploying Conjur.
Step 1: Open ports
Conjur requires a number of ports be available for node-to-node communication.
By default, Podman running in rootless mode prevents port binding to ports lower than 1024. Either map your port bindings to a port higher than 1024 when you run the container or run the following command to allow binding to port 443.
sudo sysctl net.ipv4.ip_unprivileged_port_start=443
Leader/Standby
The following ports need to be open and accessible according to the following table.
From | To | Port | Protocol | Description |
---|---|---|---|---|
Admin endpoint |
Leader/Standby |
22 |
TCP |
SSH access Port 22 is a suggestion. You can choose an alternative port. |
Leader |
Standby |
5432 |
TCP |
PostgreSQL replication Required for data replication from the Leader to Standbys and Followers |
Standby |
Leader |
5432 |
TCP |
PostgreSQL replication Required for data replication from the Leader to Standbys and Followers |
Load balancer |
Leader |
5432 |
TCP |
PostgreSQL replication Required for data replication from the Leader to Standbys and Followers |
Load balancer |
Standby |
5432 |
TCP |
PostgreSQL replication Required for data replication from the Leader to Standbys and Followers |
Leader |
Standby |
443 |
TCP |
Auto-Failover |
Standby |
Leader |
443 |
TCP |
Auto-Failover |
Load balancer |
Leader |
443 |
TCP |
TLS endpoint for Conjur UI and API Access |
Load balancer |
Standby |
443 |
TCP |
TLS endpoint for Conjur UI and API Access |
Client |
Load balancer |
443 |
TCP |
TLS endpoint for Conjur UI and API Access |
Load balancer |
Leader |
1999 |
TCP |
syslog-ng audit stream Using syslog-ng, audit events are streamed from the Follower to the Leader |
Load balancer |
Standby |
1999 |
TCP |
syslog-ng audit stream. Using syslog-ng, audit events are streamed from the Follower to the Leader |
Load balancer |
Leader |
444 |
TCP |
HTTP health endpoint Simplifies load balancer setup |
Load balancer |
Standby |
444 |
TCP |
HTTP health endpoint Simplifies load balancer setup |
Follower
The following ports need to be open:
Port |
Accessible from |
Purpose |
---|---|---|
22 |
Local machine for setup / management |
SSH access Note: This specific port is not required by Conjur. You can choose an alternative port. |
443 |
Load balancer |
TLS endpoint for API |
444 |
Load balancer |
HTTP health endpoint Simplifies load balancer setup |
Step 2: Create system folders
If you are mounting volumes, you must first create the following folders to be mounted by the Conjur container.
These folders simplify the process of getting configuration data into the container as well as getting data out of the container for audit, backups, and more.
Folder |
Purpose |
---|---|
/opt/cyberark/conjur/security |
Location for the Docker |
/opt/cyberark/conjur/config |
Location for the configuration file |
/opt/cyberark/conjur/backups |
Allows backups to be available on the host server |
/opt/cyberark/conjur/seeds |
Simplifies transferring seed files into the Conjur container |
/opt/cyberark/conjur/logs |
Provides direct access to the Conjur logs locally |
To create the above folders, run the following command:
$ mkdir -p /opt/cyberark/conjur/{security,config,backups,seeds,logs}
For Podman, the system user running the Conjur container must own these folders. To update the ownership, run the following command:
chown [user]:[group] /opt/cyberark/conjur/{security,config,backups,seeds,logs}
Step 3: Recommended: Copy the Conjur configuration file
Conjur provides a configuration file conjur.yml
to hold system settings. The file is created in the /etc/conjur/config
directory inside the container, if one isn't already there when you define nodes using the evoke configure <role>
command.
We strongly recommend maintaining this file outside of the Docker container. To prepare for this, create an empty file in /opt/cyberark/conjur/config
by running:
$ touch /opt/cyberark/conjur/config/conjur.yml
To allow the Conjur container to read the file on start up, set the appropriate permissions on the file and the directory containing it by running the following commands:
chmod o+x /opt/cyberark/conjur/config
chmod o+r /opt/cyberark/conjur/config/conjur.yml
Step 4: Install your platform software
You can install the Conjur container image on Docker or Podman.
-
Before you begin:
-
A Conjur Server is packaged as a container image. For high availability, each Leader and Standby container should run on a separate VM.
-
For Conjur Server system requirements, see System requirements for Conjur Server.
-
-
Download and install the platform software:
Platform Download link Docker v20.10 or later - Community edition: See Docker Engine for your platform.
-
Enterprise edition (required for FIPS compliance): Mirantis Container Runtime (MCR) (previously known as Docker Enterprise Edition) on RHEL 8.x and 9.x.
Podman 4.x Podman is CLI-compatible with the Docker CLI. You can configure
alias docker=podman
for the shell that sets up the Conjur Server. This way, all thedocker
commands can be used when working with Podman.Alternatively, you can manually replace
docker
in each command withpodman
.All references to Docker in this document apply to Podman as well.
-
To ensure the container platform is correctly installed and running, open a terminal application and run the following command:
For example, run:
$
docker run --rm hello-world
The platform is installed and runs, and a message including "hello world" is displayed. You can now load the Conjur image.
Step 5: Load the Conjur container image
Make sure you have the Conjur Enterprise container image available.
For more information about accessing the image file, contact your CyberArk Customer Support.
-
Load the image into the Docker Engine. For example, for version 1.1.0, run:
$
docker load -i conjur-appliance_1.1.0.tar
Recommended: If your organization has a local Docker registry, push the Conjur Enterprise image to that registry.
-
View the image in Docker:
$
docker images
The output shows the repository and tag that you will use when creating your containers.
Step 6: Prepare the Docker seccomp profile (Docker and Podman only)
In production environments, we recommend that you harden your Conjur configuration by using a seccomp profile. A seccomp profile helps to enforce least privilege principles within Conjur. The profile is referenced in the docker run
command when you create the Conjur container. For more information about preparing a seccomp profile, see Docker security profile.
Step 7: Start the Conjur container
The following command starts an unconfigured Conjur Server. Additional work is required to configure these running containers into their designated purpose (Leader, Standby, or Follower).
-
For more information about common Docker commands and options that are useful to know when administering a Conjur container installation, see Docker command summary.
-
For Podman in rootless mode, the user running in the Conjur container must enable login lingering to allow the Conjur container to continue to run after the user is signed out. To enable login lingering, run the following command:
sudo loginctl enable-linger [user]
-
In a Podman environment that uses Container Network Interface (CNI) networking, you must add a network-scoped alias for the container and set the alias for all networks that the container joins. To set a name only for a specific network, use the
--network-alias
option when you create each container. A DNS-enabled network can use these aliases for name resolution.To determine if your network is DNS-enabled, run the following command:
podman network inspect -f .DNSEnabled [name]
To use the
--network-alias
option, add the following line to thedocker run
command:--network-alias=conjur-leader.mycompany.local
If the network is not DNS-enabled, use the
--add-host
option to map fully-qualified domain names (FQDNs) to IP addresses in the/etc/hosts
file. This mapping is required for ETCD name resolution in Conjur auto-failover clusters.To use the
--add-hosts
option, add the following line to thedocker run
command:--add-host=conjur01.mon.local:172.31.27.126
-
In Podman environments that drop the
AUDIT_WRITE
Linux capability by default, you must add this capability to the Conjur container by adding the--cap-add AUDIT_WRITE
argument to thepodman run
command.To determine whether you need to add this argument, run a Conjur container without this argument and run the command
podman inspect <container-name>
. The output includes a section titled CapDrop. If this section includesCAP_AUDIT_WRITE
, thecap-add AUDIT_WRITE
argument is required. -
For Podman in rootless mode, the user running the Conjur container may use the slirp4netns package to enable user-mode networking for unprivileged network namespaces. We recommend using the
--network
option to change the port handler from the default rootlesskit to slirp4netns to preserve the source IP information. When you configure the--network
option, ensure thatenable_ipv6
is set tofalse
.To use the
--network
option, add the following line to thepodman run
command:--network slirp4netns:enable_ipv6=false,port_handler=slirp4netns
-
In a Podman environment where
systemd
is used to manage the Conjur container lifecycle, you must remove the--restart=unless-stopped
argument from thepodman run
command. For more information, see Create systemd service.
Leader / Standby
(Docker and rootful Podman only) With the given configuration, the Conjur container uses a bridge network that isolates it from the host server. This is a security measure to provide least-privilege network access to the container. As a result, the Health check in the UI displays the bridge IP address for the Leader instead of the host server's IP address.
As a best practice, we recommend running the appliance container with security-opt (seccomp): security-opt seccomp=/opt/cyberark/conjur/security/seccomp.json
docker run \
--name <container-name> \
--detach \
--restart=unless-stopped \
--security-opt seccomp=/opt/cyberark/conjur/security/seccomp.json \
--publish "443:443" \
--publish "444:444" \
--publish "5432:5432" \
--publish "1999:1999" \
--log-driver journald \
--volume /opt/cyberark/conjur/config:/etc/conjur/config:Z \
--volume /opt/cyberark/conjur/security:/opt/cyberark/conjur/security:Z \
--volume /opt/cyberark/conjur/backups:/opt/conjur/backup:Z \
--volume /opt/cyberark/conjur/seeds:/opt/cyberark/conjur/seeds:Z \
--volume /opt/cyberark/conjur/logs:/var/log/conjur:Z \
registry.tld/conjur-appliance:<version>
Follower
As a best practice, we recommend running the appliance container with security-opt (seccomp):security-opt seccomp=/opt/cyberark/conjur/security/seccomp.json
docker run \
--name <container-name> \
--detach \
--restart=unless-stopped \
--security-opt seccomp=/opt/cyberark/conjur/security/seccomp.json \
--publish "443:443" \
--publish "444:444" \
--log-driver journald \
--volume /opt/conjur/config:/etc/conjur/config:Z \
--volume /opt/cyberark/conjur/security:/opt/cyberark/conjur/security:Z \
--volume /opt/cyberark/conjur/seeds:/opt/cyberark/conjur/seeds:Z \
--volume /opt/cyberark/conjur/logs:/var/log/conjur:Z \
registry.tld/conjur-appliance:<version>
<container-name> |
An appropriate name for the Conjur container, for example, for Leader/Standbys, |
||
<version> |
The version number of the Conjur image |
||
:z or :Z |
Modifies the label of the host file or directory being mounted into the container. This affects the file or directory on the host machine itself and can have consequences outside of the scope of the container platform.
|
To verify that the container is running, run:
$ docker ps -a
Create systemd service
(Podman only) For each container, create the systemd service that starts the Podman container automatically on reboot. To create this service, run the following commands:
$ sudo su
$ podman generate systemd <container-name> --name --container-prefix="" --separator="" > /etc/systemd/system/conjur.service
$ systemctl enable conjur.service
This systemd service definition includes a reference to the Conjur container ID. When you recreate the container, such as after an upgrade, you must also recreate this service. To recreate the systemd service, run the following:
$ sudo su
$ podman generate systemd <container-name> --name --container-prefix="" --separator="" > /etc/systemd/system/conjur.service
$ systemctl daemon-reload && systemctl restart conjur.service
$ mkdir -p $HOME/.config/systemd/user
$ podman generate systemd --name --container-prefix="" --separator="" > $HOME/.config/systemd/user/conjur.service
$ systemctl --user enable conjur.service
Enter the user password when prompted.
This systemd service definition includes a reference to the Conjur container ID. When you recreate the container, such as after an upgrade, you must also recreate this service. To recreate the systemd service, run the following:
$ mkdir -p $HOME/.config/systemd/user
$ podman generate systemd --name --container-prefix="" --separator="" > $HOME/.config/systemd/user/conjur.service
$ systemctl --user enable conjur.service
$ systemctl daemon-reload && systemctl restart conjur.service
Enter the user password when prompted.
When you use systemd
to manage a Conjur container, you must start the container without the --restart
argument. Otherwise, the systemd
service cannot stop properly. If you omit the --restart
argument, the following message appears when you generate the systemd
unit:
WARN[0000] Container <container-id> has restart policy "unless-stopped" which can lead to issues on shutdown: consider recreating the container without a restart policy and use systemd's restart mechanism instead
By default, if there is a failure, the systemd
service restarts the container. If a different restart policy is necessary, specify this when you run the podman generate systemd
command with the --restart-policy
argument. For example:
--restart-policy=on-failure
-
For Leader / Standby: Configure Conjur Leader
-
For Followers: Set up Follower