Installing and Running the Linux Client v5.0 (EA)

This article explains how to install and run the Cato Client (version 5.0 and higher) for the Linux OS.

Overview of the Linux v5.0 Client

Starting with version 5.0, the Linux Client supports different modes for connecting the device to the Cato Cloud. Client v5.0 introduces a new infrastructure for remote users which provide support for Single Sign-On (SSO), and resiliency improvements. These are the available modes in Linux to run the Client:

  • Browser based

    • Uses a browser for authentication with SSO

    • Supports new infrastructure for remote users

  • Terminal servers (CLI only, no browser)

    • Only able to authenticate with user name and password

    • Supports new infrastructure for remote users

  • Legacy Client - Terminal servers for MFA (CLI only, no browser)

    • Only able to authenticate with user name and password

    • Supports MFA and Device Authentication

    • Run the Client with the -legacy argument

Prerequisites

  • Supported Linux OS versions for 64-bit (X86_64):

    • Ubuntu v18 and higher

    • CentOS v8 and higher

    • Fedora v36 and higher

    • Debian v11 and higher

    • Mint v20.3 and higher

  • For SSO and GUI-based features:

    • Run the Cato Client from a GNOME-based desktop

    • Define a default browser for the device (generally the default setting is for GNOME)

  • The installation and execution scripts are run from the CLI, and require you to open a terminal app

Known Limitations

  • The Client automatically runs in the foreground, and with Client terminal session in the background. If you close the Client terminal session, the Client closes and the device disconnects from the Cato Cloud.

  • Automatic re-authentication is not supported. End-users must re-authenticate to the IdP in the browser.

Installing the Linux Client

Download from the Cato User Portal

To install the Client on a Linux device:

  • Run the Client file: cato-install-<OS name>.sh

Running the Linux Client

To run the Client in the browser mode, and include support for SSO, we recommend that you start the Client with no arguments. For terminal or legacy mode, or for troubleshooting purposes - add the required arguments to the command.

When running the Client, use the command with mandatory and optional arguments - ./cclient.sh <action> [argument1, argument2]. The available actions are start, restart, and stop.

After you start the Client on your device, it asks for the root password.

Run the following command to show the CLI arguments that you can use: ./cclient.sh –-help

To run the Client on a Linux device:

  • In the directory where the Client is installed:

    • To start the Client on a browser-based device, run: ./cclient.sh start

    • To start the Client in CLI based mode, run: ./client.sh start --user <user> --account <account>

    • To start the Client in CLI based (legacy) mode, run: ./client.sh start --user <user> --account <account> -legacy

Arguments for the Linux OS Client

These are the arguments that you can use for different features and settings when you run the Client.

Parameter

Description

--address

The Client connects to a specific Cato PoP (contact Support for the specific IP address). The default behavior is that the client automatically connects to the best PoP in the Cato Cloud.

--append {head|tail}

Preserves the existing configuration in /etc/resolv.conf.

When connected, the Client replaces /etc/resolv.conf with the DNS configuration received from Cato. Using this parameter appends the Cato configuration to the existing configuration.

  • head - adds the DNS configuration from Cato before the existing configuration, giving preference to the Cato configuration.

  • tail - adds the DNS configuration from Cato after the existing configuration, giving preference to the existing configuration.In both cases, /etc/resolv.conf is restored to its original contents on disconnection.

If Split Tunnel is enabled in the Cato Management Application, this parameter is ignored and the Client always replaces the contents of /etc/resolv.conf.

--floglevel

--gloglevel

Sets the file (floglevel) or global (gloglevel) logging settings for the Client:

  • 0 - verbose

  • 1 - debug

  • 2 - info

  • 3 - warning

  • 4 - error

  • 5 - none

--help

Shows the help screen.

--legacy

Runs the Client in legacy mode, with no web browser or SSO support.

Supports MFA with user name and password.

--metric _metric_

The route created for VPN traffic (see --route).

If not specified, this route has the highest priority on the system (identical to specifying --metric 0).

--port

Changes the DTLS port (443 or 1337), port 443 is the default setting.

--reconn _seconds_

Following a disconnect, the number of seconds the Client waits before attempting to reconnect. The Client attempts to reconnect at this interval until a connection is established or the client is stopped externally.

If this parameter is not specified, the client attempts to reconnect once and if unsuccessful, exits immediately.

--reg_code

Uses a registration code to authenticate to the Client.

--route

A single subnet that is routed to the tunnel instead of the default route. For example: --route 10.24.0.0/16 creates a specific route so only this subnet is routed through VPN.

If not specified, the Client adds a default route so all traffic is routed through the VPN on the device (identical to specifying --route 0.0.0.0/0).

--status

Displays the status of a running service.

--user, --account, --password, --reset-password, --reset-cred

Cato user credentials. These values are optional for users that authenticate with the web browser.

password is optional. When a password is required, the user is prompted to add a new one.

reset-cred resets all the user credentials and removes the authentication token (supported on v5.0 and higher).

Note

Note: We don't recommend using the --password argument.

--use-systemd-resolv

Uses systemd-resolv (instead of editing /dev/resolv.conf directly). The values for this parameter are:

  • 1 - true

  • 0 - false (default value)

When using the --use-systemd-resolv parameter with the Client, do NOT use the append parameter.

--version

Shows information about the Client version.

Arguments for Client File Parameters

You can save the arguments for the Linux Client to a file, and then load the parameters when you start the Client. These are the arguments for the Client file:

Parameter

Description

--load_file_

Uses the parameter values stored in the file previously with --save.

You can override any stored setting by specifying it on the command line.

Since the credentials are also stored in this file, make sure you keep it private as anyone can use this file to connect with the saved credentials. The password is saved in hashed form (SHA-256 with salt).

Alternately, you can store an empty or incorrect password in the file and specify the correct one on the command line. For example: --load _file_ --password '******'

--save_file_

Saves all arguments passed on the command line to the given file for use with the --load parameter.

--show_file_

Display the settings stored in the file using --save.

Arguments for Device Authentication with Certificates

This section contains arguments that are used for the Linux Clients that use Device Authentication with a device certificate. For more information, see Distributing Device Certificates.

Note

Note: Device Authentication is currently only supported when you run the Client in Legacy mode.

Parameter

Description

--cert <certificate path>

Path to the certificate file for Device Authentication.

Was this article helpful?

2 out of 4 found this helpful

4 comments

Date Votes
  • Comment author
    JM

    Where is the guide for installing just the certificate on Linux?

  • Comment author
    Dermot - Community Manager Only 42 of these badges will be awarded. They are reserved for people who have played a key role in helping build the Cato Community through their contributions! Community Pioneer The chief of community conversations. Community manager

    Hello JM!

    I suspect that this KB is the one that contains the desired information.  However, I am checking with Product Management to determine if this is correct.

    Kind Regards,

    Dermot Doran - Cato Networks Community Manager

  • Comment author
    JM

    Hi Dermot,

    That's the one for device authentication, what I am missing are the steps to install the Cato root certificate for TLS inspection. I found general instructions in Google-land of course, but I would expect those to be available here (as they are for the other platforms).

    JM

  • Comment author
    Dermot - Community Manager Only 42 of these badges will be awarded. They are reserved for people who have played a key role in helping build the Cato Community through their contributions! Community Pioneer The chief of community conversations. Community manager

    Ah!  I understand now what you are looking for.  I'll get back to you as soon as I can with a response from the PM team.

    Dermot

Add your comment