Getting Started
This section describes how to install the CernVM-FS client. The CernVM-FS client is supported on x86, x86_64, and ARM architectures running Linux and macOS \(\geq 10.14\) as well as on Windows Services for Linux (WSL2). There is experimental support for Power and RISC-V architectures.
Overview
The CernVM-FS repositories are located under /cvmfs
.
Each repository is identified by a fully qualified repository name.
On Linux, mounting and unmounting of the CernVM-FS is usually controlled by autofs
and automount.
That means that starting from the base directory /cvmfs
different repositories are mounted automatically just by accessing them.
A repository will be automatically unmounted after some automount-defined idle time.
On macOS, mounting and unmounting of the CernVM-FS is done by the user with sudo mount -t cvmfs /cvmfs/...
commands.
Getting the Software
The CernVM-FS source code and binary packages are available from the CernVM website. However, it is recommended to use the available package repositories that are also provided for the supported operating systems.
Linux
To add the CVMFS repository (available for Debian and RHEL flavors) and install CVMFS, run:
sudo yum install https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest.noarch.rpm
sudo yum install -y cvmfs
wget https://ecsft.cern.ch/dist/cvmfs/cvmfs-release/cvmfs-release-latest_all.deb
sudo dpkg -i cvmfs-release-latest_all.deb
rm -f cvmfs-release-latest_all.deb
sudo apt-get update
sudo apt-get install cvmfs
sudo dnf install https://ecsft.cern.ch/dist/cvmfs/cvmfs-2.11.5/cvmfs-2.11.5-1.fc38.x86_64.rpm \
https://ecsft.cern.ch/dist/cvmfs/cvmfs-config/cvmfs-config-default-latest.noarch.rpm \
http://ecsft.cern.ch/dist/cvmfs/cvmfs-2.11.5/cvmfs-libs-2.11.5-1.fc38.x86_64.rpm
Other Platforms
The CernVM-FS service container can expose the /cvmfs
directory tree to the host.
Import the container with
docker pull registry.cern.ch/cvmfs/service:latest
or with
curl https://ecsft.cern.ch/dist/cvmfs/cvmfs-2.11.5/cvmfs-service-2.11.5-1.x86_64.docker.tar.gz | docker load
Run the container as a system service with
docker run -d --rm \
-e CVMFS_CLIENT_PROFILE=single \
-e CVMFS_REPOSITORIES=sft.cern.ch,... \
--cap-add SYS_ADMIN \
--device /dev/fuse \
--volume /cvmfs:/cvmfs:shared \
cvmfs/service:2.11.5-1
Use docker stop
to unmount the /cvmfs
tree.
Note
If you run multiple nodes (a cluster), use -e CVMFS_HTTP_PROXY
to set a proper site proxy as described further down.
On Mac OS X, CernVM-FS is based on macFUSE. Note that as of macOS 11 Big Sur, kernel extensions need to be enabled to install macFUSE. Verify that fuse is available with
kextstat | grep -i fuse
Download the CernVM-FS client package in the terminal in order to avoid signature warnings
curl -o ~/Downloads/cvmfs-2.11.5.pkg https://ecsft.cern.ch/dist/cvmfs/cvmfs-2.11.5/cvmfs-2.11.5.pkg
Install the CernVM-FS package by opening the .pkg file and reboot. Future releases will provide a signed and notarized package.
A native package for Apple Silicon M1/M2 … processors is available as well, use the following command instead:
curl -o ~/Downloads/cvmfs-2.11.2-applesilicon.pkg https://ecsft.cern.ch/dist/cvmfs/cvmfs-2.11.2/cvmfs-2.11.2-applesilicon.pkg
Future releases will provide a package with universal binaries.
Follow the Windows instructions to install the Windows Subsystem for Linux (WSL2). Install any of the Linux distributions and follow the instructions for the distribution in this guide. Whenever you open the Linux distribution, run
sudo cvmfs_config wsl2_start
to start the CernVM-FS service.
Setting up the Software
Configure AutoFS
For the basic setup, run cvmfs_config setup
.
This ensures that the file /etc/auto.master.d/cvmfs.autofs
exists containing /cvmfs /etc/auto.cvmfs
and that the autofs
service is running. Reload the autofs
service in order to apply an updated configuration.
NB: For OpenSUSE uncomment the line #+dir:/etc/auto.master.d/
in the file /etc/auto.master
and restart the autofs
service.
sed -i 's%#+dir:/etc/auto.master.d%+dir:/etc/auto.master.d%' /etc/auto.master
systemctl restart autofs
Mac OS X
Due to the lack of autofs
on macOS, mount the individual repositories manually like
sudo mkdir -p /cvmfs/cvmfs-config.cern.ch
sudo mount -t cvmfs cvmfs-config.cern.ch /cvmfs/cvmfs-config.cern.ch
For optimal configuration settings, mount the config repository before any other repositories.
Create default.local
Create /etc/cvmfs/default.local
and open the file for editing.
Select the desired repositories by setting CVMFS_REPOSITORIES=repo1,repo2,...
. For ATLAS, for instance, set
CVMFS_REPOSITORIES=atlas.cern.ch,atlas-condb.cern.ch,grid.cern.ch
For an individual workstation or laptop, set
CVMFS_CLIENT_PROFILE=single
If you set up a cluster of cvmfs nodes, specify the HTTP proxy servers on your site with
CVMFS_HTTP_PROXY="http://myproxy1:port|http://myproxy2:port"
If you’re unsure about the proxy names, set CVMFS_HTTP_PROXY=DIRECT
.
This should only be done for very few clients (< 5), because large numbers can put a heavy load on the Stratum 1 servers and result, amongst others, in poorer performance for the clients.
For the syntax of more complex HTTP proxy settings, see Network Settings.
If there are no HTTP proxies yet at your site, see Setting up a Local Squid Proxy for instructions on how to set them up.
Verify the file system
Check if CernVM-FS mounts the specified repositories by cvmfs_config probe
.
If the probe fails, try to restart autofs
with sudo systemctl restart autofs
.
Building from source
The CernVM-FS client is not relocatable and needs to be installed under /usr. On Intel architectures, it needs a gcc \(\geq 4.2\) compiler, on ARMv7 a gcc \(\geq 4.7\) compiler. In order to compile and install from sources, use the following commands
cd <source directory>
mkdir build && cd build
cmake ../
make
sudo make install
Building with local libraries
For development purposes it might be useful to use locally installed libraries instead of using default system libraries.
This can be done by defining variables during the cmake
configuration step.
The correct naming of the variables can be found in cmake/Modules
.
For example, in case of Fuse3 following variables must be set: FUSE3_INCLUDE_DIR
and FUSE3_LIBRARY
.
Furthermore, CMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON
must be set, otherwise will sudo make install
strip all linked libraries that point to none-system libraries.
Example code for building CernVM-FS with locally built Fuse3 and including the CernVM-FS unit tests and gateway:
cmake -DCMAKE_INSTALL_RPATH_USE_LINK_PATH:BOOL=ON \
-D BUILD_UNITTESTS=ON -D BUILD_GATEWAY=ON \
-D FUSE3_INCLUDE_DIR=/usr/local/include/ \
-D FUSE3_LIBRARY=/usr/local/lib/x86_64-linux-gnu/libfuse3.so.3.10.5 \
../
make
sudo make install
Troubleshooting
In order to check for common misconfigurations in the base setup, run
cvmfs_config chksetup
CernVM-FS gathers its configuration parameter from various configuration files that can overwrite each other’s settings (default configuration, domain specific configuration, local setup, …). To show the effective configuration for repository.cern.ch, run
cvmfs_config showconfig repository.cern.ch
In order to exclude autofs/automounter as a source of problems, you can try to mount repository.cern.ch manually with the following
mkdir -p /mnt/cvmfs
mount -t cvmfs repository.cern.ch /mnt/cvmfs
In order to exclude SELinux as a source of problems, you can try mounting after SELinux has been disabled by
/usr/sbin/setenforce 0
Once the issue has been identified, ensure that the changes are taken by restarting
autofs
systemctl restart autofs
If the problem is that a repository can be mounted and unmounted but later cannot be remounted, see Remounting and Namespaces/Containers.
In order to exclude a corrupted local cache as a source of problems, run
cvmfs_config wipecache
Finally running with debug logs enabled can provide additional information for bug reports. This can be done by specifying a log file path in the client settings, e.g:
CVMFS_DEBUGLOG=/tmp/cvmfs.log
. See Debug Logs for more details.