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 June 26, 2025 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.El 121.El 122.Pp 123Along with the metadata, a user data file is provided, either named 124.Pa user_data 125or 126.Pa user-data . 127If this file starts with a 128.Qq #! , 129it will be executed at the end of the boot via 130.Cm nuageinit_user_data_script . 131If this file starts with 132.Qq #!cloud-config , 133it will be parsed as a YAML configuration file. 134All other cases will be ignored. 135.Pp 136The 137.Qq #!cloud-config 138configuration entries supported by 139.Nm : 140.Bl -tag -width "config-2" 141.It Ic fqdn 142Specify a fully qualified domain name for the instance. 143.It Ic hostname 144Specify the hostname of the instance if 145.Qq Ic fqdn 146is not set. 147.It Ic timezone 148Sets the system timezone based on the value provided. 149.Pp 150See also 151.Xr tzfile 3 Ns . 152.It Ic groups 153An array of strings or objects to be created: 154.Bl -bullet 155.It 156If the entry is a string, 157a group using this string as a name will be created. 158.It 159if the entry is an object, the 160.Qq Ar key 161will be used as the name of the group, the 162.Qq Ar value 163is expected to be a list of members (array), specified by name. 164.El 165.It Ic ssh_keys 166An object of multiple key/values, 167.Qq Cm keys 168being in the form 169.Ar algo_private 170or 171.Ar algo_public , 172.Qq Cm values 173being the actual content of the files in 174.Pa /etc/ssh . 175.It Ic ssh_authorized_keys 176Append each entry of the array to 177.Nm 178default user which will be created. 179.It Ic ssh_pwauth 180boolean which determines the value of the 181.Qq Ic PasswordAuthentication 182configuration in 183.Pa /etc/ssh/sshd_config 184.It Ic network 185Network configuration parameters. 186.Pp 187Specifying the following parameters from a file named 188.Pa network-config 189takes precedence over their specification from the 190.Ic network 191parameter of 192.Pa user-data Ns . 193.Bl -tag -width "ethernets" 194.It Ic ethernets 195Mapping representing a generic configuration for existing network interfaces. 196.Pp 197Each key is an interface name that is only used when no 198.Sy match 199rule is specified. 200If 201.Sy match 202rules are specified, an arbitrary name can be used 203.Po e.g.: id0 Pc Ns . 204.Bl -tag -width "nameservers" 205.It Ic match 206This selects a subset of available physical devices by various hardware properties. 207The following configuration will then apply to all matching devices, as soon as 208they appear. 209All specified properties must match. 210The following properties for 211creating matches are supported: 212.Bl -tag -width "macaddress" 213.It Ic macaddress 214.No Device's MAC address in the form Sy xx:xx:xx:xx:xx:xx Ns . 215Letters should be lowercase. 216.It Ic name 217Current interface name. 218Lua pattern-matching expressions are supported. 219.It Ic driver 220Interface driver name and unit number of the interface. 221Lua pattern-natching expressions 222are supported. 223.El 224.It Ic set-name 225When matching on unique properties such as MAC, match rules can be written so that they 226match only one device. 227Then this property can be used to give that device a more 228specific/desirable/nicer name than the default. 229.Pp 230While multiple properties can be used in a match, 231.Sy macaddress 232is required for nuageinit to perform the rename. 233.It Ic mtu 234The MTU key represents a device's Maximum Transmission Unit, the largest size packet 235or frame. 236.It Ic wakeonlan 237Enable wake on LAN. 238Off by default. 239.It Ic dhcp4 240Configure the interface to use DHCP. 241.Pp 242This takes precedence over 243.Sy addresses 244when both are specified. 245.It Ic addresses 246List of strings representing IPv4 or IPv6 addresses. 247.It Ic gateway4 248Set default gateway for IPv4, for manual address configuration. 249This requires setting 250.Sy addresses 251too. 252.Pp 253Since only one default router can be configured at a time, this parameter is applied 254when processing the first entry, and any others are silently ignored. 255.It Ic gateway6 256Set default gateway for IPv6, for manual address configuration. 257This requires setting 258.Sy addresses 259too. 260.Pp 261Since only one default router can be configured at a time, this parameter is applied 262when processing the first entry, and any others are silently ignored. 263.It Ic nameservers 264Set DNS servers and search domains, for manual address configuration. 265.Pp 266There are two supported fields: 267.Bl -tag -width "addresses" 268.It Ic search 269Search list for host-name lookup. 270.It Ic addresses 271List of IPv4 or IPv6 name server addresses that the resolver should query. 272.El 273.El 274.El 275.It Ic runcmd 276An array of commands to be run at the end of the boot process 277.It Ic packages 278List of packages to be installed. 279.It Ic package_update 280Update the remote package metadata. 281.It Ic package_upgrade 282Upgrade the packages installed to their latest version. 283.It Ic users 284Specify a list of users to be created: 285.Bl -tag -width "ssh_authorized_keys" 286.It Ic name 287Name of the user. 288.It Ic gecos 289GECOS for the user. 290.It Ic homedir 291The path of the home directory for the user. 292.It Ic primary_group 293The main group the user should belong to. 294.It Ic groups 295The list of other groups the user should belong to. 296.It Ic no_create_home 297A boolean which determines if the home directory should be created or not. 298.It Ic shell 299The shell that should be used for the user. 300.It Ic ssh_authorized_keys 301List of SSH keys for the user. 302.It Ic passwd 303The encrypted password for the user. 304.It Ic plain_text_passwd 305The password in plain text for the user. 306Ignored if an encrypted password is already provided. 307.It Ic locked 308Boolean to determine if the user account should be locked. 309.It Ic sudo 310A string or an array of strings which should be appended to 311.Pa ${LOCALBASE}/etc/sudoers.d/90-nuageinit-users 312.It Ic doas 313A string or an array of strings which should be appended to 314.Pa ${LOCALBASE}/etc/doas.conf 315.Pp 316Instead of hardcoding the username, you can use 317.Sy %u Ns , 318which will be replaced by the current username. 319.El 320.Pp 321A special case exist: if the entry is a simple string with the value 322.Qq default , 323then the default user is created. 324.It Ic chpasswd 325Change the passwords for users, it accepts the following keys: 326.Bl -tag -width "expire" 327.It Ic expire 328Boolean to force the user to change their password on first login. 329.It Ic users 330An array of objects: 331.Bl -tag -width "password" 332.It Ic user 333Specify the user whose password will be changed. 334.It Ic password 335Specify a text line with the new password or 336specify the user whose password will be changed. 337.Qq Cm RANDOM 338to assign the password randomly. 339If the textline starts with 340.Qq Cm $x$ 341where x is a number, then the password is considered encrypted, 342otherwise the password is considered plaintext. 343.El 344.El 345.It Ic write_files 346An array of objects representing files to be created at first boot. 347The files are being created before the installation of any packages 348and the creation of the users. 349The only mandatory field is: 350.Ic path . 351It accepts the following keys for each objects: 352.Bl -tag -width "permissions" 353.It Ic content 354The content to be written to the file. 355If this key is not existing then an empty file will be created. 356.It Ic encoding 357Specify the encoding used for content. 358If not specified, then plain text is considered. 359Only 360.Ar b64 361and 362.Ar base64 363are supported for now. 364.It Ic path 365The path of the file to be created. 366.Pq Note intermerdiary directories will not be created . 367.It Ic permissions 368A string representing the permission of the file in octal. 369.It Ic owner 370A string representing the owner, two forms are possible: 371.Ar user 372or 373.Ar user:group . 374.It Ic append 375A boolean to specify the content should be appended to the file if the file 376exists. 377.It Ic defer 378A boolean to specify that the files should be created after the packages are 379installed and the users are created. 380.El 381.El 382.Sh EXAMPLES 383Here is an example of a YAML configuration for 384.Nm : 385.Bd -literal 386#cloud-config 387fqdn: myhost.mynetwork.tld 388users: 389 - default 390 - name: user 391 gecos: Foo B. Bar 392 sudo: ALL=(ALL) NOPASSWD:ALL 393 ssh_authorized_keys: 394 - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... 395packages: 396 - neovim 397 - git-lite 398package_update: true 399package_upgrade: true 400runcmd: 401 - logger -t nuageinit "boot finished" 402ssh_keys: 403 ed25519_private: | 404 -----BEGIN OPENSSH PRIVATE KEY----- 405 blabla 406 ... 407 -----END OPENSSH PRIVATE KEY----- 408 ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ 409network: 410 ethernets: 411 vtnet0: 412 addresses: 413 - 192.168.8.2/24 414 gateway4: 192.168.8.1 415.Ed 416.Sh SEE ALSO 417.Xr kenv 2 , 418.Xr cd9660 4 , 419.Xr msdosfs 4 , 420.Xr smbios 4 , 421.Xr ssh_config 5 , 422.Xr rc 8 423.Sh STANDARDS 424.Nm 425is believed to conform to the 426.Lk https://cloud-init.io/ Cloud Init 427specification. 428.Sh HISTORY 429.Nm 430appeared in 431.Fx 14.1 432