Download and installation#

There are multiple ways to install cunoFS:

Install locations#

When cunoFS is installed via the Scripted Installer, it gets installed to different locations depending on whether it was installed by root, or by a non-root user. Hereafter, root installations are called ‘system-wide’, and non-root installations are called ‘user-local’.

Note

A package manager install of cunoFS is always system-wide, regardless of the privileges of the user installing it.

cunoFS installation locations for per-user and systemwide installations#

Install type

Location (CUNO_ROOT)

Symlinks created in

User-local

~/.local/opt/cuno/

~/.local/bin/

~/.local/lib/x86_64-linux-gnu

~/.local/share/man/

System-wide

/opt/cuno/

/usr/bin/

/usr/lib/

/usr/share/man/

Scripted installer#

Distros using glibc (most)#

Most Linux distributions (including Debian/Ubuntu, RedHat and its derivatives) use the GNU Project’s C standard library (glibc). This installer/version is compatible with all such Linux distributions.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

For full details about user privileges for installation, see the user guide.

  1. Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version from your browser, or run the command:

    wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-glibc-installer.run

  2. To install only for the current user, run the following terminal command:

    sh cuno-glibc-installer.run

    To install system-wide, run:

    sudo sh cuno-glibc-installer.run

  3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.

  4. The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Distros using musl (Alpine)#

Some Linux distributions (Alpine) use the musl C standard library. This installer/version is compatible with all such Linux distributions.

The Scripted Installer allows you to install cunoFS without root privileges (no sudo).

Note

This release is coming very soon.

Note

This installation method assumes you have the libgcc package installed (due to a dependency on libgcc_s.so). On Alpine you can do (may require sudo):

apk add libgcc

Note

For full details about user privileges for installation, see the user guide.

  1. Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest musl version from your browser, or run the command:

    wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno-musl-installer.run

  2. To install only for the current user, run the following terminal command:

    sh cuno-musl-installer.run

    To install system-wide, run:

    sudo sh cuno-musl-installer.run

  3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.

  4. The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Package manager installation#

Debian and derivatives (e.g. Ubuntu)#

  1. Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version of the self-extracting package for Debian from your browser, or run the command:

    wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno_amd64_glibc_deb.run

  2. Unpack the archive by running:

    sh cuno_amd64_glibc_deb.run

  3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the extraction.

  4. The archive and its contents will be unpacked into a directory named cuno_1.1.7_amd64_glibc containing the package itself and additional documents:

    $ ls cuno_1.1.7_amd64_glibc
cuno_1.1.7_amd64.deb
CUNO-Installation-and-User-Guide.pdf

  5. Install cunoFS and its dependencies using apt:

    Note

    Be sure to use a relative path here, ./, to instruct apt not to search its repositories.

    sudo apt update
sudo apt install ./cuno_1.1.7_amd64_glibc/cuno_1.1.7_amd64_glibc.deb

  6. Complete the installation by following the interactive instructions.

  7. The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

RedHat and derivatives#

  1. Donwload the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the latest version of the self-extracting package for RHEL from your browser, or run the command:

    wget https://github.com/cunoFS/cunoFS/releases/latest/download/cuno_x86_64_glibc_rpm.run

  2. Unpack the archive by running:

    sh cuno_x86_64_glibc_rpm.run

  3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the extraction.

  4. The archive and its contents will be unpacked into a directory named cuno_1.1.7_x86_64_glibc containing the package itself and additional documents:

    $ ls cuno_1.1.7_x86_64_glibc
cuno_1.1.7_x84_64_.rpm
CUNO-Installation-and-User-Guide.pdf

  5. Install cunoFS and its dependencies using yum:

    sudo yum makecache
sudo yum install ./cuno_1.1.7_x86_64_glibc/cuno_1.1.7_x86_64_glibc.rpm

  6. Complete the installation by following the interactive instructions.

  7. The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Alpine Linux#

Warning

cunoFS APK packages for Alpine will be available soon.

sudo apk add --allow-untrusted ./cuno_1.1.7_amd64_musl/cuno_1.1.7_amd64_musl.apk

Other operating systems#

cunoFS is built for Linux distributions only, and does not natively support other operating systems. However, there are still ways to use cunoFS.

macOS using Docker#

Note

Alternatives to Docker on Mac are available, some recommended alternatives are:

  • Rancher Desktop (free) - If you’re on Apple Silicon, enable Rosetta (Settings > Virtual Machine > VZ: Enable Rosetta support) and VirtioFS (Settings > Virtual Machine > Volumes: virtiofs)

  • OrbStack for Mac (may be faster) - OrbStack works out of the box.

Unfortunately, colima is not currently supported.

A fully native Mac client is coming soon!

You can currently install cunoFS on your Mac directly, or inside a container. Installing cunoFS on your Mac directly will allow you to use cuno-mac, our handy tool for launching Linux containers that automatically have your local installation of cunoFS available inside them.

Note

For those on Apple Silicon (ARM) Macs, macOS 13.0 Ventura or later is required.

  1. All Mac users require a virtualisation/containerisation software to be installed and set up.

    We fully support usage of Docker and Rancher Desktop. Docker is assumed in these guides.

    Some settings should be changed to use cunoFS:

    We recommend changing the file sharing implementation to VirtioFS:

    1. Open Docker Desktop’s Settings panel

    2. Open the General section.

    3. For the setting Choose file sharing implementation for your containers select VirtioFS.

    4. Use the Apply & Restart button to save the change.

    You may also use OrbStack for Mac and find it to be faster, but cuno-mac native support is not available in this case.

    Unfortunately, colima is not currently supported.

  2. Download the installer. By downloading you are agreeing to the terms of the End User License Agreement. Click to download the Scripted Installer.

  3. Install the package onto your Mac directly, or inside a Linux container:

    Installing cunoFS on to your Mac directly will allow you to use cuno-mac, our handy tool for launching Linux containers that automatically have your local installation of cunoFS installed inside them.

    Note

    To use cuno-mac, you must also have Python 3 installed and available as python3 in Terminal.

    1. In a Terminal on your Mac, navigate to your download directory. If this was the default Downloads folder, you can run:

      cd /Users/$USER/Downloads

    2. Run the installer (without sudo):

      sh cuno-glibc-installer.run

    3. Please follow the interactive steps, read the displayed end-user licence agreement (EULA) and agree to the terms to continue with the installation.

    4. Export the cuno-mac location to your PATH variable:

      export PATH=$PATH:~/.local/opt/cuno/share/macos

      To have this persist and apply to new Terminal sessions, add this as a new line at the bottom of the file /Users/<your username>/.bash_profile using a text editor, or using the following command in a Terminal session:

      echo "PATH=\$PATH:~/.local/opt/cuno/share/macos" >> ~/.bash_profile

      Warning

      Do not miss the \ because otherwise your current PATH will be written literally into the profile and break future changes.

  4. The installation will prompt you to set the CUNO_ROOT environment variable to the installation directory. This is not always necessary when using cunoFS, but it will make it easier to follow the steps in this guide.

Additional instructions for cuno-mac users#

If you have installed cunoFS directly onto a Mac, you will only have access to cunoFS functionality within Docker containers. We provide the cuno-mac utility which you run from Terminal to launch conveniently set-up Linux containers.

The first time cuno-mac is run, a Docker image will be created with cunoFS ready to use, and a user will be set up within the container similar to your local user on the host Mac.

The Dockerfile found at ~/.local/opt/cuno/share/macos/Dockerfile can be edited to include any software packages you wish to have available inside the container. However, to update this will require deleting the old image first (by doing docker rmi cuno-mac), you can then run cuno-mac to rebuild it.

You must choose between using cuno-mac and cuno depending on the environment you are currently in.

To start a new session in which you can use cunoFS, you run cuno-mac in Terminal.

If any arguments are given to cuno-mac, it will start a temporary container and pass the arguments on to cuno.

If no arguments are given, cuno-mac will start a new interactive container and prefix (cuno) to your command-line prompt. This indicated that you are now inside a Docker container, so from here you cannot use cuno-mac and should instead use cuno.

To return to macOS, run exit until the (cuno) prefix is removed. You may only need to do this once, or you may need to do it multiple times if you have started subshells.

Windows using WSL2#

Windows clients require Windows Subsystem for Linux 2 (WSL2): Install WSL on Windows or inside a Linux virtual machine.

WSL installs Ubuntu by default, so the installation instructions for Debian can then be followed. You will be able to use cunoFS with any Linux applications also installed in the Linux subsystem.

Note

Refer to the Microsoft documentation on installing WSL for more information.

Exposing mounted object storage to the Host OS#

If you’re running cunoFs in a virtual machine, you can expose any object storage mounted as volumes in it using guest-to-host volume mapping.

Licence activation#

Interactive#

Activate your licence by running the command and following the interactive steps:

cuno creds activate

Note

Normally, activation means that access to cunoFS is limited to the user who runs cuno creds activate. However, if the user that runs cuno creds activate is root, then access can be optionally given to other users.

Non-interactive#

For non-interactive activation, you can supply a file to the command:

cuno creds activate "<file>"

You can also pipe the licence in as input:

echo "<your licence key>" | cuno creds activate

Note

The location of the license file after activation is $CUNO_ROOT/etc/license. By default, the permissions on this file are set to 0600. Administrators can manually modify the group and permissions to allow other system users accessing cuno.