Using eryph-packer to create genesets

Creating your own genesets allows you to reuse your catlet and fodder genes on the genepool and share them with other users.

Genesets are created and uploaded to the genepool using eryph-packer, which is a standalone tool available for download.

Installing eryph-packer

To install eryph-packer, run the following command from a powershell prompt (does not have to be run as admin)

CopySet-ExecutionPolicy Bypass -Scope Process -Force; `
[System.Net.ServicePointManager]::SecurityProtocol = `
[System.Net.ServicePointManager]::SecurityProtocol -bor 3072; `
iex ((New-Object System.Net.WebClient).DownloadString( `
 'https://raw.githubusercontent.com/eryph-org/dotnet-genepoolclient/refs/heads/main/src/apps/src/eryph-packer/install.ps1'))

You can now run `eryph-packer' commands from the command line.

Authoring genesets

Catlet genesets

The simplest use case for a geneset is one that contains only catlets without volumes. These catlets will most likely have a parent and maybe some fodder content.

As an example, we will create a variant of the starter catlet for ubuntu-22.04 with a custom password.

Initialize Geneset and Tag

First, we will create the geneset folder.

Copyeryph-packer geneset init myorg/ubuntu-catlet

This will initialize the geneset folder for the organization myorg and the geneset name ubuntu-catlet.

The command response is the json of geneset.json, which is the geneset manifest.
The directory also contains a readme.md that can be used to document the geneset.

Next, we initialize our first geneset tag:

Copyeryph-packer geneset-tag init myorg/ubuntu-catlet/22.04-1

The response is again a manifest - this time the geneset-tag manifest.

Catlet content

Now you can add your catlet content to the geneset tag as catlet.yaml.
You can only create one catlet.yaml file in a geneset tag.

Copy# filename: catlet.yaml
parent: dbosoft/ubuntu-22.04/latest
fodder:
 - source: gene:dbosoft/starter-food:linux-starter 
   variables:
   - name: password
     value: nosecret

Pack & Push

Now we need to pack the geneset tag:

Copyeryph-packer geneset-tag pack myorg/ubuntu-catlet/22.04-1

Any error in catlet.yaml will now cause the command to fail. Check for errors and retry the pack command.

Finally, you can push your geneset tag:

Copyeryph-packer geneset-tag push myorg/ubuntu-catlet/22.04-1

A new browser window will open where you will need to authenticate (this is only required when accessing the genepool and will be cached for a while).

The geneset you created is automatically pushed before the geneset tag.

If you only want to push the geneset, you can also push it yourself:

Copy# Note the difference in the first argument
eryph-packer geneset push myorg/ubuntu-catlet

References

A geneset tag can only be pushed once into the genepool. Even if it is deleted, the name of the tag is still blocked for security reasons. So you should think about how to version your genesets. Typically you will have a version number or name somewhere in the catlet name.

To refer to your version catlet, you can use a reference tag. Reference tags are like normal tags, but they can have no content and can be updated automatically. The tag latest is a typical reference tag, but you can use any tag name as a reference:

Copy# init a tag for reference (22.04)
eryph-packer geneset-tag init myorg/ubuntu-catlet/22.04

# Add the reference
eryph-packer geneset-tag ref myorg/ubuntu-catlet/22.04 myorg/ubuntu-catlet/22.04-1

# pack
eryph-packer geneset-tag pack myorg/ubuntu-catlet/22.04

# push

eryph-packer geneset-tag push myorg/ubuntu-catlet/22.04

Fodder Genesets

The workflow for creating a fodder geneset is almost the same.
The difference is where you put the yaml files for the fodder genes:

Copygeneset-tag
│ catlet.yaml (optional)
│
└──fodder
    │Food1.yaml
    │ food2.yaml
    │
    └──arch
        │ food1.yaml
        │ food2.yaml
        │ ...

Food genes are usually placed directly in the food directory. Subdirectories can be used for architectural variations (see below).

Fodder Content

So let us extend the previous example. Instead of using the fodder gene from linux-starter, we create our own copy of linux-starter:

Copyeryph-packer geneset init myorg/ubuntu-basefood
eryph-packer geneset-tag init myorg/ubuntu-basefood/1.0

Copyname: ssh

variables:
  - name: lockPassword
    type: boolean
    value: true    
  - name: sshPublicKey
    required: true

fodder:
- name: admin-linux
  type: cloud-config
  secret: true
  content: 
    users:
    - name: orgadm
      plain_text_passwd: nosecret
      group: admin
      lock_passwd: {{ lockPassword }}
      sudo: 'ALL=(ALL) NOPASSWD: ALL'
      ssh_authorized_keys:
      - {{ sshPublicKey }}

This variant is much stricter than the starter food. It will only allow password access if you unlock password and expects an ssh key.

Now you can package this and push it out to your org:

Copyeryph-packer geneset-tag pack myorg/ubuntu-basefood/1.0
eryph-packer geneset-tag push myorg/ubuntu-basefood/1.0

Architecture Variations

All fodder genes in the fodder root directory have the architecture any, meaning they can be used on any architecture. The architecture defines the hypervisor and processor type the gene is compatible with. See Manifest documentation for supported values.

Base catlets

The most complex case is when you want to create your own base catlets, for example to customize them during build or to use your own licenses.

Base catlets are technically simple virtual machines that have only one strict requirement: they must support cloud-init to handle fodder configurations.
For Windows, there is a fork of cloud-init that supports a limited set of cloud-init features, but is sufficient for eryph. It can be found here: cloudbase.it/cloudbase-init

You can build the template with any tool you prefer, but we recommend something like Hashicorp packer. Hashicorp packer is used for many projects and you can find templates for many use cases on github.

You can also fork our base catlet repository and modify it to your needs: github.com/eryph-org/basecatlets-hyperv.

Importing VM Templates

When you have your VM template ready, export it to the file system. Then run the following command to import the template into the geneset

Copyeryph-packer geneset-tag add-vm <geneset-tag> <VM export path>.

This command generates a catlet from the VM settings and prepares to pack the volumes. You can now modify the generated catlet.

Now run

Copyeryph-packer geneset-tag pack <geneset-tag>

to pack the volumes and the catlet into the geneset tag.

Mixed Content

There is no restriction that you cannot use both catlets and fodder genes, or even base catlets, in the same geneset. However, it often makes more sense to keep them separate, especially if you are considering versioning:
Typically, you will version base catlets based on something like a build date or a release month. Fodder genes are typically versioned to provide fixes and new features. So having both in the same geneset would result in two different versioning schemes in the same geneset.

Therefore, it is recommended not to mix feed genes and base catlets in the same geneset.
Having catlets in both is fine, especially if they are separated by a prefix (like we use in the starter catlets). However, you should also keep them separate if they have special features and dependencies.

Testing

It is highly recommended that you test your geneset content before uploading it to the Genepool.

Fodder and catlets

As a best practice, you should first write fodder and catlets in a standalone catlet file.
Script commands can also be run directly on a test machine, tweaked, and then added to the fodder section of the test catlet.

If everything works, move the fodder content, if any, to a standalone file. See the next section to test the packed version of the feed gene.

Packed genesets

To test packed versions (base catlets and standalone fodder files), you can copy the contents of the .packed directory (created by the pack command) directly into your local genepool directory.

For example, if you have a geneset tag myorg/geneset/tag1, you need to copy the files from the .packed directory to <genepool>\myorg\genset\tag. When you use them in a catlet, eryph-zero will automatically extract the files.

This doesn't work for reference tags, because reference tags are always looked up in the genepool. Therefore, for testing, you should directly reference the tag you want to test.

In our geneset repository we have a script test_packed.ps1 that automates these tasks and performs some basic tests on new base catlets.