SSHepherd Documentation
< All Topics
Print

Installing the SSHepherd® Control App and CLI

Overview

This article will guide you through installing the SSHepherd® Control App and CLI. The Control App and CLI (shepctl) are used to connect to your SSHepherd® Command-and-Control (C3) Server which then makes the connection to your protected hosts.

System Requirements

  • Windows 10 Professional or Enterprise
  • Windows 11 Professional or Enterprise
  • Windows Server 2016
  • Windows Server 2019
  • Windows Server 2022
  • Ubuntu 16.04 +
  • Red Hat 7.9 +
  • Debian 11 +
  • MacOS Ventura +

The SSHepherd® Control App and CLI is available for x64 and AArch64 architectures.

Installing on Windows

  1. Download and install shepctl.msi
  2. When the installation completes, launch the SSHepherd® Control App
  3. Enter your SSHepherd® server URL, username and password
  4. Configure your sessions

Installing on MacOS

IMPORTANT: In order to run RDP Sessions using SSHepherd® on MacOS, Microsoft Remote Desktop must be installed. It is available in the Apple App Store.

  1. Download and double-click shepctl.dmg
  2. Remove the quarantine attribute (required on some MacOS installs). Open a terminal and type:

sudo xattr -r -d com.apple.quarantine /Applications/SSHepherd\ Control.app

  1. Drag the SSHepherd® icon and drop it over the Applications folder in the pop-up window
  1. When the installation completes, launch the SSHepherd® Control App.
  2. Enter your SSHepherd® server URL, username and password
  3. Next, you’ll want to configure your sessions.

Installing on Linux

Debian/Ubuntu – Add Repository

The following must be done once on all linux machines where you want to use shepagent or shepctl.

IMPORTANT: Replace user and password combinations in the following commands with your repository credentials.

sudo apt update && sudo apt install -y wget gnupg apt-transport-https

wget -O - https://user:password@repo.sshepherd.io/fullarmor.gpg.key|sudo apt-key add -

echo deb https://repo.sshepherd.io/debian buster main | sudo tee /etc/apt/sources.list.d/fullarmor.list

echo machine repo.sshepherd.io login user password password | sudo tee /etc/apt/auth.conf.d/fullarmor.conf

sudo apt update

Debian/Ubuntu – SShepherd® Control CLI Install:

This command installs the SSHepherd® Control CLI. We offer an optional SSHepherd® Control App for Linux GUI.

sudo apt install -y shepctl

SSHepherd Control CLI install on Ubuntu

Debian/Ubuntu – SSHepherd® Control App (UI) Install (optional):

IMPORTANT: The SSHepherd® Control CLI (shepCTL) must be installed prior to installing the SSHepherd® Control App (shepUI).

sudo apt install -y shepui

  1. Once the install completes, you will find the SSHepherd® Control App in Applications.
  2. Launch the SSHepherd® Control App
  3. Enter your SSHepherd® server URL, username and password
  4. Next, you’ll want to configure your sessions
SSHepherd Control App (UI) Install on Ubuntu

RedHat/CentOS – Add Repository

The following must be done once on all linux machines where you want to use shepagent or shepctl.

IMPORTANT: Replace user and password combinations in the following commands with your repository credentials.

sudo yum install wget

wget -O - https://user:password@repo.sshepherd.io/el$(rpm -E '%{?rhel}')/sshepherd.repo | sudo tee /etc/yum.repos.d/sshepherd.repo

echo "username=user" | sudo tee -a /etc/yum.repos.d/sshepherd.repo

echo "password=password" | sudo tee -a /etc/yum.repos.d/sshepherd.repo

sudo yum update

RedHat/CentOS – SSHepherd® Control App Install:

This command installs the SSHepherd® Control CLI. We offer an optional SSHepherd® Control App for Linux GUI.

sudo yum install shepctl

RedHat/CentOS – SSHepherd® Control App (UI) Install (optional):

IMPORTANT: The SSHepherd® Control CLI (shepCTL) must be installed prior to installing the SSHepherd Control App (shepUI).

sudo yum install shepui

Logging in with SSHepherd® Control App

Using a local SSHepherd account

  1. Once the install completes, you will find the SSHepherd® Control App in Applications.
  2. Launch the SSHepherd® Control App
  3. Enter your SSHepherd® server URL
  4. When the username and password fields are displayed, enter your local SSHepherd user name (email) and password to authenticate
  5. Next, you’ll want to configure your sessions

Using an Active Directory account

  1. Once the install completes, you will find the SSHepherd® Control App in Applications.
  2. Launch the SSHepherd® Control App
  3. Enter your SSHepherd® server URL
  4. When the username and password fields are displayed, enter your AD user name and password to authenticate
  5. Next, you’ll want to configure your sessions

Using SSO (saml, oidc)

  1. Once the install completes, you will find the SSHepherd® Control App in Applications.
  2. Launch the SSHepherd® Control App
  3. Enter your SSHepherd® server URL
  4. Instead of being prompted to enter a user and password, your default web browser will open and prompt you to login to your SSO provider
  5. Next, you’ll want to configure your sessions

Logging in with SSHepherd® Control CLI (shepctl)

  1. Open a Terminal and run the following command

shepctl --url https://<yourSSHepherdServer> login

  1. For local SSHepherd authentication or Active Directory, when prompted, enter your username and password
  2. For SSO (saml, oidc) authentication, instead of being prompted for a username and password, you’ll receive a URL and a validation code. Paste the URL into your web browser and enter the code. The code is only valid for 10 minutes before it expires and can no longer be used to validate your device. You will be directed to your SSO provider for authentication.
  3. For Help, or to see a list of the shepctl commands and options, type:

shepctl --help

Note: Active Directory can use simple username/password combinations, however they are validated against the AD server configured in the C3 server.

Important: In order to bypass the configured authentication methods and login to the SSHepherd C3 with a local SSHepherd account, pass the –user parameter with your local SSHepherd user account.
Example:
shepctl --url https://yourSSHepherdServer --user shepadmin@shep.com login

In This Article