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.

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

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.

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

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:

Rootful
Rootless

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

$ 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