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 groups 147An array of strings or objects to be created: 148.Bl -bullet 149.It 150If the entry is a string, 151a group using this string as a name will be created. 152.It 153if the entry is an object, the 154.Qq Ar key 155will be used as the name of the group, the 156.Qq Ar value 157is expected to be a list of members (array), specified by name. 158.El 159.It Ic ssh_keys 160An object of multiple key/values, 161.Qq Cm keys 162being in the form 163.Ar algo_private 164or 165.Ar algo_public , 166.Qq Cm values 167being the actual content of the files in 168.Pa /etc/ssh . 169.It Ic ssh_authorized_keys 170Append each entry of the array to 171.Nm 172default user which will be created. 173.It Ic ssh_pwauth 174boolean which determines the value of the 175.Qq Ic PasswordAuthentication 176configuration in 177.Pa /etc/ssh/sshd_config 178.It Ic network 179.It Ic runcmd 180An array of commands to be run at the end of the boot process 181.It Ic packages 182List of packages to be installed. 183.It Ic package_update 184Update the remote package metadata. 185.It Ic package_upgrade 186Upgrade the packages installed to their latest version. 187.It Ic users 188Specify a list of users to be created: 189.Bl -tag -width "plain_text_passwd" 190.It Ic name 191Name of the user. 192.It Ic gecos 193GECOS for the user. 194.It Ic homedir 195The path of the home directory for the user. 196.It Ic primary_group 197The main group the user should belong to. 198.It Ic groups 199The list of other groups the user should belong to. 200.It Ic no_create_home 201A boolean which determines if the home directory should be created or not. 202.It Ic shell 203The shell that should be used for the user. 204.It Ic passwd 205The encrypted password for the user. 206.It Ic plain_text_passwd 207The password in plain text for the user. 208Ignored if an encrypted password is already provided. 209.It Ic groups 210The list of other groups the user should belong to. 211.It Ic locked 212Boolean to determine if the user account should be locked. 213.It Ic sudo 214A string or an array of strings which which should be appended to 215.Pa /usr/local/etc/sudoers.d/90-nuageinit-users 216.El 217.Pp 218A special case exist: if the entry is a simple string with the value 219.Qq default , 220then the default user is created. 221.It Ic chpasswd 222Change the passwords for users, it accepts the following keys: 223.Bl -tag -width "expire" 224.It Ic expire 225Boolean to force the user to change their password on first login. 226.It Ic users 227An array of objects: 228.Bl -tag -width "password" 229.It Ic user 230Specify the user whose password will be changed. 231.It Ic password 232Specify a text line with the new password or 233specify the user whose password will be changed. 234.Qq Cm RANDOM 235to assign the password randomly. 236If the textline starts with 237.Qq Cm $x$ 238where x is a number, then the password is considered encrypted, 239otherwise the password is considered plaintext. 240.El 241.El 242.It Ic write_files 243An array of objects representing files to be created at first boot. 244The files are being created before the installation of any packages 245and the creation of the users. 246The only mandatory field is: 247.Ic path . 248It accepts the following keys for each objects: 249.Bl -tag -width "permissions" 250.It Ic content 251The content to be written to the file. 252If this key is not existing then an empty file will be created. 253.It Ic encoding 254Specifiy the encoding used for content. 255If not specified, then plain text is considered. 256Only 257.Ar b64 258and 259.Ar base64 260are supported for now. 261.It Ic path 262The path of the file to be created. 263.Pq Note intermerdiary directories will not be created . 264.It Ic permissions 265A string representing the permission of the file in octal. 266.It Ic owner 267A string representing the owner, two forms are possible: 268.Ar user 269or 270.Ar user:group . 271.It Ic append 272A boolean to specify the content should be appended to the file if the file 273exists. 274.It Ic defer 275A boolean to specify that the files should be created after the packages are 276installed and the users are created. 277.El 278.El 279.Sh EXAMPLES 280Here is an example of a YAML configuration for 281.Nm : 282.Bd -literal 283#cloud-config 284fqdn: myhost.mynetwork.tld 285users: 286 - default 287 - name: user 288 gecos: Foo B. Bar 289 sudo: ALL=(ALL) NOPASSWD:ALL 290 ssh-authorized-keys: 291 - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... 292packages: 293 - neovim 294 - git-lite 295package_update: true 296package_upgrade: true 297runcmd: 298 - logger -t nuageinit "boot finished" 299ssh_keys: 300 ed25519_private: | 301 -----BEGIN OPENSSH PRIVATE KEY----- 302 blabla 303 ... 304 -----END OPENSSH PRIVATE KEY----- 305 ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ 306.Ed 307.Sh SEE ALSO 308.Xr kenv 2 , 309.Xr cd9660 4 , 310.Xr msdosfs 4 , 311.Xr smbios 4 , 312.Xr ssh_config 5 , 313.Xr rc 8 314.Sh STANDARDS 315.Nm 316is believed to conform to the 317.Lk https://cloud-init.io/ Cloud Init 318specification. 319.Sh HISTORY 320.Nm 321appeared in 322.Fx 14.1 323