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