Guest services and remote access

The eryph guest services run inside a catlet. They apply the catlet's fodder on first boot, report the provisioning progress to eryph and provide an SSH server that you can reach without any network configuration of the catlet.

Overview

The eryph guest services consist of two programs:

The provisioning agent is compatible with cloud-init: it applies the cloud-config fodder of the catlet and reports its progress to the host over Hyper-V KVP.

The SSH server of the guest services is separate from any SSH server you install in the catlet. It is reachable in two ways:

• Through eryph from any machine with an eryph connection. No access to the Hyper-V host and no administrator rights are needed.
• Over the Hyper-V socket directly on the Hyper-V host. No IP address, firewall rule or password is needed.

The commands on this page require eryph-zero 0.5 or later and the eryph powershell client 0.16 or later.

Adding guest services to a catlet

The guest services are installed by the fodder genes of the dbosoft/guest-services geneset. Add the gene for the operating system of your catlet:

Copyname: my-catlet
parent: dbosoft/winsrv2022-standard/starter
fodder:
  - source: gene:dbosoft/guest-services:win-install   # use linux-install for Linux catlets

The genes support the following variables:

Provisioning status and log

eryph tracks the provisioning status of every catlet. The status is reported by the guest services and shown by Get-Catlet and Get-CatletProvisioningStatus:

CopyGet-CatletProvisioningStatus my-catlet

When provisioning fails or takes longer than expected, read the provisioning log. The log is reassembled from the events which the guest reports to the host:

Copy# structured events, one object per event
Get-CatletProvisioningLog my-catlet

# human readable text log
Get-CatletProvisioningLog my-catlet -AsText

Reading the provisioning log starts an operation on the host, so it is only available while the catlet is running.

Guest services status and configuration

Get-CatletGuestServiceStatus returns the state reported by the guest services of a catlet:

CopyGet-CatletGuestServiceStatus my-catlet

By default, interactive SSH sessions start powershell.exe on Windows and the user's shell on Linux. You can change the shell for a catlet:

Copy# use PowerShell 7 without logo and profile
Set-CatletGuestServiceConfig my-catlet -Shell pwsh.exe -ShellArgs "-NoLogo -NoProfile"

# show the configured shell
Get-CatletGuestServiceConfig my-catlet

# reset to the default shell
Set-CatletGuestServiceConfig my-catlet -Shell "" -ShellArgs ""

An empty value clears the setting. A parameter which is not specified leaves the current value unchanged.

SSH access through eryph

With egs-tool you can connect to a catlet from any machine which has a connection to eryph. The SSH traffic is relayed by eryph to the guest services; the SSH session itself is encrypted end-to-end between your machine and the catlet.

Install egs-tool

Copyiex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/eryph-org/guest-services/main/src/Eryph.GuestServices.Tool/install.ps1'))

Connect to a catlet

Add an SSH configuration for the catlet and authorize your key in the guest:

Copy$catlet = Get-Catlet my-catlet
egs-tool catlet add-ssh-config $catlet.Id --add-key

The command prints the aliases you can use with ssh:

Copyssh my-catlet.eryph.alt               # catlet in the default project
ssh my-catlet.my-project.eryph.alt    # catlet in another project
ssh <catlet-id>.eryph.alt             # always unique

egs-tool catlet uses your default eryph client configuration. Use --configuration <name> and --client-id <id> to select another configuration or client.

The eryph client needs the scope compute:catlets:remote-access and read access to the catlet's project. The scopes compute:write, compute:catlets:write and compute:catlets:control include it. See Shared access & security.

SSH keys

By default, egs-tool creates a key for your user and stores it in your profile. To use your own key, specify it with --identity:

Copyegs-tool catlet add-ssh-config $catlet.Id --identity C:\Users\me\.ssh\id_ed25519 --add-key

The public key must be authorized in the guest. You can authorize it in three ways:

• With --add-key when you add the SSH configuration, as shown above.
• At runtime with egs-tool catlet add-key. Use --ttl to let the key expire, e.g. --ttl 8h, and --public-key <path> to authorize another public key.
• When the catlet is created, with the sshPublicKey variable of the guest services gene. egs-tool catlet get-client-key prints the public key of your managed key.

Copyfodder:
  - source: gene:dbosoft/guest-services:win-install
    variables:
      - name: sshPublicKey
        value: 'ecdsa-sha2-nistp256 AAAA... egs'   # from: egs-tool catlet get-client-key

To revoke your key, use egs-tool catlet remove-key <catlet-id> or Remove-CatletGuestServiceAccessKey:

CopyRemove-CatletGuestServiceAccessKey my-catlet

Both only revoke your own key. Keys of other users are not affected.

SSH access on the Hyper-V host

On the Hyper-V host you can also connect over the Hyper-V socket. This doesn't involve eryph and works for all virtual machines with guest services. Initialize egs-tool once on the host in an elevated PowerShell:

Copyegs-tool initialize

Then add an SSH configuration for the virtual machine. The command takes the Hyper-V VM id of the catlet, which is shown in the VmId property of Get-Catlet:

Copy$catlet = Get-Catlet my-catlet
egs-tool add-ssh-config $catlet.VmId
ssh "$($catlet.VmId).hyper-v.alt"

The key exchange happens over Hyper-V KVP, so no key needs to be authorized in advance.

Over the Hyper-V socket, egs-tool can also transfer files with upload-file, upload-directory, download-file and download-directory, and change the shell with set-shell.

Security

• Reading the provisioning status, the provisioning log and the guest services status requires the scope compute:catlets:read.
• Opening SSH channels, managing access keys and changing the guest services configuration require the scope compute:catlets:remote-access.
• Access through eryph is authorized with your eryph identity. A key can only be revoked by the user who authorized it.
• Access over the Hyper-V socket requires access to the Hyper-V host.

Further information on the guest services, including the supported cloud-config modules, can be found in the guest services repository.