1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2025 Baptiste Daroussin <bapt@FreeBSD.org> 4.\" Copyright (c) 2025 Jesús Daniel Colmenares Oviedo <dtxdf@FreeBSD.org> 5.\" 6.Dd January 6, 2026 7.Dt NUAGEINIT 7 8.Os 9.Sh NAME 10.Nm nuageinit 11.Nd initialize a cloud-init environment 12.Sh DESCRIPTION 13The 14.Nm 15program is used to initialize instances in a cloud environment. 16.Nm 17runs at the first boot after the system installation. 18It is composed of three 19.Xr rc 8 20scripts: 21.Bl -tag -width "nuageinit" 22.It Cm nuageinit 23This script detects the type of cloud environment and gathers 24the configuration data accordingly. 25The following cloud environments are supported right now: 26.Bl -tag -width "OpenStack" 27.It ondisk 28A cloud agnostic environment where the disk is provided to the system 29with the configuration data on it. 30The disk must be formatted using one of the following filesystems: 31.Xr cd9660 4 32or 33.Xr msdosfs 4 34and be labelled (via filesystem label) either 35.Ar config-2 36or 37.Ar cidata . 38.It OpenStack 39The system is running in an 40.Lk https://www.openstack.org/ OpenStack environment . 41It is detected via the 42.Ar smbios.system.product 43.Xr smbios 4 44description available in 45.Xr kenv 2 . 46.El 47.Pp 48Depending on the cloud environment above, 49.Nm 50will attempt to configure the instance. 51This script executes early 52after all the local filesystem are mounted but before 53the network is configured. 54.It Cm nuageinit_post_net 55This script is responsible for processing the configurations that are network 56dependent: 57.Bl -bullet 58.It 59dealing with packages 60.It 61dealing with users (which can depend on shell provided by packages) 62.El 63.It Cm nuageinit_user_data_script 64This script is responsible for executing everything which would have 65been passed via the configuration to be executed, via the configuration 66or because the user_data provided is a script. 67.El 68.Pp 69The default user for nuageinit is a user named 70.Va freebsd 71with a password set to 72.Va freebsd 73and a login shell set to 74.Va /bin/sh . 75.Sh CONFIGURATION 76The configuration of 77.Nm 78is typically provided as metadata by the cloud provider. 79The metadata is presented to nuageinit in different forms depending on 80the provider: 81.Bl -tag -width "config-2" 82.It nocloud 83If the data is provided via a disk labelled 84.Va cidata , 85then the metadata is provided in the form of a file named 86.Pa meta-data 87in YAML format. 88.Nm 89will configure the hostname of the instance according to the value of the 90following variables 91.Va local-hostname 92or 93.Va hostname . 94.It config-2 95If the data is provided via a disk labelled 96.Va config-2 97or if it is fetched from OpenStack, 98the metadata is expected in two json files: 99.Pp 100The 101.Pa meta_data.json 102file supports the following keys: 103.Bl -tag -width "public_keys" 104.It Ic hostname 105Set the hostname of the instance. 106.It Ic public_keys 107Append each entry of the array to 108.Nm 109default user which will be created. 110.El 111.Pp 112The 113.Pa network_data.json 114file supports the following keys: 115.Bl -tag -width "public_keys" 116.It Ic links 117Array of network interfaces to be configured. 118.It Ic networks 119Array of network configurations to be set. 120.It Ic services 121Array of service configurations to be set (e.g: DNS). 122.El 123.El 124.Pp 125Along with the metadata, a user data file is provided, either named 126.Pa user_data 127or 128.Pa user-data . 129If this file starts with a 130.Qq #! , 131it will be executed at the end of the boot via 132.Cm nuageinit_user_data_script . 133If this file starts with 134.Qq #cloud-config , 135it will be parsed as a YAML configuration file. 136All other cases will be ignored. 137.Pp 138The 139.Qq #cloud-config 140configuration entries supported by 141.Nm : 142.Bl -tag -width "config-2" 143.It Ic fqdn 144Specify a fully qualified domain name for the instance. 145.It Ic hostname 146Specify the hostname of the instance if 147.Qq Ic fqdn 148is not set. 149.It Ic timezone 150Sets the system timezone based on the value provided. 151.Pp 152See also 153.Xr tzfile 5 . 154.It Ic groups 155An array of strings or objects to be created: 156.Bl -bullet 157.It 158If the entry is a string, 159a group using this string as a name will be created. 160.It 161if the entry is an object, the 162.Qq Ar key 163will be used as the name of the group, the 164.Qq Ar value 165is expected to be a list of members (array), specified by name. 166.El 167.It Ic ssh_keys 168An object of multiple key/values, 169.Qq Cm keys 170being in the form 171.Ar algo_private 172or 173.Ar algo_public , 174.Qq Cm values 175being the actual content of the files in 176.Pa /etc/ssh . 177.It Ic ssh_authorized_keys 178Append each entry of the array to 179.Nm 180default user which will be created. 181.It Ic ssh_pwauth 182boolean which determines the value of the 183.Qq Ic PasswordAuthentication 184configuration in 185.Pa /etc/ssh/sshd_config 186.It Ic network 187Network configuration parameters. 188.Pp 189Specifying the following parameters from a file named 190.Pa network-config 191takes precedence over their specification from the 192.Ic network 193parameter of 194.Pa user-data . 195.Bl -tag -width "ethernets" 196.It Ic ethernets 197Mapping representing a generic configuration for existing network interfaces. 198.Pp 199Each key is an interface name that is only used when no 200.Sy match 201rule is specified. 202If 203.Sy match 204rules are specified, an arbitrary name can be used 205.Po e.g.: id0 Pc . 206.Bl -tag -width "nameservers" 207.It Ic match 208This selects a subset of available physical devices by various hardware 209properties. 210The following configuration will then apply to all matching devices, as soon as 211they appear. 212All specified properties must match. 213The following properties for 214creating matches are supported: 215.Bl -tag -width "macaddress" 216.It Ic macaddress 217.No Device's MAC address in the form Sy xx:xx:xx:xx:xx:xx . 218Letters should be lowercase. 219.It Ic name 220Current interface name. 221Lua pattern-matching expressions are supported. 222.It Ic driver 223Interface driver name and unit number of the interface. 224Lua pattern-natching expressions 225are supported. 226.El 227.It Ic set-name 228When matching on unique properties such as MAC, match rules can be written so 229that they match only one device. 230Then this property can be used to give that device a more 231specific/desirable/nicer name than the default. 232.Pp 233While multiple properties can be used in a match, 234.Sy macaddress 235is required for nuageinit to perform the rename. 236.It Ic mtu 237The MTU key represents a device's Maximum Transmission Unit, the largest size 238packet or frame. 239.It Ic wakeonlan 240Enable wake on LAN. 241Off by default. 242.It Ic dhcp4 243Configure the interface to use DHCP. 244.Pp 245This takes precedence over 246.Sy addresses 247when both are specified. 248.It Ic addresses 249List of strings representing IPv4 or IPv6 addresses. 250.It Ic gateway4 251Set default gateway for IPv4, for manual address configuration. 252This requires setting 253.Sy addresses 254too. 255.Pp 256Since only one default router can be configured at a time, this parameter is 257applied when processing the first entry, and any others are silently ignored. 258.It Ic gateway6 259Set default gateway for IPv6, for manual address configuration. 260This requires setting 261.Sy addresses 262too. 263.Pp 264Since only one default router can be configured at a time, this parameter is 265applied when processing the first entry, and any others are silently ignored. 266.It Ic nameservers 267Set DNS servers and search domains, for manual address configuration. 268.Pp 269There are two supported fields: 270.Bl -tag -width "addresses" 271.It Ic search 272Search list for host-name lookup. 273.It Ic addresses 274List of IPv4 or IPv6 name server addresses that the resolver should query. 275.El 276.El 277.El 278.It Ic runcmd 279An array of commands to be run at the end of the boot process 280.It Ic packages 281List of packages to be installed. 282.It Ic package_update 283Update the remote package metadata. 284.It Ic package_upgrade 285Upgrade the packages installed to their latest version. 286.It Ic users 287Specify a list of users to be created: 288.Bl -tag -width "ssh_authorized_keys" 289.It Ic name 290Name of the user. 291.It Ic gecos 292GECOS for the user. 293.It Ic homedir 294The path of the home directory for the user. 295.It Ic primary_group 296The main group the user should belong to. 297.It Ic groups 298The list of other groups the user should belong to. 299.It Ic no_create_home 300A boolean which determines if the home directory should be created or not. 301.It Ic shell 302The shell that should be used for the user. 303.It Ic ssh_authorized_keys 304List of SSH keys for the user. 305.It Ic passwd 306The encrypted password for the user. 307.It Ic plain_text_passwd 308The password in plain text for the user. 309Ignored if an encrypted password is already provided. 310.It Ic locked 311Boolean to determine if the user account should be locked. 312.It Ic sudo 313A string or an array of strings which should be appended to 314.Pa ${LOCALBASE}/etc/sudoers.d/90-nuageinit-users 315.It Ic doas 316A string or an array of strings which should be appended to 317.Pa ${LOCALBASE}/etc/doas.conf 318.Pp 319Instead of hardcoding the username, you can use 320.Sy %u , 321which will be replaced by the current username. 322.El 323.Pp 324A special case exist: if the entry is a simple string with the value 325.Qq default , 326then the default user is created. 327Configuring 328.Nm sudo 329or 330.Nm doas 331does not automatically install them. 332Ensure the relevant command is listed in your 333.Nm packages 334section. 335.It Ic chpasswd 336Change the passwords for users, it accepts the following keys: 337.Bl -tag -width "expire" 338.It Ic expire 339Boolean to force the user to change their password on first login. 340.It Ic users 341An array of objects: 342.Bl -tag -width "password" 343.It Ic user 344Specify the user whose password will be changed. 345.It Ic password 346Specify a text line with the new password or 347specify the user whose password will be changed. 348.Qq Cm RANDOM 349to assign the password randomly. 350If the textline starts with 351.Qq Cm $x$ 352where x is a number, then the password is considered encrypted, 353otherwise the password is considered plaintext. 354.El 355.El 356.It Ic write_files 357An array of objects representing files to be created at first boot. 358The files are being created before the installation of any packages 359and the creation of the users. 360The only mandatory field is: 361.Ic path . 362It accepts the following keys for each objects: 363.Bl -tag -width "permissions" 364.It Ic content 365The content to be written to the file. 366If this key is not existing then an empty file will be created. 367.It Ic encoding 368Specify the encoding used for content. 369If not specified, then plain text is considered. 370Only 371.Ar b64 372and 373.Ar base64 374are supported for now. 375.It Ic path 376The path of the file to be created. 377.Pq Note intermerdiary directories will not be created . 378.It Ic permissions 379A string representing the permission of the file in octal. 380.It Ic owner 381A string representing the owner, two forms are possible: 382.Ar user 383or 384.Ar user:group . 385.It Ic append 386A boolean to specify the content should be appended to the file if the file 387exists. 388.It Ic defer 389A boolean to specify that the files should be created after the packages are 390installed and the users are created. 391.El 392.El 393.Sh EXAMPLES 394Here is an example of a YAML configuration for 395.Nm : 396.Bd -literal 397#cloud-config 398fqdn: myhost.mynetwork.tld 399users: 400 - default 401 - name: user 402 gecos: Foo B. Bar 403 sudo: ALL=(ALL) NOPASSWD:ALL 404 ssh_authorized_keys: 405 - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... 406packages: 407 - neovim 408 - git-lite 409 - sudo 410package_update: true 411package_upgrade: true 412runcmd: 413 - logger -t nuageinit "boot finished" 414ssh_keys: 415 ed25519_private: | 416 -----BEGIN OPENSSH PRIVATE KEY----- 417 blabla 418 ... 419 -----END OPENSSH PRIVATE KEY----- 420 ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ 421network: 422 ethernets: 423 vtnet0: 424 addresses: 425 - 192.168.8.2/24 426 gateway4: 192.168.8.1 427.Ed 428.Sh SEE ALSO 429.Xr kenv 2 , 430.Xr cd9660 4 , 431.Xr msdosfs 4 , 432.Xr smbios 4 , 433.Xr ssh_config 5 , 434.Xr rc 8 435.Sh STANDARDS 436.Nm 437is believed to conform to the 438.Lk https://cloud-init.io/ Cloud Init 439specification. 440.Sh HISTORY 441.Nm 442appeared in 443.Fx 14.1 444