Profile v2 Reference

Profile v2 is the primary migration input format. It is YAML parsed with strict validation in the Go CLI. The JSON Schema lives at schemas/profile.v2.schema.json.

Required Top-Level Fields

schemaVersion: 2
name: example
source:
  ssh: old-server
target:
  ssh: new-server
sourcePolicy: strict-read-only
approved: false

Required fields:

• schemaVersion: must be 2.
• name: migration name.
• source.ssh: source SSH alias.
• target.ssh: target SSH alias, or provide --target at runtime.
• sourcePolicy: must be strict-read-only.
• approved: must be true before apply can proceed.

Platform Fields

platforms:
  source: ubuntu:22.04
  target: debian:12

HostShift uses platform values to determine support status and package capability mappings. Unknown targets block apply because package names cannot be guessed safely.

First-Install Target Configuration

These sections only affect the target.

Firewall

firewall:
  enabled: true
  enable: false
  rules:
    - from: 172.17.0.0/16
      port: 3306
      proto: tcp

Rules map to target UFW actions. from must be an IP address or CIDR prefix. port must be 1-65535. proto must be tcp or udp.

SSHD

sshd:
  settings:
    ClientAliveInterval: 120
    ClientAliveCountMax: 720

Supported keys:

• ClientAliveInterval
• ClientAliveCountMax

Values must be between 0 and 86400. HostShift writes /etc/ssh/sshd_config.d/99-hostshift.conf on the target, validates sshd -t, and reloads ssh or sshd.

MySQL

mysql:
  settings:
    bindAddress: 0.0.0.0
    mysqlxBindAddress: 127.0.0.1

HostShift writes /etc/mysql/mysql.conf.d/99-hostshift-bind.cnf on the target and reloads or restarts MySQL. Values must be valid IP addresses.

Workloads

workloads describe what must be prepared and moved.

workloads:
  - type: docker-compose
    name: customer-app
    data:
      workingDir: /srv/customer-app
      configFile: /srv/customer-app/docker-compose.yml
  - type: file-set
    name: app-files
    data:
      paths:
        - /srv/customer-app
        - /etc/nginx/sites-available/customer.conf
      targetPath: /
  - type: mysql
    name: customer_db
    data:
      sourcePasswordEnv: SRC_MYSQL_PWD
      targetPasswordEnv: DST_MYSQL_PWD
  - type: redis
    name: cache
    data:
      snapshotPath: /var/lib/redis/dump.rdb
      targetPath: /var/lib/redis/dump.rdb

Supported workload types are documented in Workload Reference.

Checks

checks define target-side verification.

checks:
  - type: http
    name: public-health
    data:
      url: http://127.0.0.1/health
      hostHeader: example.com
      timeoutSeconds: 10
  - type: mysqlScalar
    name: page-count
    data:
      database: customer_db
      query: SELECT COUNT(*) FROM pages
      expected: "42"

Supported check types are documented in Check Reference.

Approval Model

Profiles generated by discover are not approved:

approved: false

Apply commands are blocked until the operator reviews the profile and sets:

approved: true

This keeps discovery and plan generation separate from target mutation.

v1 Migration

HostShift can read v1 profiles and convert them to v2:

hostshift profile migrate --input examples/profile.yaml --output profile.v2.yaml

v1 fields map as follows:

v1 field	v2 destination
composeProjects	workloads[type=docker-compose]
standaloneContainers	workloads[type=docker-standalone]
fileSets	workloads[type=file-set]
databases	`workloads[type=mysql
healthChecks	checks
applicationChecks	checks