NAME

nuageinit — initialize a cloud-init environment

DESCRIPTION

The nuageinit program is used to initialize instances in a cloud environment. nuageinit runs at the first boot after the system installation. It is composed of three rc(8) scripts:

nuageinit

This script detects the type of cloud environment and gathers the configuration data accordingly. The following cloud environments are supported right now:

ondisk

A cloud agnostic environment where the disk is provided to the system with the configuration data on it. The disk must be formatted using one of the following filesystems: cd9660(4) or msdosfs(4) and be labelled (via filesystem label) either config-2 or cidata.

OpenStack

The system is running in an OpenStack environment. It is detected via the smbios.system.product smbios(4) description available in kenv(2).

Depending on the cloud environment above, nuageinit will attempt to configure the instance. This script executes early after all the local filesystem are mounted but before the network is configured.

nuageinit_post_net

This script is responsible for processing the configurations that are network dependent:

• dealing with packages
• dealing with users (which can depend on shell provided by packages)

nuageinit_user_data_script

This script is responsible for executing everything which would have been passed via the configuration to be executed, via the configuration or because the user_data provided is a script.

The default user for nuageinit is a user named freebsd with a password set to freebsd and a login shell set to /bin/sh.

CONFIGURATION

The configuration of nuageinit is typically provided as metadata by the cloud provider. The metadata is presented to nuageinit in different forms depending on the provider:

nocloud

If the data is provided via a disk labelled cidata, then the metadata is provided in the form of a file named meta-data in YAML format. nuageinit will configure the hostname of the instance according to the value of the following variables local-hostname or hostname.

config-2

If the data is provided via a disk labelled config-2 or if it is fetched from OpenStack, the metadata is expected in two json files:

The meta_data.json file supports the following keys:

hostname

Set the hostname of the instance.

public_keys

Append each entry of the array to nuageinit default user which will be created.

The network_data.json file supports the following keys:

links

Array of network interfaces to be configured.

networks

Array of network configurations to be set.

services

Array of service configurations to be set (e.g: DNS).

Along with the metadata, a user data file is provided, either named user_data or user-data. If this file starts with a "#!", it will be executed at the end of the boot via nuageinit_user_data_script. If this file starts with "#cloud-config", it will be parsed as a YAML configuration file. All other cases will be ignored.

The "#cloud-config" configuration entries supported by nuageinit:

fqdn

Specify a fully qualified domain name for the instance.

hostname

Specify the hostname of the instance if "fqdn" is not set.

timezone

Sets the system timezone based on the value provided.

See also tzfile(5).

groups

An array of strings or objects to be created:

• If the entry is a string, a group using this string as a name will be created.
• if the entry is an object, the "key" will be used as the name of the group, the "value" is expected to be a list of members (array), specified by name.

ssh_keys

An object of multiple key/values, "keys" being in the form algo_private or algo_public, "values" being the actual content of the files in /etc/ssh.

ssh_authorized_keys

Append each entry of the array to nuageinit default user which will be created.

ssh_pwauth

boolean which determines the value of the "PasswordAuthentication" configuration in /etc/ssh/sshd_config

network

Network configuration parameters.

Specifying the following parameters from a file named network-config takes precedence over their specification from the network parameter of user-data.

ethernets

Mapping representing a generic configuration for existing network interfaces.

Each key is an interface name that is only used when no match rule is specified. If match rules are specified, an arbitrary name can be used (e.g.: id0).

match

This selects a subset of available physical devices by various hardware properties. The following configuration will then apply to all matching devices, as soon as they appear. All specified properties must match. The following properties for creating matches are supported:

macaddress

Device's MAC address in the form xx:xx:xx:xx:xx:xx. Letters should be lowercase.

name

Current interface name. Lua pattern-matching expressions are supported.

driver

Interface driver name and unit number of the interface. Lua pattern-natching expressions are supported.

set-name

When matching on unique properties such as MAC, match rules can be written so that they match only one device. Then this property can be used to give that device a more specific/desirable/nicer name than the default.

While multiple properties can be used in a match, macaddress is required for nuageinit to perform the rename.

mtu

The MTU key represents a device's Maximum Transmission Unit, the largest size packet or frame.

wakeonlan

Enable wake on LAN. Off by default.

dhcp4

Configure the interface to use DHCP.

This takes precedence over addresses when both are specified.

addresses

List of strings representing IPv4 or IPv6 addresses.

gateway4

Set default gateway for IPv4, for manual address configuration. This requires setting addresses too.

Since only one default router can be configured at a time, this parameter is applied when processing the first entry, and any others are silently ignored.

gateway6

Set default gateway for IPv6, for manual address configuration. This requires setting addresses too.

Since only one default router can be configured at a time, this parameter is applied when processing the first entry, and any others are silently ignored.

nameservers

Set DNS servers and search domains, for manual address configuration.

There are two supported fields:

search

Search list for host-name lookup.

addresses

List of IPv4 or IPv6 name server addresses that the resolver should query.

runcmd

An array of commands to be run at the end of the boot process

packages

List of packages to be installed.

package_update

Update the remote package metadata.

package_upgrade

Upgrade the packages installed to their latest version.

users

Specify a list of users to be created:

name

Name of the user.

gecos

GECOS for the user.

homedir

The path of the home directory for the user.

primary_group

The main group the user should belong to.

groups

The list of other groups the user should belong to.

no_create_home

A boolean which determines if the home directory should be created or not.

shell

The shell that should be used for the user.

ssh_authorized_keys

List of SSH keys for the user.

passwd

The encrypted password for the user.

plain_text_passwd

The password in plain text for the user. Ignored if an encrypted password is already provided.

locked

Boolean to determine if the user account should be locked.

sudo

A string or an array of strings which should be appended to ${LOCALBASE}/etc/sudoers.d/90-nuageinit-users

doas

A string or an array of strings which should be appended to ${LOCALBASE}/etc/doas.conf

Instead of hardcoding the username, you can use %u, which will be replaced by the current username.

A special case exist: if the entry is a simple string with the value "default", then the default user is created. Configuring sudo or doas does not automatically install them. Ensure the relevant command is listed in your packages section.

chpasswd

Change the passwords for users, it accepts the following keys:

expire

Boolean to force the user to change their password on first login.

users

An array of objects:

name

Specify the user whose password will be changed.

password

Specify a text line with the new password or "RANDOM" to assign the password randomly. If the textline starts with "$x$" where x is a number, then the password is considered encrypted, otherwise the password is considered plaintext.

write_files

An array of objects representing files to be created at first boot. The files are being created before the installation of any packages and the creation of the users. The only mandatory field is: path. It accepts the following keys for each objects:

content

The content to be written to the file. If this key is not existing then an empty file will be created.

encoding

Specify the encoding used for content. If not specified, then plain text is considered. Only b64 and base64 are supported for now.

path

The path of the file to be created. (Note intermerdiary directories will not be created).

permissions

A string representing the permission of the file in octal.

owner

A string representing the owner, two forms are possible: user or user:group.

append

A boolean to specify the content should be appended to the file if the file exists.

defer

A boolean to specify that the files should be created after the packages are installed and the users are created.

EXAMPLES

Here is an example of a YAML configuration for nuageinit:

#cloud-config
fqdn: myhost.mynetwork.tld
users:
  - default
  - name: user
    gecos: Foo B. Bar
    sudo: ALL=(ALL) NOPASSWD:ALL
    ssh_authorized_keys:
      - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr...
packages:
  - neovim
  - git-lite
  - sudo
package_update: true
package_upgrade: true
runcmd:
  - logger -t nuageinit "boot finished"
ssh_keys:
  ed25519_private: |
    -----BEGIN OPENSSH PRIVATE KEY-----
    blabla
    ...
    -----END OPENSSH PRIVATE KEY-----
  ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+
network:
  ethernets:
    vtnet0:
      addresses:
        - 192.168.8.2/24
      gateway4: 192.168.8.1

SEE ALSO

kenv(2), cd9660(4), msdosfs(4), smbios(4), ssh_config(5), rc(8)

STANDARDS

nuageinit is believed to conform to the Cloud Init specification.

HISTORY

nuageinit appeared in FreeBSD 14.1