NUAGEINIT(7)

🎀 NAME 🎀

okay so bestie, this is nuageinit(7) — the manual page for initializing a cloud-init environment. It's giving “first boot gets a glow-up” energy, and honestly? iconic. 💅

🦋 DESCRIPTION 🦋

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

• nuageinit — this script detects the type of cloud environment and gathers the configuration data accordingly. The cloud environments supported right now are:
  • 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 these filesystems: cd9660(4) or msdosfs(4), and it must be labelled (via filesystem label) either config-2 or cidata.
  • OpenStack — the system is running in an OpenStack environment: https://www.openstack.org/. It's 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. yes bestie, that's the whole vibe. 🫶

---

✨ 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 the 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 are:

• 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, and 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 the 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 for the user, in plain text. Ignored if an encrypted password is already provided, so like… don't fight yourself, bestie 💅
• locked — a boolean that decides whether the user account should be locked 🔒
• sudo — a string, or an array of strings, which gets appended to ${LOCALBASE}/etc/sudoers.d/90-nuageinit-users
• doas — a string, or an array of strings, which gets appended to ${LOCALBASE}/etc/doas.conf

Instead of hardcoding the username, you can use %u, which gets replaced by the current username. iykyk ✨

There's one special case, and it's kind of iconic: if the entry is a simple string with the value "default", then the default user is created 👑

⚠️ Setting up sudo or doas does not automatically install them. Not you forgetting the packages section 😭 — make sure the relevant command is listed in your packages section, fr fr.

chpasswd — changes the passwords for users. It accepts these keys:

• expire — a boolean that forces the user to change their password on first login 🫶
• users — an array of objects:
  • name — specifies which user's password will be changed.
  • password — a text line with the new password, or "RANDOM" to assign the password randomly. If the text line starts with "$x$", where x is a number, then the password is considered encrypted; otherwise the password is considered plaintext. vibe check: enc or not enc 🦋

write_files — an array of objects representing files to be created at first boot. The way these files get created before the installation of any packages and before the users are created… order matters, periodt 🌸 The only mandatory field is path. Each object accepts the following keys:

• content — the content to be written to the file. If this key doesn't exist, then an empty file will be created 📄
• encoding — the encoding used for content. If it's not specified, then plain text is assumed. Only b64 and base64 are supported for now.
• path — the path of the file to be created. (Note: intermediary directories will not be created 🙈 so build those yourself)
• 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 specifying that the content should be appended to the file if the file already exists.
• defer — a boolean specifying that the files should be created after the packages are installed and the users are created ⏳

---

🎀 EXAMPLES 🎀

Here's an example of a YAML configuration for nuageinit, bestie — live a little:

#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

Look at that. Gorgeous. No notes. 💖

---

🌈 SEE ALSO 🌈

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

Go read them, they're literally right there 🫶

---

⭐ STANDARDS ⭐

nuageinit is believed to conform to the Cloud Init: https://cloud-init.io/ specification. "believed to" is doing so much work in that sentence and I respect it 👑

---

🦋 HISTORY 🦋

nuageinit appeared in FreeBSD 14.1 🌱

---

okay that's the whole page, you ate that 💅 This one's from the Debian crew, dated February 26, 2026, and it's filed under NUAGEINIT(7) — go forth and cloud-init, bestie 😭🔥🎀