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.

Required ports for the Leader and Standbys
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:

Required ports for Followers

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 seccomp.json file

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

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

  2. Download and install the platform software:

    Platform Download link
    Docker v20.10 or later
    Podman 4.x

    Podman

    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 the docker commands can be used when working with Podman.

    Alternatively, you can manually replace docker in each command with podman.

    All references to Docker in this document apply to Podman as well.

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

All Conjur artifacts are cryptographically signed archives. We strongly recommend verifying archive signatures before installing them in your environment. For more information, see Verify signed Conjur artifacts.
  1. 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.

  2. 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 the docker 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 the docker 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 the podman 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 includes CAP_AUDIT_WRITE, the cap-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 that enable_ipv6 is set to false.

    To use the --network option, add the following line to the podman 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 the podman 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, mycontainer and for Followers, follower.

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

  • :z (lower case) indicates that the bind mount content is shared among multiple containers

     

    This option is recommended when working with selinux.

  • :Z (upper case) indicates that the bind mount content is private and unshared

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