CernVM-FS client system¶
The recommended way to gain access to CernVM-FS repositories is to set up a system-wide native installation of CernVM-FS on the client system(s), which comes down to:
- Installing the client component of CernVM-FS;
- Creating a minimal client configuration file (
/etc/cvmfs/default.local
); - Completing the client setup by:
- Creating a
cvmfs
user account and group; - Creating the
/cvmfs
and/var/lib/cvmfs
directories; - Configuring
autofs
to enable auto-mounting of repositories (recommended).
- Creating a
For repositories that are not included in the default CernVM-FS configuration you also need to provide some additional information specific to those repositories in order to access them.
This is not a production-ready setup (yet)!
While these basic steps are enough to gain access to CernVM-FS repositories, this is not sufficient to obtain a production-ready setup.
This is especially true on HPC infrastructure that typically consists of a large number of worker nodes on which software provided by one or more CernVM-FS repositories will be used.
After covering the basic client setup in this section, we will outline how to make accessing of CernVM-FS repositories more reliable and performant, by also setting up a proxy server and CernVM-FS Stratum 1 replica server.
Installing CernVM-FS client¶
Start with installing the cvmfs
package which provides the CernVM-FS client component:
# install cvmfs-release package to add yum repository
sudo yum install -y https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest.noarch.rpm
# install CernVM-FS client package
sudo yum install -y cvmfs
# install cvmfs-release package to add apt repository
sudo apt install lsb-release
curl -OL https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
sudo dpkg -i cvmfs-release-latest_all.deb
sudo apt update
# install CernVM-FS client package
sudo apt install -y cvmfs
If none of the available cvmfs
packages are compatible with your system,
you can also build CernVM-FS from
source.
Minimal client configuration¶
Next to installing the CernVM-FS client, you should also create a minimal configuration file for it.
This is typically done in /etc/cvmfs/default.local
,
which should contain something like:
CVMFS_CLIENT_PROFILE="single" # a single node setup, not a cluster
CVMFS_QUOTA_LIMIT=10000
More information on the structure of /etc/cvmfs
and supported configuration settings is available
in the CernVM-FS documentation.
Client profile setting (click to expand)
With CVMFS_CLIENT_PROFILE="single"
we specify that this CernVM-FS client should:
- Use the proxy server specified via
CVMFS_HTTP_PROXY
, if that configuration setting is defined; - Directly connect to a Stratum-1 replica server that provides the repository being used if no proxy server
is specified via
CVMFS_HTTP_PROXY
.
As an alternative to defining CVMFS_CLIENT_PROFILE
, you can also set CVMFS_HTTP_PROXY
to DIRECT
to specify
that no proxy server should be used by CernVM-FS:
CVMFS_HTTP_PROXY="DIRECT"
We will get back to CVMFS_HTTP_PROXY
later when setting up a proxy server.
Maximum size of client cache (click to expand)
The CVMFS_QUOTA_LIMIT
configuration setting specifies the maximum size of the CernVM-FS client cache (in MBs).
In the example above, we specify that no more than ~10GB should be used for the client cache.
When the specified quota limit is reached, CernVM-FS will automatically remove files from the cache according to the Least Recently Used (LRU) policy, until half of the maximum cache size has been freed.
The location of the cache directory can be controlled by CVMFS_CACHE_BASE
if needed (default: /var/lib/cvmfs
),
but must be a on a local file system of the client, not a network file system that can be modified by multiple
hosts.
Using a directory in a RAM disk (like /dev/shm
) for the CernVM-FS client cache
can be considered if enough memory is available in the client system, which would
help reduce latency and start-up performance of software.
For more information on cache-related configuration settings, see the CernVM-FS documentation.
Hierarchy of configuration files¶
CernVM-FS can be configured through a hierarchy of configuration files (sometimes also referred to as
parameter files), which can be located under either /etc/cvmfs
, or the CernVM-FS configuration repository
that is being used (there can be only one), which lives under /cvmfs
and is determined by the
CVMFS_CONFIG_REPOSITORY
configuration setting.
There are 3 levels of configuration files: general, domain-specific, and repository-specific.
Each CernVM-FS configuration file has either .conf
or .local
as file extension.
Order of configuration files¶
A CernVM-FS configuration file is sourced to set the configuration settings (a.k.a. parameters) it specifies, in the order outlined below:
- By level: first general, then domain-specific, finally repository-specific;
- Within each level:
.conf
before.local
;- CernVM-FS configuration repository before
/etc/cvmfs
(except for general level);
As a result, a configuration file that is picked up later can override configuration settings that were specified in an earlier consider configuration file.
Concrete example: the settings in the general /etc/cvmfs/default.local
configuration file
are overridden by those specified in the domain-specific configuration file
/cvmfs/cvmfs-config.cern.ch/etc/cvmfs/domain.d/eessi.io.conf
(which is located in
the default CernVM-FS configuration repository cvmfs-config.cern.ch
).
General level¶
At the general level, the following configuration files are considered (in order):
/etc/cvmfs/default.conf
/etc/cvmfs/default.d/*.conf
(in alphabetical order)$CVMFS_CONFIG_REPOSITORY/etc/cvmfs/default.conf
/etc/cvmfs/default.local
Domain-specific level¶
At the domain-specific level, the following configuration files are considered (in order):
$CVMFS_CONFIG_REPOSITORY/etc/cvmfs/domain.d/DOMAIN.conf
/etc/cvmfs/domain.d/DOMAIN.conf
/etc/cvmfs/domain.d/DOMAIN.local
where "DOMAIN
" is replaced by the domain of the CernVM-FS repository being considered,
like eessi.io
for software.eessi.io
.
Repository-specific level¶
At the repository-specific level, the following configuration files are considered (in order):
$CVMFS_CONFIG_REPOSITORY/etc/cvmfs/config.d/<your_repository>.conf
/etc/cvmfs/config.d/<your_repository>.conf
/etc/cvmfs/config.d/<your_repository>.local
Show configuration¶
To show all configuration settings in alphabetical order, including by which configuration file it got set,
use cvmfs_config showconfig
, for example:
cvmfs_config showconfig software.eessi.io
For CVMFS_QUOTA_LIMIT
, you should see this in the output:
CVMFS_QUOTA_LIMIT=10000 # from /etc/cvmfs/default.local
See also Inspecting repository configuration.
Completing the client setup¶
To complete the setup of the CernVM-FS client component,
we need to make sure that a cvmfs
service account and group are present on the system,
and the /cvmfs
and /var/lib/cvmfs
directories exist with the correct ownership and permissions.
This should be taken care of by the post-install script that is run when installing the cvmfs
package,
so you will only need to take action on these aspects if you were installing the CernVM-FS client from source.
In addition, it is recommended to update the autofs
configuration
to enable auto-mounting of CernVM-FS repositories, and to make sure the autofs
service is running.
All these actions can be performed in one go by running the following command:
sudo cvmfs_config setup
Additional options can be passed to the cvmfs_config setup
command to disable some of the actions,
like nouser
to not create the cvmfs
user and group, or noautofs
to not
update the autofs
configuration.
Recommendations for autofs
¶
It is recommended to configure autofs
to never unmount repositories due to inactivity,
since that can cause problems in specific situations.
This can be done by setting additional options in /etc/sysconfig/autofs
(on RHEL-based Linux distributions)
or /etc/default/autofs
(on Debian-based distributions):
OPTIONS="--timeout 0"
The default autofs
timeout is typically 5 minutes (300 seconds), which is usually specified in /etc/autofs.conf
.
Warning when using Slurm's job_container/tmpfs
plugin with autofs
(click to expand)
Slurm versions up to 23.02 had issues when the job_container/tmpfs
plugin was being used in combination with autofs
.
More information can be found at the Slurm bug tracker and the CernVM-FS forum.
Slurm version 23.02 includes a fix by providing a Shared
option for the job_container/tmpfs
plugin, which allows it to work with autofs
.
Using static mounts¶
If you prefer not to use autofs
, you will need to use static mounting, by either:
-
Manually mounting the CernVM-FS repositories you want to use, for example:
sudo mkdir -p /cvmfs/software.eessi.io sudo mount -t cvmfs software.eessi.io /cvmfs/software.eessi.io
-
Updating
/etc/fstab
to ensure that the CernVM-FS repositories are mounted at boot time.
Configuring autofs
to never unmount due to inactivity is preferable to using static mounts,
because the latter requires that every repository is mounted individually,
even if is already known in your CernVM-FS configuration.
When using autofs
you can access all repositories that are known to CernVM-FS through its active configuration.
For more information on mounting repositories, see the CernVM-FS documentation.
Checking client setup¶
To ensure that the setup of the CernVM-FS client component is valid, you can run:
sudo cvmfs_config chksetup
You should see OK
as output of this command.
Default repositories¶
The default configuration of CernVM-FS, provided by the cvmfs-config-default
package, provides the public keys and configuration for a number of
commonly used CernVM-FS repositories.
One particular repository included in the default CernVM-FS configuration is
cvmfs-config.cern.ch
, which is a CernVM-FS config repository
that provides public keys and configuration for additional flagship
CernVM-FS repositories,
like software.eessi.io
:
$ ls /cvmfs/cvmfs-config.cern.ch/etc/cvmfs
common.conf config.d default.conf domain.d keys
$ find /cvmfs/cvmfs-config.cern.ch/etc/cvmfs -type f -name '*eessi*'
/cvmfs/cvmfs-config.cern.ch/etc/cvmfs/domain.d/eessi.io.conf
/cvmfs/cvmfs-config.cern.ch/etc/cvmfs/keys/eessi.io/eessi.io.pub
That means we now already have access to the EESSI CernVM-FS repository:
$ ls /cvmfs/software.eessi.io
README.eessi host_injections versions
Inspecting repository configuration¶
To check whether a specific CernVM-FS repository is accessible, we can probe it:
$ cvmfs_config probe software.eessi.io
Probing /cvmfs/software.eessi.io... OK
To view the configuration for a specific repository, use cvmfs_config showconfig
:
cvmfs_config showconfig software.eessi.io
To check the active configuration for a specific repository used
by the running CernVM-FS instance,
use cvmfs_talk -i <repo> parameters
(which requires admin privileges):
sudo cvmfs_talk -i software.eessi.io parameters
cvmfs_talk
requires that the repository is currently mounted.
If not, you will see an error like this:
$ sudo cvmfs_talk -i software.eessi.io parameters
Seems like CernVM-FS is not running in /var/lib/cvmfs/shared (not found: /var/lib/cvmfs/shared/cvmfs_io.software.eessi.io)
Accessing a repository¶
To access the contents of the repository, just use the corresponding subdirectory as if it were a local filesystem.
While the contents of the files you are accessing are not actually available on the client system the first time they are being accessed, CernVM-FS will automatically downloaded them in the background, providing the illusion that the whole repository is already there.
We like to refer to this as "streaming" of software installations, much like streaming music or video services.
To start using EESSI just source the initialisation script included in the repository:
source /cvmfs/software.eessi.io/versions/2023.06/init/bash
You may notice some "lag" when files are being accessed, or not, depending on the network latency.
Additional repositories¶
To access additional CernVM-FS repositories beyond those that are available by default, you will need to:
- Add the public keys for those repositories into a domain-specific subdirectory of
/etc/cvmfs/keys/
; - Add the configuration for those repositories into
/etc/cvmfs/domain.d
(domain-specific) or/etc/cvmfs/config.d
(repository-specific).
Examples are available in the etc/cvmfs
subdirectory of the config-repo GitHub repository.
(next: Squid proxy server)