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