1.\" SPDX-License-Identifier: BSD-2-Clause 2.\" 3.\" Copyright (c) 2025 Baptiste Daroussin <bapt@FreeBSD.org> 4.\" 5.Dd June 16, 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 214An entry 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.El 243.Sh EXAMPLES 244Here is an example of a YAML configuration for 245.Nm : 246.Bd -literal 247#cloud-config 248fqdn: myhost.mynetwork.tld 249users: 250 - default 251 - name: user 252 gecos: Foo B. Bar 253 sudo: ALL=(ALL) NOPASSWD:ALL 254 ssh-authorized-keys: 255 - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... 256packages: 257 - neovim 258 - git-lite 259package_update: true 260package_upgrade: true 261runcmd: 262 - logger -t nuageinit "boot finished" 263ssh_keys: 264 ed25519_private: | 265 -----BEGIN OPENSSH PRIVATE KEY----- 266 blabla 267 ... 268 -----END OPENSSH PRIVATE KEY----- 269 ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ 270.Ed 271.Sh SEE ALSO 272.Xr kenv 2 , 273.Xr cd9660 4 , 274.Xr msdosfs 4 , 275.Xr smbios 4 , 276.Xr ssh_config 5 , 277.Xr rc 8 278.Sh STANDARDS 279.Nm 280is believed to conform to the 281.Lk https://cloud-init.io/ Cloud Init 282specification. 283.Sh HISTORY 284.Nm 285appeared in 286.Fx 14.1 287