--- name: "nuageinit" section: "7" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/nuageinit" --- # nuageinit(7) initialize a cloud-init environment ## NAME **nuageinit** – initialize a cloud-init environment ## DESCRIPTION The **nuageinit** program is used to initialize instances in a cloud environment. **nuageinit** runs at the first boot after the system installation. It is composed of three [rc(8)](/rc/8.md) scripts: - **nuageinit** This script detects the type of cloud environment and gathers the configuration data accordingly. The following cloud environments are supported right now: - ondisk A cloud agnostic environment where the disk is provided to the system with the configuration data on it. The disk must be formatted using one of the following filesystems: [cd9660(4)](/cd9660/4.md) or [msdosfs(4)](/msdosfs/4.md) and be labelled (via filesystem label) either *config-2* or *cidata*. - OpenStack The system is running in an *OpenStack* *environment:* **https://www.openstack.org/**. It is detected via the *smbios.system.product* [smbios(4)](/smbios/4.md) description available in [kenv(2)](/kenv/2.md). Depending on the cloud environment above, **nuageinit** will attempt to configure the instance. This script executes early after all the local filesystem are mounted but before the network is configured. - **nuageinit\_post\_net** This script is responsible for processing the configurations that are network dependent: - dealing with packages - dealing with users (which can depend on shell provided by packages) - **nuageinit\_user\_data\_script** This script is responsible for executing everything which would have been passed via the configuration to be executed, via the configuration or because the user\_data provided is a script. The default user for nuageinit is a user named *freebsd* with a password set to *freebsd* and a login shell set to */bin/sh*. ## CONFIGURATION The configuration of **nuageinit** is typically provided as metadata by the cloud provider. The metadata is presented to nuageinit in different forms depending on the provider: - nocloud If the data is provided via a disk labelled *cidata*, then the metadata is provided in the form of a file named *meta-data* in YAML format. **nuageinit** will configure the hostname of the instance according to the value of the following variables *local-hostname* or *hostname*. - config-2 If the data is provided via a disk labelled *config-2* or if it is fetched from OpenStack, the metadata is expected in two json files: The *meta\_data.json* file supports the following keys: - **hostname** Set the hostname of the instance. - **public\_keys** Append each entry of the array to **nuageinit** default user which will be created. The *network\_data.json* file supports the following keys: - **links** Array of network interfaces to be configured. - **networks** Array of network configurations to be set. - **services** Array of service configurations to be set (e.g: DNS). Along with the metadata, a user data file is provided, either named *user\_data* or *user-data*. If this file starts with a "#!", it will be executed at the end of the boot via **nuageinit\_user\_data\_script**. If this file starts with "#cloud-config", it will be parsed as a YAML configuration file. All other cases will be ignored. The "#cloud-config" configuration entries supported by **nuageinit**: - **fqdn** Specify a fully qualified domain name for the instance. - **hostname** Specify the hostname of the instance if "**fqdn**" is not set. - **manage\_etc\_hosts** Boolean which determines whether the hostname should be added to */etc/hosts* on the "127.0.0.1" and "::1" localhost lines. Defaults to *true*. Set to *false* to skip this behaviour. - **mounts** A list of mount points to configure. Each entry is written to */etc/fstab* and the mount point directory is created. Each entry can be specified as a list: ``` [ device, mountpoint, fstype ] ``` or as an object: ``` { device: "...", mountpoint: "...", type: "...", options: "..." } ``` The following keys are recognized: - device (or name, spec) The device to mount. - mountpoint (or mount\_point) The mount point directory. - type (or fstype, filesystem) The filesystem type. - options (or opts) The mount options, defaults to "rw". - dump The dump frequency for [dump(8)](/dump/8.md), defaults to 0. - passno The pass number for [fsck(8)](/fsck/8.md), defaults to 0. - **resolv\_conf** An object configuring the content of */etc/resolv.conf*. The following keys are recognized: - nameservers A list of IP addresses for DNS name servers. - searchdomains A list of search domains. - domain A single domain name. - sortlist A list of IP/netmask sortlist entries. - options A dictionary of resolver options. - **locale** Set the system locale by appending "**export**" statements to */etc/profile*. If the value is a string, it is used as the “**LANG**” value. If the value is an object mapping, each key-value pair is exported. - **keyboard** An object configuring the keyboard layout. Sets the *keymap* variable in */etc/rc.conf.d/keymap*. The following keys are recognized: - layout The keyboard layout (e.g., "fr", "de", "us"). - variant The keyboard variant (e.g., "acc", "nodeadkeys"). - **ssh\_authkey\_fingerprints** Boolean which determines whether fingerprints of SSH host keys should be logged to the console. Defaults to *false*. - **ntp** An object configuring the NTP daemon by writing */etc/ntp.conf*. The following keys are recognized: - servers A list of NTP server addresses. - pools A list of NTP pool addresses. - enabled Boolean, defaults to *true*. Set to *false* to skip NTP configuration. Alternatively, **ntp** can be a list of server addresses (legacy format). - **ca\_certs** An object managing CA certificates. The following keys are recognized: - trusted A list of PEM-encoded CA certificates to add to the system trust store. Certificates are written to */usr/share/certs/trusted/* and [certctl(8)](/certctl/8.md) rehash is executed. - remove\_defaults Boolean, if *true*, remove the default CA certificates. - **timezone** Sets the system timezone based on the value provided. See also [tzfile(5)](/tzfile/5.md). - **groups** An array of strings or objects to be created: - If the entry is a string, a group using this string as a name will be created. - if the entry is an object, the "*key*" will be used as the name of the group, the "*value*" is expected to be a list of members (array), specified by name. - **ssh\_deletekeys** Boolean which determines if the existing SSH host keys in */etc/ssh* should be removed on first boot. New host keys will be generated automatically by [sshd(8)](/sshd/8.md). - **ssh\_keys** An object of multiple key/values, "**keys**" being in the form *algo\_private* or *algo\_public*, "**values**" being the actual content of the files in */etc/ssh*. - **ssh\_authorized\_keys** Append each entry of the array to **nuageinit** default user which will be created. - **allow\_public\_ssh\_keys** Boolean which determines if the public SSH keys from the datasource metadata are imported to the default user and root. If set to *false*, only the keys specified in **ssh\_authorized\_keys** are used. Defaults to *true*. - **ssh\_pwauth** boolean which determines the value of the "**PasswordAuthentication**" configuration in */etc/ssh/sshd\_config* - **disable\_root** Boolean which determines if root login via SSH should be disabled. If set to *true* (the default), the public SSH keys are written to */root/.ssh/authorized\_keys* with the options specified in **disable\_root\_opts**, which by default redirects the login to the default user. If set to *false*, the public SSH keys are written to */root/.ssh/authorized\_keys* without any restriction. - **disable\_root\_opts** String or array of options used to prefix the public SSH keys in */root/.ssh/authorized\_keys* when **disable\_root** is set to *true*. The *$USER* and *$DISABLE\_USER* placeholders are replaced with the default user name and *root* respectively. If not specified, defaults to *no-port-forwarding,no-agent-forwarding,no-X11-forwarding,command="echo* *'Please* *login* *as* *the* *user* *$USER* *rather* *than* *the* *user* *$DISABLE\_USER* *.';echo;sleep* *10;exit* *142"*. Only the first value is used when an array is provided. - **network** Network configuration parameters. Specifying the following parameters from a file named *network-config* takes precedence over their specification from the **network** parameter of *user-data*. - **ethernets** Mapping representing a generic configuration for existing network interfaces. Each key is an interface name that is only used when no **match** rule is specified. If **match** rules are specified, an arbitrary name can be used (e.g.: id0). - **match** This selects a subset of available physical devices by various hardware properties. The following configuration will then apply to all matching devices, as soon as they appear. All specified properties must match. The following properties for creating matches are supported: - **macaddress** Device's MAC address in the form **xx:xx:xx:xx:xx:xx**. Letters should be lowercase. - **name** Current interface name. Lua pattern-matching expressions are supported. - **driver** Interface driver name and unit number of the interface. Lua pattern-natching expressions are supported. - **set-name** When matching on unique properties such as MAC, match rules can be written so that they match only one device. Then this property can be used to give that device a more specific/desirable/nicer name than the default. While multiple properties can be used in a match, **macaddress** is required for nuageinit to perform the rename. - **mtu** The MTU key represents a device's Maximum Transmission Unit, the largest size packet or frame. - **wakeonlan** Enable wake on LAN. Off by default. - **dhcp4** Configure the interface to use DHCP. This takes precedence over **addresses** when both are specified. - **addresses** List of strings representing IPv4 or IPv6 addresses. - **gateway4** Set default gateway for IPv4, for manual address configuration. This requires setting **addresses** too. Since only one default router can be configured at a time, this parameter is applied when processing the first entry, and any others are silently ignored. - **gateway6** Set default gateway for IPv6, for manual address configuration. This requires setting **addresses** too. Since only one default router can be configured at a time, this parameter is applied when processing the first entry, and any others are silently ignored. - **nameservers** Set DNS servers and search domains, for manual address configuration. There are two supported fields: - **search** Search list for host-name lookup. - **addresses** List of IPv4 or IPv6 name server addresses that the resolver should query. - **runcmd** An array of commands to be run at the end of the boot process - **packages** List of packages to be installed. - **package\_update** Update the remote package metadata. - **package\_upgrade** Upgrade the packages installed to their latest version. - **power\_state** An object controlling the power state of the instance after configuration. The following keys are recognized: - **delay** Time to wait before the action. Can be "now" or a time accepted by [shutdown(8)](/shutdown/8.md) (e.g., "+5" for five minutes). Defaults to "now". - **mode** The action to take: "poweroff", "reboot", or "halt". Defaults to "poweroff". - **message** Optional message to display to users. - **timeout** Not supported on FreeBSD, silently ignored. - **condition** Boolean or command string. If "false", the action is skipped. If a string, it is run as a command; the action is only taken if the command succeeds. Defaults to "true". - **phone\_home** An object configuring the posting of instance data to a URL. The following keys are recognized: - **url** The target URL to which the data will be posted. - **post** A list of data items to send, or the string "all" to send all supported items. Supported items are: "hostname", "fqdn", "instance\_id", "pub\_key\_rsa", "pub\_key\_ecdsa", and "pub\_key\_ed25519". - **tries** Number of retry attempts. Defaults to 1. The data is posted using [fetch(1)](/fetch/1.md). - **final\_message** A string message to be displayed at the end of the boot process. The placeholder "$UPTIME" is replaced with the system uptime in seconds. - **users** Specify a list of users to be created: - **name** Name of the user. - **gecos** GECOS for the user. - **homedir** The path of the home directory for the user. - **primary\_group** The main group the user should belong to. - **groups** The list of other groups the user should belong to. - **no\_create\_home** A boolean which determines if the home directory should be created or not. - **shell** The shell that should be used for the user. - **ssh\_authorized\_keys** List of SSH keys for the user. - **passwd** The encrypted password for the user. - **plain\_text\_passwd** The password in plain text for the user. Ignored if an encrypted password is already provided. - **lock\_passwd** Boolean to determine if the user account should be locked. The legacy **locked** key is also accepted. - **sudo** A string or an array of strings which should be appended to *${LOCALBASE}/etc/sudoers.d/90-nuageinit-users* - **doas** A string or an array of strings which should be appended to *${LOCALBASE}/etc/doas.conf* Instead of hardcoding the username, you can use **%u**, which will be replaced by the current username. A special case exist: if the entry is a simple string with the value "default", then the default user is created. Configuring **sudo** or **doas** does not automatically install them. Ensure the relevant command is listed in your **packages** section. - **bootcmd** An array of commands to be run early in the boot process, before the hostname is set and before the network is configured. - **chpasswd** Change the passwords for users, it accepts the following keys: - **expire** Boolean to force the user to change their password on first login. - **users** An array of objects: - **name** Specify the user whose password will be changed. - **password** Specify a text line with the new password or "**RANDOM**" to assign the password randomly. If the textline starts with "**$x$**" where x is a number, then the password is considered encrypted, otherwise the password is considered plaintext. - **write\_files** An array of objects representing files to be created at first boot. The files are being created before the installation of any packages and the creation of the users. The only mandatory field is: **path**. It accepts the following keys for each objects: - **content** The content to be written to the file. If this key is not existing then an empty file will be created. - **encoding** Specify the encoding used for content. If not specified, then plain text is considered. Only *b64* and *base64* are supported for now. - **path** The path of the file to be created. (Note intermerdiary directories will be created). - **permissions** A string representing the permission of the file in octal. - **owner** A string representing the owner, two forms are possible: *user* or *user:group*. - **append** A boolean to specify the content should be appended to the file if the file exists. - **defer** A boolean to specify that the files should be created after the packages are installed and the users are created. Additionally, user-data can be provided as a MIME multipart message with content type "multipart/mixed". Each part is handled according to its "Content-Type" header. Supported part types: - text/cloud-config Processed as a cloud-config YAML document. - text/x-shellscript Saved as an executable script for later execution. ## EXAMPLES Here is an example of a YAML configuration for **nuageinit**: ``` #cloud-config bootcmd: - kldload if_bridge fqdn: myhost.mynetwork.tld users: - default - name: user gecos: Foo B. Bar sudo: ALL=(ALL) NOPASSWD:ALL ssh_authorized_keys: - ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAr... packages: - neovim - git-lite - sudo package_update: true package_upgrade: true runcmd: - logger -t nuageinit "boot finished" ssh_deletekeys: true disable_root: true ssh_keys: ed25519_private: | -----BEGIN OPENSSH PRIVATE KEY----- blabla ... -----END OPENSSH PRIVATE KEY----- ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ network: ethernets: vtnet0: addresses: - 192.168.8.2/24 gateway4: 192.168.8.1 ``` ## SEE ALSO [kenv(2)](/kenv/2.md), [cd9660(4)](/cd9660/4.md), [msdosfs(4)](/msdosfs/4.md), [smbios(4)](/smbios/4.md), [ssh\_config(5)](/ssh_config/5.md), [rc(8)](/rc/8.md) ## STANDARDS **nuageinit** is believed to conform to the *Cloud* *Init:* **https://cloud-init.io/** specification. ## HISTORY **nuageinit** appeared in FreeBSD 14.1