Documentation > Administration > Child Host Management
⭐ PRO+

Child Host Management

Comprehensive guide to creating, managing, and monitoring child hosts including WSL instances, containers, and virtual machines within your SysManage infrastructure.

Professional+ Required for Write Operations

Creating, starting, stopping, restarting, and deleting child hosts requires a Professional+ license with the container_engine module. Viewing child hosts and distributions remains available in the Community Edition.

Overview

Child host management in SysManage enables you to create and manage virtualized environments directly from the web interface. This includes Windows Subsystem for Linux (WSL) instances, LXD/LXC containers, and various virtual machine technologies. Child hosts are automatically registered as managed hosts with the sysmanage-agent pre-installed.

Key Concepts

  • Parent Host: The physical or virtual machine that hosts child environments
  • Child Host: A virtualized environment (WSL, container, or VM) running on a parent host
  • Distribution: The operating system image used to create child hosts (e.g., Ubuntu, Debian, Fedora)
  • Virtualization Type: The technology used (WSL, LXD, VirtualBox, Hyper-V, KVM, etc.)
  • Agent Auto-Installation: Child hosts automatically receive the sysmanage-agent during creation

Supported Virtualization Types

  • WSL (Windows Subsystem for Linux): Run Linux distributions on Windows hosts
  • LXD/LXC: Linux containers for lightweight virtualization
  • VirtualBox: Cross-platform virtual machine management
  • Hyper-V: Windows native hypervisor support
  • KVM/QEMU: Linux kernel-based virtualization
  • VMM/vmd: OpenBSD virtual machine monitor
  • bhyve: FreeBSD hypervisor

Virtualization Detection

Automatic Detection

SysManage automatically detects virtualization capabilities on each managed host. The agent queries the system to determine which virtualization technologies are available and reports this information to the server.

Detected Capabilities

  • Hardware Virtualization: CPU support for VT-x/AMD-V extensions
  • Installed Hypervisors: Which virtualization software is installed
  • Enabled Features: Which features are enabled and ready to use
  • Pending Configuration: Features that require a reboot to enable

WSL Detection on Windows

On Windows hosts, SysManage detects WSL status and can automatically enable WSL if it's not already configured:

  • Not Installed: WSL feature is not enabled - can be enabled via SysManage
  • Needs Reboot: WSL was enabled but requires a system restart
  • Ready: WSL is enabled and ready to create child hosts

Child Hosts Tab

Accessing Child Hosts

The Child Hosts tab is available on each host's detail page for hosts that support virtualization:

  1. Navigate to Hosts in the main menu
  2. Select a host that supports virtualization
  3. Click the "Child Hosts" tab

Tab Information

The Child Hosts tab displays:

  • Virtualization Status: Shows enabled virtualization types and any pending configuration
  • Child Host List: All child hosts with their status (running, stopped, creating, error)
  • Action Buttons: Create, start, stop, restart, and delete child hosts
  • Enable Button: Enable WSL or other virtualization if not yet enabled

Creating Child Hosts

Professional+ Required

Creating child hosts requires a Professional+ license with the container_engine module. Community Edition users can view existing child hosts but cannot create new ones.

Prerequisites

  • Virtualization must be enabled on the parent host
  • User must have the "Create Child Host" permission
  • Desired distribution must be enabled in Settings > Distributions
  • Network connectivity for downloading distribution images

Creation Process

  1. Click "Create Child Host" button on the Child Hosts tab
  2. Select the virtualization type (if multiple are available)
  3. Choose a distribution from the dropdown list
  4. Enter a hostname for the new child host
  5. Provide a username and password for the initial user account
  6. Click "Create" to start the installation process

Form Fields

  • Virtualization Type: WSL, LXD, VirtualBox, etc. (based on host capabilities)
  • Distribution: The operating system to install (e.g., Ubuntu 24.04 LTS)
  • Hostname: Unique identifier for the child host (suggested format: parent-wsl-distro)
  • Username: The non-root user account to create
  • Password: Password for the new user account (not stored by SysManage)

Installation Progress

During creation, SysManage shows real-time progress including:

  • Distribution download (if not cached)
  • Installation and configuration
  • User account creation
  • Agent installation and configuration
  • Initial startup and connection

Host Approval Required

After creation completes, the new child host's agent will connect to the server. An administrator must approve the new host in the Hosts list, just like any other new agent registration. Once approved, the child host becomes fully managed.

Managing Child Hosts

Professional+ Required for Lifecycle Actions

Starting, stopping, restarting, and deleting child hosts requires a Professional+ license with the container_engine module. Viewing child host status remains available in the Community Edition.

Available Actions

Start

Starts a stopped child host. The child will boot and begin reporting to SysManage.

Required Permission: Start Child Host

Stop

Gracefully shuts down a running child host. All processes within the child are terminated.

Required Permission: Stop Child Host

Restart

Stops and then starts the child host. Useful for applying configuration changes.

Required Permission: Restart Child Host

Delete

Permanently removes the child host and all its data. This action cannot be undone.

Required Permission: Delete Child Host

Warning: Data Loss

Deleting a child host permanently removes all data stored within it. For WSL, this runs 'wsl --unregister' which completely removes the distribution. Ensure you have backups of any important data before deletion.

Status Indicators

  • Running: Child host is active and responsive
  • Stopped: Child host is shut down
  • Creating: Installation is in progress
  • Pending Approval: Agent is waiting for administrator approval
  • Error: An error occurred - check details for more information

Hosts List Integration

Filtering Child Hosts

The main Hosts list includes a filter toggle for child hosts:

  • All Hosts: Shows both parent and child hosts
  • Parents Only: Hides child hosts from the list
  • Children Only: Shows only child hosts

Parent-Child Navigation

  • View Children: Click the "Children" button on a parent host to filter for its child hosts
  • View Parent: On a child host's detail page, click "View Parent" to navigate to the parent host

Distribution Management

Professional+ Required for Distribution Changes

Adding, editing, and deleting distributions requires a Professional+ license with the container_engine module. Viewing available distributions remains available in the Community Edition.

Accessing Distribution Settings

Manage available distributions through:

Settings > Distributions

Distribution Operations

  • Add Distribution: Add new distributions with install identifiers and agent configuration
  • Edit Distribution: Modify distribution settings, install commands, or display names
  • Enable/Disable: Control which distributions are available for child host creation
  • Delete Distribution: Remove distributions that are no longer needed

Agent Installation Methods

Each distribution specifies how to install the sysmanage-agent:

  • APT (Launchpad PPA): For Ubuntu and Debian-based distributions
  • DNF (COPR): For Fedora, RHEL, Rocky Linux, AlmaLinux, and Oracle Linux
  • Zypper (OBS): For openSUSE and SLES distributions
  • Manual: Custom installation commands for other distributions

Permissions (RBAC)

Virtualization Roles

Child host operations require specific permissions from the Virtualization role group:

  • View Child Host: View child hosts and their status (read-only)
  • Create Child Host: Create new WSL instances, containers, or VMs
  • Start Child Host: Start stopped child hosts
  • Stop Child Host: Stop running child hosts
  • Restart Child Host: Restart child hosts
  • Delete Child Host: Delete child hosts and their data
  • Configure Child Host: Manage distribution settings and configuration

WSL-Specific Information

Requirements

  • WSL version 2 (WSL v1 is not supported)
  • systemd support (enabled automatically during creation)
  • Windows 10 version 2004 or later, or Windows 11

Enabling WSL

If WSL is not enabled on a Windows host, SysManage can enable it automatically:

  1. Click "Enable WSL" on the Child Hosts tab
  2. The agent will run the necessary Windows commands
  3. A reboot may be required - the host will show "Reboot Required"
  4. After reboot, WSL will be ready for use

Supported WSL Distributions

SysManage ships with pre-configured support for distributions where sysmanage-agent packages are available:

Debian/Ubuntu Family (APT)

  • Ubuntu 24.04 LTS (Noble)
  • Ubuntu 22.04 LTS (Jammy)
  • Debian 12 (Bookworm)

Fedora/RHEL Family (DNF)

  • Fedora
  • Rocky Linux 9
  • AlmaLinux 9
  • Oracle Linux 9

openSUSE Family (Zypper)

  • openSUSE Tumbleweed
  • openSUSE Leap 15

LXD-Specific Information

Overview

LXD (pronounced "lex-dee") is a next-generation system container and virtual machine manager for Linux. SysManage supports LXD containers as child hosts, providing lightweight virtualization with near-native performance.

Requirements

  • LXD must be installed on the parent host (typically via snap)
  • LXD must be initialized (lxd init) with a storage pool and network bridge
  • A network bridge (typically lxdbr0) configured for NAT
  • The sysmanage-agent user must be a member of the lxd group
  • Linux host (Ubuntu, Debian, or other distributions with LXD support)

LXD Detection

SysManage automatically detects LXD when:

  • The lxc command is available on the system
  • LXD is properly initialized with at least one storage pool
  • A network bridge is configured and active

When LXD is detected and functional, the host will display "LXD Host" as one of its server roles.

Setting Up LXD

If LXD is not already configured on your Linux host:

  1. Install LXD: sudo snap install lxd
  2. Initialize LXD: sudo lxd init (accept defaults for simple setup)
  3. Add sysmanage-agent to the lxd group: sudo usermod -aG lxd sysmanage-agent
  4. Restart the sysmanage-agent service to apply group changes

Container Creation Process

When creating an LXD container, SysManage performs the following steps:

  1. Downloads the container image from the configured image server (images.linuxcontainers.org)
  2. Creates the container with the specified hostname
  3. Attaches the container to the default network bridge
  4. Starts the container and waits for network connectivity
  5. Creates the specified user account with sudo privileges
  6. Installs the sysmanage-agent from the appropriate package repository
  7. Configures the agent to connect to your SysManage server
  8. Starts the sysmanage-agent service

Networking

LXD containers are attached to the default network bridge (typically lxdbr0). The bridge provides:

  • DHCP: Automatic IP address assignment from the bridge's subnet
  • NAT: Outbound internet access through the parent host
  • DNS: Name resolution via the bridge's built-in DNS

The container's IP address is displayed in the child host details and in the managed host information after agent approval.

Supported LXD Distributions

SysManage supports creating LXD containers from distributions where sysmanage-agent packages are available:

Debian/Ubuntu Family (APT)

  • Ubuntu 24.04 LTS (Noble)
  • Ubuntu 22.04 LTS (Jammy)
  • Debian 12 (Bookworm)

Fedora/RHEL Family (DNF)

  • Fedora
  • Rocky Linux 9
  • AlmaLinux 9
  • Oracle Linux 9

openSUSE Family (Zypper)

  • openSUSE Tumbleweed
  • openSUSE Leap 15

LXD vs WSL

Feature LXD WSL
Host OS Linux Windows
Isolation Full container isolation Lightweight subsystem
Networking Bridged with own IP NAT through Windows
Performance Near-native Near-native
Storage ZFS, btrfs, dir, LVM Virtual disk (ext4)
Multiple instances Yes, unlimited Yes, unlimited

KVM/QEMU Virtual Machine Management

Overview

KVM (Kernel-based Virtual Machine) is a virtualization technology built into the Linux kernel. Combined with QEMU for hardware emulation and libvirt for management, it provides enterprise-grade virtual machine capabilities. SysManage integrates with KVM/libvirt to enable seamless VM creation and lifecycle management from the web interface.

Requirements

  • CPU with hardware virtualization support (Intel VT-x or AMD-V)
  • Linux kernel with KVM modules (kvm, kvm_intel or kvm_amd)
  • libvirt daemon installed and running (libvirtd)
  • QEMU with KVM acceleration support
  • libvirt default network or custom network bridge configured
  • The sysmanage-agent user must be in the libvirt group
  • Only available on Linux hosts

KVM Host Detection

SysManage automatically detects KVM capability by checking:

  • KVM kernel modules are loaded (/dev/kvm exists)
  • libvirt daemon is running and accessible
  • The virsh command is available and functional
  • At least one libvirt network is configured

When detected, the host is assigned the KVM Host role and KVM appears as an available virtualization type.

KVM Setup

To prepare a host for KVM virtual machine management:

  1. Verify CPU virtualization support: grep -E 'vmx|svm' /proc/cpuinfo
  2. Install KVM packages: sudo apt install qemu-kvm libvirt-daemon-system (Debian/Ubuntu) or sudo dnf install qemu-kvm libvirt (Fedora/RHEL)
  3. Enable and start libvirtd: sudo systemctl enable --now libvirtd
  4. Add agent user to libvirt group: sudo usermod -aG libvirt sysmanage-agent
  5. Configure the default network: sudo virsh net-autostart default && sudo virsh net-start default
  6. Restart the sysmanage-agent service to pick up group membership

Alternatively, click "Enable KVM" in the SysManage web interface to automate these setup steps.

VM Creation Process

When creating a KVM virtual machine through SysManage:

  1. SysManage downloads the cloud image from the distribution's official source
  2. A new disk image is created and the cloud image is applied as a backing store
  3. Cloud-init configuration is generated with hostname, user account, and agent settings
  4. The VM is defined in libvirt with the specified resources (CPU, memory, disk)
  5. VM boots and cloud-init configures the system, creates the user, and installs the agent
  6. The sysmanage-agent service starts and connects to your SysManage server
  7. The VM appears in the Hosts list pending approval (or auto-approved if selected)

KVM-Specific Form Fields

When creating KVM VMs, additional configuration options are available:

  • VM Name: The libvirt domain name (must be unique on the host)
  • Memory: RAM allocation (e.g., "2G", "4096M") - default is 2GB
  • vCPUs: Number of virtual CPUs - default is 2
  • Disk Size: Virtual disk size (e.g., "20G", "50G") - default is 20GB

Networking

KVM VMs connect to the libvirt default network which provides:

  • DHCP: VMs receive IP addresses automatically from the virbr0 bridge (typically 192.168.122.x)
  • NAT: Outbound connectivity is provided via NAT through the host
  • DNS: VMs use the host's DNS servers for name resolution

For advanced networking, SysManage also supports bridged mode where VMs get IP addresses directly from your network's DHCP server.

VM Lifecycle Management

Once created, KVM VMs support the full range of lifecycle operations:

  • Start: Boot the VM using virsh start
  • Stop: Gracefully shutdown the VM using virsh shutdown
  • Restart: Reboot the VM using virsh reboot
  • Delete: Remove the VM and its storage using virsh undefine --remove-all-storage

Supported Distributions

KVM VMs can be created using cloud images from distributions where the sysmanage-agent is available:

Debian/Ubuntu (APT)

  • Ubuntu 24.04 LTS (Noble)
  • Ubuntu 22.04 LTS (Jammy)
  • Debian 12 (Bookworm)

Fedora/RHEL Family (DNF)

  • Fedora
  • Rocky Linux 9
  • AlmaLinux 9
  • Oracle Linux 9

openSUSE (Zypper)

  • openSUSE Tumbleweed
  • openSUSE Leap 15

KVM vs LXD Comparison

Feature KVM LXD
Virtualization Type Full virtualization (hardware-level) OS-level containerization
Isolation Complete (separate kernel) Shared kernel with host
Guest OS Any (Linux, Windows, BSD) Linux only
Performance Near-native with VirtIO Native (no overhead)
Resource Usage Higher (dedicated memory) Lower (shared resources)
Boot Time 30-60 seconds 1-2 seconds
Best For Full OS isolation, different kernels Lightweight Linux environments

Troubleshooting

Common Issues

Child Host Creation Fails

  • Verify the parent host has network connectivity
  • Check that the distribution is enabled in Settings
  • Ensure sufficient disk space on the parent host
  • Review the error message in the child host status

WSL Enable Requires Reboot

This is normal behavior. Use SysManage's reboot function to restart the Windows host, then retry creating child hosts.

Agent Not Connecting After Creation

  • Verify the child host is running (not stopped)
  • Check that the sysmanage-agent service is running inside the child
  • Verify network connectivity from the child to the SysManage server
  • Review the agent logs for connection errors

Child Host Shows "Error" Status

Click on the child host to view the error details. Common causes include:

  • Distribution download failed
  • Agent installation failed
  • User creation encountered an error

LXD Container Creation Fails

  • Verify LXD is initialized: run lxc storage list to check storage pools exist
  • Check the sysmanage-agent user is in the lxd group: groups sysmanage-agent
  • If group was just added, restart the sysmanage-agent service
  • Verify network bridge exists: lxc network list

LXD Container Has No Network

  • Check the container is attached to the bridge: lxc config show <container>
  • Verify the bridge is running: lxc network info lxdbr0
  • Check DHCP is enabled on the bridge
  • Inside the container, check if eth0 has an IP: lxc exec <container> -- ip addr

LXD Host Role Not Showing

  • Verify LXD is installed and the lxc command is in PATH
  • Ensure LXD is initialized with at least one storage pool
  • Wait for the agent to send an updated data collection or restart the agent
  • Check that the agent has permission to run lxc commands (lxd group membership)

LXD Container Agent Shows Not Privileged

  • Verify the sudoers file exists in /etc/sudoers.d/sysmanage-agent inside the container
  • Check the sudoers file has correct permissions (440 or 400)
  • Test sudo access: lxc exec <container> -- sudo -u sysmanage-agent sudo -n whoami
  • Restart the agent to refresh privilege detection

KVM VM Creation Fails

  • Verify KVM is enabled: virsh list --all should work without errors
  • Check libvirt is running: sudo systemctl status libvirtd
  • Ensure sysmanage-agent user is in the libvirt group: groups sysmanage-agent
  • Verify sufficient disk space in /var/lib/libvirt/images
  • Check the cloud image URL is accessible from the host

KVM VM Has No Network

  • Verify the default network is active: virsh net-list
  • Start the network if needed: virsh net-start default
  • Check VM network interface: virsh domiflist <vm_name>
  • Verify virbr0 bridge exists: ip addr show virbr0

KVM Host Role Not Showing

  • Verify /dev/kvm exists and is accessible
  • Check libvirtd is running and the virsh command works
  • Ensure sysmanage-agent user has libvirt group membership
  • Restart sysmanage-agent after adding to libvirt group

KVM VM Cloud-Init Not Completing

  • Access VM console: virsh console <vm_name>
  • Check cloud-init logs: /var/log/cloud-init.log and /var/log/cloud-init-output.log
  • Verify DNS resolution works inside the VM
  • Check if package installation failed due to repository access issues

Best Practices

Naming Conventions

  • Use descriptive hostnames that include the parent host name and purpose
  • Follow a consistent naming pattern: parent-type-distro (e.g., server01-wsl-ubuntu24)
  • Avoid special characters in hostnames

Security

  • Use strong passwords for child host user accounts
  • Promptly approve or reject pending child hosts
  • Regularly review and remove unused child hosts
  • Apply the principle of least privilege for permissions

Maintenance

  • Keep distributions updated with latest agent installation commands
  • Monitor child host disk usage to prevent parent host issues
  • Stop child hosts that are not actively in use
  • Back up important data before deleting child hosts

Quick Navigation

← Host Management Firewall Management →