From mboxrd@z Thu Jan 1 00:00:00 1970 X-GM-THRID: 6691586504498610176 X-Received: by 2002:a2e:9b93:: with SMTP id z19mr976538lji.96.1558623325918; Thu, 23 May 2019 07:55:25 -0700 (PDT) X-BeenThere: isar-users@googlegroups.com Received: by 2002:a19:ed03:: with SMTP id y3ls599499lfy.1.gmail; Thu, 23 May 2019 07:55:25 -0700 (PDT) X-Google-Smtp-Source: APXvYqyI/KvCV7H5cedkIQ0sD1kd3JGAzykJoOejUIP6aCHs1+N/oAtiVjjc8XrcoRMxQGSYbiJM X-Received: by 2002:a19:2b84:: with SMTP id r126mr47419718lfr.86.1558623325427; Thu, 23 May 2019 07:55:25 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1558623325; cv=none; d=google.com; s=arc-20160816; b=hCih2d+1JYSDmaubN/4IjJu7Gspq5Kqti4VYZzzpBX+Ns09WqQZhZOoKuypLmKLJ/a C8CIAqezuMZ/vpPqfVom4Qvmuh/uWHV3h4Qgepua2SmbhoxKipjaMlyelM3ifJ9SS+SZ xC9LUrEqiIAvEN5LyUq9buuxNRtin6XUCbNTlRXHorF5g58CUlZVSr47mdbr2g6L00FH ZNnVjy+reSV76h6ui7Rx7LdI0y+0enuAFoIzhpjAkAWmLlz+hqpKVT7ClxSG5OxeyK1p e6a5huzxn0a77vJYzkDiJ6ttuqVOAV52MtsgDxK1oFiwU7FVlnsNHlBPS5xFvBZIkR8l 2ARw== 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=x+sEua6yz+GUzXVtC8+QdblXGgU/jeSYBt+i0C1RUOM2mYP1JEJk+aDowKEWps4vj0 5cwBQ+FEMMba1kZtZF7MYmQWj/11y2/a8b79TreOf7URIO0I217xhr7VqfViVZC7T1oi fP7sv9by2NEPiRTKNNopIEWmmV6ONaqwE1Iw1vrQAq+5y7tIAclPSA80vQ+TwosGdbkF jF5VzsGC2E7FWTy6Wr+LL6hvxCoDfQBi9l1vKIH8rjH+TMXa31REXtvAl9ZvMcDk4nyl MArDlCOB/Kw4HSKjzYiuaGeBCXryRIvrOz9KnOTp24yLou7SFFLd0CDn4f5Q1CBXFGTC GjRA== ARC-Authentication-Results: i=1; gmr-mx.google.com; spf=pass (google.com: domain of claudius.heine.ext@siemens.com designates 194.138.37.39 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 lizzard.sbs.de (lizzard.sbs.de. [194.138.37.39]) by gmr-mx.google.com with ESMTPS id o133si364597lfo.0.2019.05.23.07.55.25 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 23 May 2019 07:55:25 -0700 (PDT) Received-SPF: pass (google.com: domain of claudius.heine.ext@siemens.com designates 194.138.37.39 as permitted sender) client-ip=194.138.37.39; Authentication-Results: gmr-mx.google.com; spf=pass (google.com: domain of claudius.heine.ext@siemens.com designates 194.138.37.39 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 lizzard.sbs.de (8.15.2/8.15.2) with ESMTPS id x4NEtOvX027876 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK); Thu, 23 May 2019 16:55:24 +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 x4NEtNgE014892; Thu, 23 May 2019 16:55:24 +0200 From: claudius.heine.ext@siemens.com To: isar-users@googlegroups.com Cc: Claudius Heine Subject: [PATCH v4 5/8] doc: update description of image customization Date: Thu, 23 May 2019 16:55:18 +0200 Message-Id: <20190523145521.23050-6-claudius.heine.ext@siemens.com> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190523145521.23050-1-claudius.heine.ext@siemens.com> References: <20190523145521.23050-1-claudius.heine.ext@siemens.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-TUID: f2LpkcgGXdUQ 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