From nobody Tue Jun 17 06:54:43 2025 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bLyKb4K7mz5pxSJ; Tue, 17 Jun 2025 06:54:43 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bLyKb3d0Yz3Nlb; Tue, 17 Jun 2025 06:54:43 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750143283; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=9EC90CVmJ26BRtbjxl58zsUG5HObX/cdGDTVVJjtkII=; b=t4DAMqTyEtpotZzTsJ0UUfSO+1C4YAS/UL32xP/5spLantZCf6uflxvIjT/WxZlX0BTfsm n7NIJMcmgFnqXiSGpWAYSufh8Mk/P91EOzf2sTQ1DtnmPT+uAFe0AKGl4Zucqq79KgSKHS 9yShk6k313mlX1EY4sbkHvcfVR9nRfw2BVAda8qPEMn2ZGnZwqfDb2SrF5Tza1shqO/U5S k9k7ohYycFLr0hEWZex1nQBg8Zui2m53L9N9I25CwKQBmq0f+eTU1K+83WU7gwrntFH0Zj DwzL4x1LuWtxI5DdMoUd/cuuzm4Ibk+WZIXYowXxEaqBlgNjJ5d/0XzPPL5BkQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750143283; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=9EC90CVmJ26BRtbjxl58zsUG5HObX/cdGDTVVJjtkII=; b=a8zQNDNrhNeLkBZm6cjBDtzCKddERKjyOA3hzqGlPKXXROP+J9RTUvlZ6rRoZ6CnZTCy4V rcQfCf+ZlxOg6uP7+nTYqvfhU61YbtZUhWAwbysFIESWpH7q1SOZNHOwrqEQVPH89jOYgh 0MTVWo4jb5K8K8jLUQ8AfKl+Tuvi0alzx8jsxpPjnX4pMTTMDgiNABi/jEU7sajQAPFfbf fHufQO5rmNcLy128UU6sK9OtAo7OKZp792rgV2VD+kUaB0ZL2UfAA2iiBYo0CsCBx778P4 iEz3oQ7+e1mM9Zsdt4jZnjMFCGsNT4BGKX8SdKN0NjQyySua14eIt8G5o98+NA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1750143283; a=rsa-sha256; cv=none; b=HJlusaZhy9xrhinxYKBmz5Gwr08RoUzD3F1rDb9gFNoZldt5TtRXTJ/vd6H69raQ9xRlNg 12kFNDH/ifag7/IjK2fWIKQBgwz8pWhPyiVxdER+U5/LLWx7fT2Lh8PyKtFmtC7FRjwAur 4soZZJ5tdv5ln2+pEVBUfIS/35E4I0eiJLynwKqrjjYMb4NchcYkRLmxizHOdu+iz8Tizf pjKjQhRDyqd+BvBktAwuo2edRaHjnl0mb5N+Bz7TX3LI01OxgFa8Xg0+Zlm7K5LNjRQeCM E2HbMO4AT53yjK23srpvxfJNn66NRf+b1Cxuse32Lr/LVgxh0AEN9ePCXPL2/g== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bLyKb3Cd0zZSr; Tue, 17 Jun 2025 06:54:43 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 55H6shVq024563; Tue, 17 Jun 2025 06:54:43 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 55H6sh9W024560; Tue, 17 Jun 2025 06:54:43 GMT (envelope-from git) Date: Tue, 17 Jun 2025 06:54:43 GMT Message-Id: <202506170654.55H6sh9W024560@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Baptiste Daroussin Subject: git: 5ec727ea1a1e - main - nuageinit: write a documentation List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: bapt X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 5ec727ea1a1e65f3a784d70f7392d0a75d38d0a6 Auto-Submitted: auto-generated The branch main has been updated by bapt: URL: https://cgit.FreeBSD.org/src/commit/?id=5ec727ea1a1e65f3a784d70f7392d0a75d38d0a6 commit 5ec727ea1a1e65f3a784d70f7392d0a75d38d0a6 Author: Baptiste Daroussin AuthorDate: 2025-06-16 15:44:57 +0000 Commit: Baptiste Daroussin CommitDate: 2025-06-17 06:54:39 +0000 nuageinit: write a documentation Reviewed by: imp, ziaee (both a previous version) Differential Revision: https://reviews.freebsd.org/D50878 --- libexec/nuageinit/Makefile | 1 + libexec/nuageinit/nuageinit.7 | 288 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 289 insertions(+) diff --git a/libexec/nuageinit/Makefile b/libexec/nuageinit/Makefile index 64c5ec316f3d..a4d8e0de5777 100644 --- a/libexec/nuageinit/Makefile +++ b/libexec/nuageinit/Makefile @@ -2,6 +2,7 @@ PACKAGE= nuageinit SCRIPTS= nuageinit FILES= nuage.lua yaml.lua FILESDIR= ${SHAREDIR}/flua +MAN= nuageinit.7 .include diff --git a/libexec/nuageinit/nuageinit.7 b/libexec/nuageinit/nuageinit.7 new file mode 100644 index 000000000000..7e44ce208a9b --- /dev/null +++ b/libexec/nuageinit/nuageinit.7 @@ -0,0 +1,288 @@ +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" Copyright (c) 2025 Baptiste Daroussin +.\" +.Dd June 16, 2025 +.Dt NUAGEINIT 7 +.Os +.Sh NAME +.Nm nuageinit +.Nd initialize a cloud-init environment +.Sh DESCRIPTION +The +.Nm +program is used to initialize instances in a cloud environment. +.Nm +runs at the first boot after the system installation. +It is composed of 3 +.Xr rc 8 +scripts: +.Bl -tag -width "nuageinit" +.It Cm nuageinit +This script will detect the configuration disk kind of cloud environement the +system runs on and gather accordingly the configuration data. +The following cloud environements are supported right now: +.Bl -tag -width "OpenStack" +.It ondisk +A cloud agnostic environment where the disk is provided to the system +with the configuration data on it. +The disk should be formatted in one of the following formats: +.Xr cd9660 4 , +or +.Xr msdosfs 4 +and be labelled (via filesystem label) either +.Ar config-2 +or +.Ar cidata . +.It OpenStack +The system is running in an +.Lk https://www.openstack.org/ OpenStack environment . +It is detected via the +.Ar smbios.system.product +.Xr smbios 4 +description available in +.Xr kenv 2 . +.El +.Pp +Depending on the cloud environement above +.Nm +will attempt to configure the instance. +See +.Sx CONFIGURATION . +This script executes early, +after all the local filesystem are mounted but before +the network is configured. +.It Cm nuageinit_post_net +This script is reponsible processing the configurations that are network +dependant: +.Bl -bullet +.It +dealing with packages +.It +dealing with users (which can depend on shell provided by packages) +.El +.It Cm 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. +.El +.Pp +The default user for nuageinit is a user named: +.Va freebsd +with a password set to +.Va freebsd +and a shell set to +.Va /bin/sh . +.Sh CONFIGURATION +The configuration of +.Nm +is typically done via metadata provided by the cloud provider. +The metadata is presented to nuageinit in different form depending on +the provider: +provider: +.Bl -tag -width "config-2" +.It nocloud +If the data is provided via a disk labelled +.Va cidata , +then the metadata is provided in the form of a file named +.Pa meta-data +in YAML format. +.Nm +Will configure the hostname of the instance according the value of the +following variables +.Va local-hostname +or +.Va hostname . +.It config-2 +If the data is provided via a disk labelled +.Va config-2 , +or if fetched from OpenStack, +the metadata is expected in two json files: +.Pp +The +.Pa meta_data.json +file supportes the following keys: +.Bl -tag -width "public_keys" +.It Ic hostname +Set the hostname of the instance. +.It Ic public_keys +Append each entry of the array to +.Nm +default user which will be created. +.El +.Pp +The +.Pa network_data.json +file supports the following keys: +.Bl -tag -width "public_keys" +.It Ic links +Array of network interfaces to be configured. +.It Ic networks +Array of network configurations to be set. +.El +.El +.Pp +Along with the metadata, a user data file is provided, either named +.Pa user_data +or +.Pa user-data +If this file starts with a +.Qq #! , +it will be executed at the end of the boot via +.Cm nuageinit_user_data_script . +If this files starts with +.Qq #!cloud-config , +it will be parsed as a YAML configuration file. +All other cases will be ignored. +.Pp +The +.Qq #!cloud-config +configuration entries supported by +.Nm : +.Bl -tag -width "config-2" +.It Ic fqdn +Specify a fully qualified domain name for the instance. +.It Ic hostname +Specify the hostname of the instance if +.Qq Ic fqdn +is not set. +.It Ic groups +An array of strings or objects to be created: +.Bl -bullet +.It +If the entry is a string, +a group using this string as a name will be created. +.It +if the entry is a an object, the +.Qq Ar key +will be used as the name of the group, the +.Qq Ar value +will is expected to be a list of members (array), specified by name. +.El +.It Ic ssh_keys +An object of multiple key/values, +.Qq Cm keys +being in the form: +.Ar algo_private +or +.Ar algo_public , +.Qq Cm values +being the actual content of the files in +.Pa /etc/ssh . +.It Ic ssh_authorized_keys +Append each entry of the array to +.Nm +default user which will be created. +.It Ic ssh_pwauth +boolean which determines the value of the +.Qq Ic PasswordAuthentication +configuration in +.Pa /etc/ssh/sshd_config +.It Ic network +.It Ic runcmd +An array of commands to be run at the end of the boot process +.It Ic packages +List of packages to be installed. +.It Ic package_update +Update the remote package metadata. +.It Ic package_upgrade +Upgrade the packages installed to their latest version. +.It Ic users +Specify a list of users to be created: +.Bl -tag -width "plain_text_passwd" +.It Ic name +Name of the user. +.It Ic gecos +GECOS for the user. +.It Ic homedir +The path of the home directory for the user. +.It Ic primary_group +The main group the user should belong to. +.It Ic groups +The list of other groups the user should belong to. +.It Ic no_create_home +A boolean which determines if the home directory should be created or not. +.It Ic shell +The shell that should be used for the user. +.It Ic passwd +The encrypted password for the user. +.It Ic plain_text_passwd +The password in plain text for the user. +Ignored if an encrypted password is already provided. +.It Ic groups +The list of other groups the user should belong to. +.It Ic locked +Boolean to determine if the user accound should be locked. +.It Ic sudo +An entry which should be appended to +.Pa /usr/local/etc/sudoers.d/90-nuageinit-users +.El +.Pp +A special case exist: if the entry is a simple string with the following value +.Qq default +The the default user is created. +.It Ic chpasswd +Change the passwords for users, it accepts the following keys: +.Bl -tag -width "expire" +.It Ic expire +Boolean to force the user to changes their password during the first login +.It Ic users +An array of objects: +.Bl -tag -width "password" +.It Ic user +Specify the user who's password will be changed. +.It Ic password +Specify a text line with the new password, or +Specify the user who's password will be changed. +.Qq Cm RANDOM +to assign the password randomly. +If the textline starts with +.Qq Cm $x$ +Where x is a number, then the password is considered encrypted, +otherwise the password is considered plaintext. +.El +.El +.El +.Sh EXAMPLES +Here is an example of a YAML configuration for +.Nm : +.Bd -literal +#cloud-config +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 +package_update: true +package_upgrade: true +runcmd: + - logger -t nuageinit "boot finished" +ssh_keys: + ed25519_private: | + -----BEGIN OPENSSH PRIVATE KEY----- + blabla + ... + -----END OPENSSH PRIVATE KEY----- + ed25519_public: ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIK+MH4E8KO32N5CXRvXVqvyZVl0+6ue4DobdhU0FqFd+ +.Ed +.Sh SEE ALSO +.Xr kenv 2 , +.Xr cd9660 4 , +.Xr msdosfs 4 , +.Xr smbios 4 , +.Xr rc 8 +.Sh STANDARDS +.Nm +is believed to conform to the +.Lk https://cloud-init.io/ Cloud Init +specification. +.Sh HISTORY +.Nm +appeared in +.Fx 14.1