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