From nobody Mon Jun 23 07:44:49 2025 X-Original-To: dev-commits-src-all@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 4bQg8f0sSxz5ywsv; Mon, 23 Jun 2025 07:44:50 +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 "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bQg8d4DMrz4D4s; Mon, 23 Jun 2025 07:44:49 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750664689; 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=jU313JpTnmFamiGO7mBHVhVbcP+KynvnVo1/cj/0x38=; b=rCl6OHSmSjXPTYP0I/606eiYHpiPQK+KtV2w6pXWIWLyu5P3KLfOYCzNSztbtM8JIal6UI yG45Qlu6rZNPOx2XVur63p1hx7SnBJVUIwQqurIJLXDFumdeCKiKtm9bqvi6LMhOFXval1 4Kng/teDrkV+u6k92Qi7S/T5DwwD4xcufPMUpRqaWDRok3PybzprTcr3Y/tdjEBbggZZ7h dl7g3249DWYbrLU33eUu9yrixKOc7vcfCtATS5tOiIVX6SvIHBEc6AEp9ftFHWzXSbM9Nv 2V+sFTaiREFj7zjBpEHm7y1bCX9OlEbL0Lm9voHc/vT5pMJr4hT1Bqk9v1GD0A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750664689; 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=jU313JpTnmFamiGO7mBHVhVbcP+KynvnVo1/cj/0x38=; b=spjQLzFZMBAeLK9iEIe1RjT8u6UE4rZ/vhY7w7yNsJdQCUUg9Y5iPIXkGc0u3GBLCEaZXX F0qZ5fcllmpc6mQl2Ha0uPT1V8GSrjXR9peoNuvkCO4vv6HVKUdssFZsEK55mVX8r97v/Z jZr3WJnC+YqStcHGtpDrz0HFl68Q/YmE507rpSrSKILUuJeRV8ZO7n/W/hXhBAum0mek+W oU1xlcyZcH4enZy2wGEMjLJpogTERotyVwmsHXve0HR35nc41yNdnY1UzpRCvUDLG0kzid T/aVilAQ0AS5FRqC/oaq+lQYjh1oaL+oN55bv9WuaFsHPabTdPbwSpDsPjePNA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1750664689; a=rsa-sha256; cv=none; b=RfX3Jyg4bc3WM1FMKcmBkZUyfk4v9EXZzgtsSUqC/wjCf9K/MsASDLHVDUTrQP5SWfP+Is Wtr6FBM88FOHTCQ18bBPyQW7l2yDamhXDYTqx0mqlmO9u61oOJRZJHONgMWJjONq/9aO+s hkW1ieYUirqH3of3j2fgrrDw6B6CXACtkT+exTskyecO5Hiai3VKxo6wLpCEfM2a8QE7uF 9L8apChJD/dNzUT6IcepJefIzz8hrLc4G4Oj3jHQETCOqBVx/KzrwWD9J9af8wsF4s0JQ8 v6eciGcOKxRN5P6QJSKplzbK9SUbx0OyPmsc5DFxef8uhzYvTAsGf+tmcOSIyQ== 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 4bQg8d3jvRztDL; Mon, 23 Jun 2025 07:44:49 +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 55N7inXD067858; Mon, 23 Jun 2025 07:44:49 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 55N7inkl067855; Mon, 23 Jun 2025 07:44:49 GMT (envelope-from git) Date: Mon, 23 Jun 2025 07:44:49 GMT Message-Id: <202506230744.55N7inkl067855@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Baptiste Daroussin Subject: git: 808038a38f05 - stable/14 - nuageinit: write a documentation List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@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/stable/14 X-Git-Reftype: branch X-Git-Commit: 808038a38f05c8d5f52b3d58d7acede7b26f1e78 Auto-Submitted: auto-generated The branch stable/14 has been updated by bapt: URL: https://cgit.FreeBSD.org/src/commit/?id=808038a38f05c8d5f52b3d58d7acede7b26f1e78 commit 808038a38f05c8d5f52b3d58d7acede7b26f1e78 Author: Baptiste Daroussin AuthorDate: 2025-06-16 15:44:57 +0000 Commit: Baptiste Daroussin CommitDate: 2025-06-23 07:44:44 +0000 nuageinit: write a documentation Reviewed by: imp, ziaee (both a previous version) Differential Revision: https://reviews.freebsd.org/D50878 (cherry picked from commit 5ec727ea1a1e65f3a784d70f7392d0a75d38d0a6) --- 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