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 February 26, 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 manage_etc_hosts 150Boolean which determines whether the hostname should be added to 151.Pa /etc/hosts 152on the 153.Qq 127.0.0.1 154and 155.Qq ::1 156localhost lines. 157Defaults to 158.Ar true . 159Set to 160.Ar false 161to skip this behaviour. 162.It Ic mounts 163A list of mount points to configure. 164Each entry is written to 165.Pa /etc/fstab 166and the mount point directory is created. 167.Pp 168Each entry can be specified as a list: 169.Bd -literal -offset indent 170[ device, mountpoint, fstype ] 171.Ed 172.Pp 173or as an object: 174.Bd -literal -offset indent 175{ device: "...", mountpoint: "...", type: "...", options: "..." } 176.Ed 177.Pp 178The following keys are recognized: 179.Bl -tag -width "options" 180.It device (or name, spec) 181The device to mount. 182.It mountpoint (or mount_point) 183The mount point directory. 184.It type (or fstype, filesystem) 185The filesystem type. 186.It options (or opts) 187The mount options, defaults to 188.Qq rw . 189.It dump 190The dump frequency for 191.Xr dump 8 , 192defaults to 0. 193.It passno 194The pass number for 195.Xr fsck 8 , 196defaults to 0. 197.El 198.It Ic resolv_conf 199An object configuring the content of 200.Pa /etc/resolv.conf . 201.Pp 202The following keys are recognized: 203.Bl -tag -width "nameservers" 204.It nameservers 205A list of IP addresses for DNS name servers. 206.It searchdomains 207A list of search domains. 208.It domain 209A single domain name. 210.It sortlist 211A list of IP/netmask sortlist entries. 212.It options 213A dictionary of resolver options. 214.El 215.It Ic keyboard 216An object configuring the keyboard layout. 217.Pp 218Sets the 219.Va keymap 220variable in 221.Pa /etc/rc.conf.d/keymap . 222.Pp 223The following keys are recognized: 224.Bl -tag -width "variant" 225.It layout 226The keyboard layout (e.g., 227.Qq fr , 228.Qq de , 229.Qq us ) . 230.It variant 231The keyboard variant (e.g., 232.Qq acc , 233.Qq nodeadkeys ) . 234.El 235.It Ic ssh_authkey_fingerprints 236Boolean which determines whether fingerprints of SSH host keys 237should be logged to the console. 238Defaults to 239.Ar false . 240.It Ic ntp 241An object configuring the NTP daemon by writing 242.Pa /etc/ntp.conf . 243.Pp 244The following keys are recognized: 245.Bl -tag -width "enabled" 246.It servers 247A list of NTP server addresses. 248.It pools 249A list of NTP pool addresses. 250.It enabled 251Boolean, defaults to 252.Ar true . 253Set to 254.Ar false 255to skip NTP configuration. 256.El 257.Pp 258Alternatively, 259.Ic ntp 260can be a list of server addresses (legacy format). 261.It Ic timezone 262Sets the system timezone based on the value provided. 263.Pp 264See also 265.Xr tzfile 5 . 266.It Ic groups 267An array of strings or objects to be created: 268.Bl -bullet 269.It 270If the entry is a string, 271a group using this string as a name will be created. 272.It 273if the entry is an object, the 274.Qq Ar key 275will be used as the name of the group, the 276.Qq Ar value 277is expected to be a list of members (array), specified by name. 278.El 279.It Ic ssh_deletekeys 280Boolean which determines if the existing SSH host keys in 281.Pa /etc/ssh 282should be removed on first boot. 283New host keys will be generated automatically by 284.Xr sshd 8 . 285.It Ic ssh_keys 286An object of multiple key/values, 287.Qq Cm keys 288being in the form 289.Ar algo_private 290or 291.Ar algo_public , 292.Qq Cm values 293being the actual content of the files in 294.Pa /etc/ssh . 295.It Ic ssh_authorized_keys 296Append each entry of the array to 297.Nm 298default user which will be created. 299.It Ic ssh_pwauth 300boolean which determines the value of the 301.Qq Ic PasswordAuthentication 302configuration in 303.Pa /etc/ssh/sshd_config 304.It Ic disable_root 305Boolean which determines if root login via SSH should be disabled. 306If set to 307.Ar true , 308sets 309.Qq Ic PermitRootLogin 310to 311.Ar no 312.Pq or the value specified in Ic disable_root_opts 313in 314.Pa /etc/ssh/sshd_config . 315.It Ic disable_root_opts 316String or array of options used to set the value of 317.Qq Ic PermitRootLogin 318in 319.Pa /etc/ssh/sshd_config , 320when 321.Ic disable_root 322is set to 323.Ar true . 324If not specified, defaults to 325.Ar no . 326.Pp 327Only the first value is used when an array is provided. 328.It Ic network 329Network configuration parameters. 330.Pp 331Specifying the following parameters from a file named 332.Pa network-config 333takes precedence over their specification from the 334.Ic network 335parameter of 336.Pa user-data . 337.Bl -tag -width "ethernets" 338.It Ic ethernets 339Mapping representing a generic configuration for existing network interfaces. 340.Pp 341Each key is an interface name that is only used when no 342.Sy match 343rule is specified. 344If 345.Sy match 346rules are specified, an arbitrary name can be used 347.Po e.g.: id0 Pc . 348.Bl -tag -width "nameservers" 349.It Ic match 350This selects a subset of available physical devices by various hardware 351properties. 352The following configuration will then apply to all matching devices, as soon as 353they appear. 354All specified properties must match. 355The following properties for 356creating matches are supported: 357.Bl -tag -width "macaddress" 358.It Ic macaddress 359.No Device's MAC address in the form Sy xx:xx:xx:xx:xx:xx . 360Letters should be lowercase. 361.It Ic name 362Current interface name. 363Lua pattern-matching expressions are supported. 364.It Ic driver 365Interface driver name and unit number of the interface. 366Lua pattern-natching expressions 367are supported. 368.El 369.It Ic set-name 370When matching on unique properties such as MAC, match rules can be written so 371that they match only one device. 372Then this property can be used to give that device a more 373specific/desirable/nicer name than the default. 374.Pp 375While multiple properties can be used in a match, 376.Sy macaddress 377is required for nuageinit to perform the rename. 378.It Ic mtu 379The MTU key represents a device's Maximum Transmission Unit, the largest size 380packet or frame. 381.It Ic wakeonlan 382Enable wake on LAN. 383Off by default. 384.It Ic dhcp4 385Configure the interface to use DHCP. 386.Pp 387This takes precedence over 388.Sy addresses 389when both are specified. 390.It Ic addresses 391List of strings representing IPv4 or IPv6 addresses. 392.It Ic gateway4 393Set default gateway for IPv4, for manual address configuration. 394This requires setting 395.Sy addresses 396too. 397.Pp 398Since only one default router can be configured at a time, this parameter is 399applied when processing the first entry, and any others are silently ignored. 400.It Ic gateway6 401Set default gateway for IPv6, for manual address configuration. 402This requires setting 403.Sy addresses 404too. 405.Pp 406Since only one default router can be configured at a time, this parameter is 407applied when processing the first entry, and any others are silently ignored. 408.It Ic nameservers 409Set DNS servers and search domains, for manual address configuration. 410.Pp 411There are two supported fields: 412.Bl -tag -width "addresses" 413.It Ic search 414Search list for host-name lookup. 415.It Ic addresses 416List of IPv4 or IPv6 name server addresses that the resolver should query. 417.El 418.El 419.El 420.It Ic runcmd 421An array of commands to be run at the end of the boot process 422.It Ic packages 423List of packages to be installed. 424.It Ic package_update 425Update the remote package metadata. 426.It Ic package_upgrade 427Upgrade the packages installed to their latest version. 428.It Ic users 429Specify a list of users to be created: 430.Bl -tag -width "ssh_authorized_keys" 431.It Ic name 432Name of the user. 433.It Ic gecos 434GECOS for the user. 435.It Ic homedir 436The path of the home directory for the user. 437.It Ic primary_group 438The main group the user should belong to. 439.It Ic groups 440The list of other groups the user should belong to. 441.It Ic no_create_home 442A boolean which determines if the home directory should be created or not. 443.It Ic shell 444The shell that should be used for the user. 445.It Ic ssh_authorized_keys 446List of SSH keys for the user. 447.It Ic passwd 448The encrypted password for the user. 449.It Ic plain_text_passwd 450The password in plain text for the user. 451Ignored if an encrypted password is already provided. 452.It Ic locked 453Boolean to determine if the user account should be locked. 454.It Ic sudo 455A string or an array of strings which should be appended to 456.Pa ${LOCALBASE}/etc/sudoers.d/90-nuageinit-users 457.It Ic doas 458A string or an array of strings which should be appended to 459.Pa ${LOCALBASE}/etc/doas.conf 460.Pp 461Instead of hardcoding the username, you can use 462.Sy %u , 463which will be replaced by the current username. 464.El 465.Pp 466A special case exist: if the entry is a simple string with the value 467.Qq default , 468then the default user is created. 469Configuring 470.Nm sudo 471or 472.Nm doas 473does not automatically install them. 474Ensure the relevant command is listed in your 475.Nm packages 476section. 477.It Ic bootcmd 478An array of commands to be run early in the boot process, 479before the hostname is set and before the network is configured. 480.It Ic chpasswd 481Change the passwords for users, it accepts the following keys: 482.Bl -tag -width "expire" 483.It Ic expire 484Boolean to force the user to change their password on first login. 485.It Ic users 486An array of objects: 487.Bl -tag -width "password" 488.It Ic name 489Specify the user whose password will be changed. 490.It Ic password 491Specify a text line with the new password or 492.Qq Cm RANDOM 493to assign the password randomly. 494If the textline starts with 495.Qq Cm $x$ 496where x is a number, then the password is considered encrypted, 497otherwise the password is considered plaintext. 498.El 499.El 500.It Ic write_files 501An array of objects representing files to be created at first boot. 502The files are being created before the installation of any packages 503and the creation of the users. 504The only mandatory field is: 505.Ic path . 506It accepts the following keys for each objects: 507.Bl -tag -width "permissions" 508.It Ic content 509The content to be written to the file. 510If this key is not existing then an empty file will be created. 511.It Ic encoding 512Specify the encoding used for content. 513If not specified, then plain text is considered. 514Only 515.Ar b64 516and 517.Ar base64 518are supported for now. 519.It Ic path 520The path of the file to be created. 521.Pq Note intermerdiary directories will not be created . 522.It Ic permissions 523A string representing the permission of the file in octal. 524.It Ic owner 525A string representing the owner, two forms are possible: 526.Ar user 527or 528.Ar user:group . 529.It Ic append 530A boolean to specify the content should be appended to the file if the file 531exists. 532.It Ic defer 533A boolean to specify that the files should be created after the packages are 534installed and the users are created. 535.El 536.El 537.Sh EXAMPLES 538Here is an example of a YAML configuration for 539.Nm : 540.Bd -literal 541#cloud-config 542bootcmd: 543 - kldload if_bridge 544fqdn: myhost.mynetwork.tld 545users: 546 - default 547 - name: user 548 gecos: Foo B. Bar 549 sudo: ALL=(ALL) NOPASSWD:ALL 550 ssh_authorized_keys: 551 - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... 552packages: 553 - neovim 554 - git-lite 555 - sudo 556package_update: true 557package_upgrade: true 558runcmd: 559 - logger -t nuageinit "boot finished" 560ssh_deletekeys: true 561disable_root: true 562ssh_keys: 563 ed25519_private: | 564 -----BEGIN OPENSSH PRIVATE KEY----- 565 blabla 566 ... 567 -----END OPENSSH PRIVATE KEY----- 568 ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ 569network: 570 ethernets: 571 vtnet0: 572 addresses: 573 - 192.168.8.2/24 574 gateway4: 192.168.8.1 575.Ed 576.Sh SEE ALSO 577.Xr kenv 2 , 578.Xr cd9660 4 , 579.Xr msdosfs 4 , 580.Xr smbios 4 , 581.Xr ssh_config 5 , 582.Xr rc 8 583.Sh STANDARDS 584.Nm 585is believed to conform to the 586.Lk https://cloud-init.io/ Cloud Init 587specification. 588.Sh HISTORY 589.Nm 590appeared in 591.Fx 14.1 592