jirutka / virt-init

Provisioning scripts for Alpine Linux VMs

virt-init

This project provides “provisioning” scripts for Alpine Linux virtual machines running on VMware or platforms supporting cloud-init/nocloud (more platforms may be supported in the future).

WIP

Supported platforms

VMware/OVF

OVF properties are mapped to the variables for the provisioning scripts by converting to SCREAMING_CASE and replacing all non-alphanumeric characters with an underscore (_). For example, OVF property admin-user is mapped to variable ADMIN_USER. This mapping can be customized in the config via vmware_ovf_mapping. There’s one predefined mapping: hostname to SET_HOSTNAME. Some special variable names, such as PATH, PWD or RC_* variables, are protected.

VMware/guestinfo

This platform/source reads parameters from the GuestInfo variables.

GuestInfo parameters are mapped to the variables for the provisioning scripts explicitly via vmware_guestinfo_mapping in the config.

Cloud-init/nocloud

This platform reads parameters from files provided on an ISO 9660 (or VFAT) filesystem (typically a virtual CD-ROM) labeled cidata, specifically from the meta-data file and the user-data file in cloud-config format.

By default, $ADMIN_USER is mapped to the first user in the users directive or to the directive user (in this order of precedence).

This integration has been tested on the Proxmox platform.

Scripts

50-admin-user

Creates an user account named $ADMIN_USER with primary group users, secondary group $ADMIN_GROUP (defaults to wheel), and shell $ADMIN_SHELL (defaults to /bin/sh).

If $ADMIN_USER is not provided, this script is skipped.

50-grow-fs

Extends all mounted filesystems to the maximum disk capacity. Only ext3, ext4, and btrfs are currently supported.

If the filesystem resides on a partition (GPT or DOS) and it’s the last partition, it will be expanded before resizing the filesystem.

Note: It’s completely unnecessary and pointless to use partitions on virtual disks, it just adds more complexity and complications, but some broken platforms and tools (e.g. Veeam Backup) require it.

50-hostname

Sets the hostname to $SET_HOSTNAME, if provided. It should contain only alphanumeric ASCII characters and a hyphen ([a-zA-Z0-9-]), all other characters will be replaced with a hyphen (-).

50-timezone

Changes the system timezone to $TIMEZONE (e.g. Europe/Prague, UTC), if provided.

60-hosts

Adds the following lines to /etc/hosts:

127.0.0.1  <fqdn> <hostname> localhost
::1        <fqdn> <hostname> localhost

<fqdn> is $FQDN or, if not provided, $SET_HOSTNAME. It should contain only alphanumeric characters, a hyphen and a period ([a-zA-Z0-9.-]), all other characters will be replaced with a hyphen (-).

<hostname> is the system’s hostname (previously set to $SET_HOSTNAME).

60-ssh-keys

If $ROOT_SSH_KEYS with SSH public key(s) is provided, adds them to /root/.ssh/authorized_keys. If $ADMIN_SSH_KEYS is provided, adds them to authorized_keys of the user specified in $ADMIN_USER (defaults to root).

Requirements

• POSIX-compatible shell (e.g. ash, bash, dash, zsh)

• OpenRC

• btrfs utility and/or resize2fs from e2fsprogs (only for grow-fs script)

• partx and sfdisk from util-linux (only for grow-fs script if you use partitions)

• vmware-rpctool from open-vm-tools (only for VMware)

• yx tool (only for cloud-init)

Installation

Manually

1. Clone this repository and jump in:

   git clone https://github.com/jirutka/virt-init.git
   cd virt-init

2. Install files (you may need to run this with sudo):

   make install

   You may use the DESTDIR variable to specify the target prefix.

3. Add the virt-init service to the boot runlevel:

   rc-update add virt-init boot

License

This project is licensed under MIT License.

Resources

• Building your own Virtual Appliances using OVF properties

• How to extract host information from within a VM?

• The Power of OVF Properties