From mboxrd@z Thu Jan 1 00:00:00 1970 X-GM-THRID: 6691586504498610176 X-Received: by 2002:a50:f5d4:: with SMTP id x20mr74593195edm.88.1558356383958; Mon, 20 May 2019 05:46:23 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a17:906:4a19:: with SMTP id w25ls3855323eju.14.gmail; Mon, 20 May 2019 05:46:23 -0700 (PDT) X-Google-Smtp-Source: APXvYqxnUEay9XDb2P/Z9RSE1utpudmqvfm1GXBhHguCm4nv62Orr5RaMI1gXtdrHPEhoXMDS0HL X-Received: by 2002:a17:906:3d8:: with SMTP id c24mr3710512eja.214.1558356383568; Mon, 20 May 2019 05:46:23 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558356383; cv=none; d=google.com; s=arc-20160816; b=Qn9x2NzClK9iApQxADxPExS6Ih0eG7kbqd/RjR2EgxuLnIm+9qo3rrG9oOsIz1+1qU 6iA4sJuz4ui2odNkpk6L03a6O5iIfEx9jeZU/URVDERer0htA0QTZexfnCaC3tCe7F1I j7hMdQrGCSb5+HW507dbz1+avDwbIciiZJGfOIkGV/h0KPRFmoeOR5uhnVxhcvI/+Abb ah98KX/Wn56ajeQP4nCjU+iDf06bV9Go85ALj35UMQKvMIKUbytZjlKLCws/BYlywZld ylWCXvVRLj50lJNW02kV1buMk7Yab9uzl1RMqRJrUIQ1+xByPHz70z5lB3+ssjgc+mg6 Klow== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from; bh=/8zEPY0wb6qIgm0SxlWTxfoOH1+ylo9CMzY7vcTxLo4=; b=uIj7DKcMzUG0F3D3RREj5/zH8X21RqW3UBfxxy7D5IRrKRcNZcUP89MJrhYTCICyVU 66a/9FHIxToLK4p5GK8lvhWWMHwCtrqivqOWiPiI+2tTtr2v2QiCJh6pNCAtE3/qlvFN eel+qVIcjV8vgsLa0hyQ0YF+1NTD5H0Ng4QgWJ8GhrUgSyb7sG8wm8PVHQdDLhbKUXZP CK8b/LgU8qct31agbPIFDb82dV4e84kZHDNy3HPF76OloWnIOR9w88YgJkfImmBPJIF+ MDZ0u1yPNfH/txq2itmHII3QRlDFbi+elDpFTtrAkVMS4zIqWC7+ewbyKIe3toDDdhnn FUAg== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: domain of claudius.heine.ext@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=claudius.heine.ext@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com Return-Path: Received: from thoth.sbs.de (thoth.sbs.de. [192.35.17.2]) by gmr-mx.google.com with ESMTPS id l30si2319185edd.4.2019.05.20.05.46.23 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 20 May 2019 05:46:23 -0700 (PDT) Received-SPF: pass (google.com: domain of claudius.heine.ext@siemens.com designates 192.35.17.2 as permitted sender) client-ip=192.35.17.2; Authentication-Results: gmr-mx.google.com; spf=pass (google.com: domain of claudius.heine.ext@siemens.com designates 192.35.17.2 as permitted sender) smtp.mailfrom=claudius.heine.ext@siemens.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=siemens.com Received: from mail1.sbs.de (mail1.sbs.de [192.129.41.35]) by thoth.sbs.de (8.15.2/8.15.2) with ESMTPS id x4KCkLYp000931 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Mon, 20 May 2019 14:46:21 +0200 Received: from ring.ppmd.siemens.net (linux-ses-ext02.ppmd.siemens.net [139.25.69.232]) by mail1.sbs.de (8.15.2/8.15.2) with ESMTP id x4KCkMDE000732; Mon, 20 May 2019 14:46:22 +0200 From: claudius.heine.ext@siemens.com To: isar-users@googlegroups.com Cc: Claudius Heine Subject: [PATCH v3 5/8] doc: update description of image customization Date: Mon, 20 May 2019 14:46:15 +0200 Message-Id: <20190520124618.16598-6-claudius.heine.ext@siemens.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190520124618.16598-1-claudius.heine.ext@siemens.com> References: <20190520124618.16598-1-claudius.heine.ext@siemens.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-TUID: ONVEKfyeIj+l From: Claudius Heine Signed-off-by: Claudius Heine --- doc/user_manual.md | 51 ++++++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 11 deletions(-) diff --git a/doc/user_manual.md b/doc/user_manual.md index dbbe6f6..4c9f4ae 100644 --- a/doc/user_manual.md +++ b/doc/user_manual.md @@ -314,16 +314,12 @@ Some other variables include: - `IMAGE_INSTALL` - The list of custom packages to build and install to target image, please refer to relative chapter for more information. - `BB_NUMBER_THREADS` - The number of `bitbake` jobs that can be run in parallel. Please set this option according your host CPU cores number. - - `LOCALE_GEN` - A `\n` seperated list of `/etc/locale.gen` entries desired on the target. - - `LOCALE_DEFAULT` - The default locale used for the `LANG` and `LANGUAGE` variable in `/etc/locale`. - `HOST_DISTRO` - The distro to use for SDK root filesystem (so far limited only to `debian-stretch`). This variable is optional. - `HOST_ARCH` - The Debian architecture of SDK root filesystem (e.g., `amd64`). By default set to current Debian host architecture. This variable is optional. - `HOST_DISTRO_APT_SOURCES` - List of apt source files for SDK root filesystem. This variable is optional. - `HOST_DISTRO_APT_PREFERENCES` - List of apt preference files for SDK root filesystem. This variable is optional. - `DISTRO_APT_PREMIRRORS` - The preferred mirror (append it to the default URI in the format `ftp.debian.org my.preferred.mirror`. This variable is optional. - `THIRD_PARTY_APT_KEYS` - List of gpg key URIs used to verify apt repos for apt installation after bootstrapping - - `CFG_ROOT_PW` - The encrypted root password to be set. To encrypt password use `mkpasswd`. You find `mkpasswd` in the `whois` package of Debian. If the variable is empty, root login is passwordless. - - `CFG_ROOT_LOCKED` - If set to `1` the root account will be locked. --- @@ -496,17 +492,50 @@ Isar contains additional image type classes that can be used as reference: ## Customize and configure image -Customization and configuration of an image should be done via packages, see below. +Customization and configuration of an image can be done in two ways: + + 1. Creating and adding a configuration package to `IMAGE_INSTALL`, or + 2. Changing the bitbake variables of the image recipe. + +In cases where configuration is not image specific, does not contain any secrets and can be shared between images, creating and adding a configuration package to `IMAGE_INSTALL` is the right option. This should be the case with most product specific configuration files. + +In cases where the configuration would contain secrets like user passwords, that would be world readable in `postinst`, etc. script files, some image extensions where created, that allow customization of those options from within the image recipe using bitbake variables. (e.g. user and group management and locale settings) + +### Locale configuration + +Two variables can be used to configure the locale installed on a image: + + - `LOCALE_GEN` - A `\n` seperated list of `/etc/locale.gen` entries desired on the target. + - `LOCALE_DEFAULT` - The default locale used for the `LANG` and `LANGUAGE` variable in `/etc/locale`. + +### User and group configuration + +Groups can be created or modified using the `GROUPS` and `GROUP_` variable or their flags. + +The `GROUPS` variable contains a space separated list of group names that should be modified or created. Each entry of this variable should have a corresponding `GROUP_` variable. -Adding those configuration packages to the image can be done in two ways: +The `GROUP_` variable contains the settings of a group named `groupname` in its flags. The following flags can be used: - 1. Simply adding the package to `IMAGE_INSTALL`, like any other isar created package, or - 2. Adding the package to `IMAGE_TRANSIENT_PACKAGES`. + - `gid` - The numeric group id. + - `flags` - A list of additional flags of the group. Those are the currently recognized flags: + - `system` - The group is created using the `--system` parameter. -In most cases adding the configuration package to `IMAGE_INSTALL` is the right option. +The `USERS` and `USER_` variable works similar to the `GROUPS` and `GROUP_` variable. The difference are the accepted flags of the `USER_` variable. It accepts the following flags: -In cases were the configuration script of the package has some external dependencies, that should not be part of the final image, then `IMAGE_TRANSIENT_PACKAGES` is the right option. -Packages in the `IMAGE_TRANSIENT_PACKAGES` variable are installed to the image and purged in the next step. If such a configuration package deploys file as part of their content, then those files will be removed as well. + - `password` - The crypt(3) encrypted password. To encrypt a password use for example `mkpasswd` or `openssl passwd -6`. You can find `mkpasswd` in the `whois` package of Debian. + - `expire` - A `YYYY-MM-DD` formatted date on which the user account will be disabled. (see useradd(8)) + - `inactive` - The number of days after a password expires until the account is permanently disabled. (see useradd(8)) + - `uid` - The numeric user id. + - `gid` - The numeric group id or group name of this users initial login group. + - `comment` - This users comment field. Commonly the following format `full name,room number,work phone number,home phone number,other entry`. + - `home` - This users home directory + - `shell` - This users login shell + - `groups` - A space separated list of groups this user is a member of. + - `flags` - A list of additional flags of the user: + - `no-create-home` - `useradd` will be called with `-M` to prevent creation of the users home directory. + - `create-home` - `useradd` will be called with `-m` to force creation of the users home directory. + - `system` - `useradd` will be called with `--system`. + - `allow-empty-password` - Even if the `password` flag is empty, it will still be set. This results in a login without password. --- -- 2.20.1