Home > Articles

This chapter is from the book

7.3 Image Options

The following sections discuss a list of options that affect how the Yocto Project build system creates your root filesystem images.

7.3.1 Languages and Locales

Additional languages for different territories can easily be added to a root filesystem or your image by adding the IMAGE_LINGUAS variable to an image recipe. Using

IMAGE_LINGUAS = "en-gb pt-br"

adds the specific language packages for British English and Brazilian Portuguese to the image. However, not all software packages provide locales separated by language and territory. Some of them provide the locale files only by language. In this case, the build system defaults to installing the correct language local files regardless of the territory.

The minimum default for all packages is en-us and is always installed. In addition, the image class defines

IMAGE_LINGUAS ?= "de-de fr-fr en-gb"

Any additional locale packages, of course, occupy additional space in your root filesystem image. Therefore, if your device does not require any additional language support, it is good practice to set

IMAGE_LINGUAS = ""

in image recipes.

The build system ignores the languages for packages that do not provide them.

7.3.2 Package Management

The build system can package software packages using the four different packaging formats dpkg (Debian Package Management), opkg (Open Package Management), RPM (Red Hat Package Manager), and tar. Only the first three can be used to create root filesystems. Tar does not provide the necessary metadata package information and database to log what packages in what versions have been installed, which packages conflict with each other, and so on.

The variable PACKAGE_CLASSES in conf/local.conf of your build environment controls what package management systems are used for your builds:

PACKAGE_CLASSES = "package_rpm package_ipk package_tar"

You can declare more than one packaging class, but you have to provide at least one. The build system creates packages for all classes specified; however, only the first packaging class in the list is used to create the root filesystem of your distribution images. The first packaging class in the list must not be tar.

The build system stores the package feeds organized by the package management system in separate directories in tmp/deploy/<pms>, where <pms> is the name of the respective package management system. Inside those directories, the packages are further subdivided into common, architecture, and machine-dependent packages.

What package management system should you choose for your project? That depends on the requirements of your project. Here are some considerations you may want to take into account:

  • Opkg creates and utilizes less package metadata than dpkg and RPM. That makes building faster, and the packages are smaller.

  • Dpkg and RPM offer better dependency handling and version management than opkg because of the enhanced package metadata.

  • The RPM package manager is written in Python and requires Python to be installed on the target to install packages during runtime of the system.

By default, the build system does not install the package manager on your target system. If you are looking to install packages during runtime of your embedded system, you have to add the package manager using its image feature:

IMAGE_FEATURES += "package_management"

The build system automatically installs the correct package manager depending on the first entry of PACKAGE_CLASSES.

The package management system for your root filesystem is ultimately controlled by the variable IMAGE_PKGTYPE. This variable is set automatically by the order of the packaging classes defined by PACKAGE_CLASSES. The first packaging class in the list sets the variable. We recommend that you do not set this variable directly.

7.3.3 Image Size

The final size of the root filesystem is dependent on multiple factors and is computed by the build system using the function _get_rootfs_size() in the Python module meta/lib/oe/image.py. The computation takes into account the actual space required by the root filesystem and the following variable settings. It also ensures that the final root filesystem image size is always sufficient to hold the entire image. Hence, even if you set IMAGE_ROOTFS_SIZE to a specific value, the final image may be larger than that value, but it is never smaller.

  • IMAGE_ROOTFS_SIZE: Defines the size in kilobytes of the created root filesystem image. The build system uses this value as a request or recommendation. The final root filesystem image size may be larger depending on the actual space required. The default value is 65536.

  • IMAGE_ROOTFS_ALIGNMENT: Defines the alignment of the root filesystem image in kilobytes. If the final size of the root filesystem image is not a multiple of this value, it is rounded up to the nearest multiple of it. The default value is 1.

  • IMAGE_ROOTFS_EXTRA_SPACE: Adds extra free space to the root filesystem image. The variable specifies the value in kilobytes. For example, to add an additional 4 GB of space, set the variable to IMAGE_ROOTFS_EXTRA_SPACE = "4194304". The default value is 0.

  • IMAGE_OVERHEAD_FACTOR: This variable specifies a multiplicator for the root filesystem image. The factor is applied after the actual space required by the root filesystem has been determined. The default value is 1.3.

After the build system has created the root filesystem in the staging area, a directory specified by the variable IMAGE_ROOTFS, it calculates its actual size in kilobytes using du -ks ${IMAGE_ROOTFS}. The function _get_rootfs_size() computes the final root filesystem image size, as shown by Listing 7-7 in pseudocode.

Listing 7-7 Root Filesystem Image Size Computation in Pseudocode

_get_rootfs_size():

   ROOTFS_SIZE =`du -ks ${IMAGE_ROOTFS}`
   BASE_SIZE = ROOTFS_SIZE * IMAGE_OVERHEAD_FACTOR

   if (BASE_SIZE < IMAGE_ROOTFS_SIZE):
      IMG_SIZE = IMAGE_ROOTFS_SIZE + IMAGE_ROOTFS_EXTRA_SPACE
   else:
      IMG_SIZE = BASE_SIZE + IMAGE_ROOTFS_EXTRA_SPACE

   IMG_SIZE = IMG_SIZE + IMAGE_ROOTFS_ALIGNMENT – 1
   IMG_SIZE = IMG_SIZE % IMAGE_ROOTFS_ALIGNMENT

   return IMG_SIZE

Most commonly, your image recipes set IMAGE_ROOTFS_SIZE and IMAGE_ROOTFS_EXTRA_SPACE to adjust the final root filesystem image size. If you are concerned with the footprint of your root filesystem, then you may also want to reduce IMAGE_OVERHEAD_FACTOR or set it to 1 to shrink your image.

7.3.4 Root Filesystem Types

Eventually, you use the root filesystem image to create a bootable medium for your target or to launch the QEMU emulator. For that purpose, the build system provides the image_types class that can create a root filesystem for various filesystem types.

Your image recipes do not use the image_types class directly but rather set the variable IMAGE_FSTYPES to one or more of the filesystem types provided by the class. Using

IMAGE_FSTYPES = "ext3 tar.bz2"

creates two root filesystem images, one using the ext3 filesystem and one that is a tar archive compressed using the bzip2 algorithm.

The image_types class defines the variable IMAGE_TYPES, which contains a list of all image types you can specify in IMAGE_FSTYPES. The list shows the filesystem types ordered by core type. Commonly, some of the core types are also used in compressed formats to preserve space. If a compression algorithm is used for the filesystem, the name of the core type is appended with the compression type: <core name>.<compression type>.

  • tar, tar.gz, tar.bz2, tar.xz, tar.lz3: Create uncompressed and compressed root filesystem images in the form of tar archives.

  • ext2, ext2.gz, ext2.bz2, ext2.lzma: Root filesystem images using the ext2 filesystem without or with compression.

  • ext3, ext3.gz: Root filesystem images using the ext3 filesystem without or with compression.

  • btrfs: Root filesystem image with B-tree filesystem.

  • jffs2, jffs2.sum: Uncompressed or compressed root filesystems based on the second generation of the Journaling Flash File System (JFFS2). Since JFFS2 directly supports NAND flash devices, it is a popular choice for embedded systems. It also provides journaling and wear-leveling.

  • cramfs: Root filesystem image using the compressed ROM filesystem (cramfs). The Linux kernel can mount this filesystem without prior decompression. The compression uses the zlib algorithm that compresses files one page at a time to allow random access. This filesystem is read-only to simplify its design, as random write access with compression is difficult to implement.

  • iso: Root filesystem image type using the ISO 9660 standard for bootable CD-ROM. This filesystem type is not a standalone format. It uses ext3 as the underlying filesystem type.

  • hddimg: Root filesystem image for bootable hard drives. It uses ext3 as the actual filesystem type.

  • squashfs, squashfs-xz: Compressed read-only root filesystem type specifically for Linux, similar to cramfs but with better compression and support for larger files and filesystems. SquashFS also has a variable block size from 0.5 kB to 64 kB over the fixed 4 kB block size of cramfs, which allows for larger file and filesystem sizes. SquashFS uses gzip compression, while squashfs-xz uses Lempel–Ziv–Markov (LZMA) compression for even smaller images.

  • ubi, ubifs: Root filesystem images using the unsorted block image (UBI) format for raw flash devices. UBI File System (UBIFS) is essentially a successor to JFFS2. The main differences between the two is that UBIFS supports write caching. Using ubifs in IMAGE_FSTYPES just creates the ubifs root filesystem image. Using ubi creates the ubifs root filesystem image and also runs the ubinize utility to create an image that can be written directly to a flash device.

  • cpio, cpio.gz, cpio.xz, cpio.lzma: Root filesystem images using uncompressed or compressed copy in and out (CPIO) streams.

  • vmdk: Root filesystem image using the VMware virtual machine disk format. It uses ext3 as the underlying filesystem format.

  • elf: Bootable root filesystem image created with the mkelfImage utility from the Coreboot project (www.coreboot.org).

Once again, which image types to use depends entirely on the requirements of your project, particularly on your target hardware. Boot device, bootloader, memory constraints, and other factors determine what root filesystem types are appropriate for your project. Our recommendation is to specify the root filesystem types ext3 and tar, or better, one of the compressed formats such as tar.bz2, in the image recipe. The ext3 format allows you to easily boot your root filesystem with the QEMU emulator for testing. The tar filesystem can easily be extracted onto partitioned and formatted media. The machine configuration files for your target hardware can then add additional root filesystem types appropriate for it.

7.3.5 Users, Groups, and Passwords

The class extrausers provides a comfortable mechanism for adding users and groups to an image as well as setting passwords for user accounts (see Listing 7-8).

Listing 7-8 Modifying Users, Groups, and Passwords

SUMMARY = "Custom image recipe from scratch"
DESCRIPTION = "Directly assign IMAGE_INSTALL and IMAGE_FEATURES for \
               for direct control over image contents."

LICENSE = "MIT"

# We are using the assignment operator (=) below to purposely overwrite
# the default from the core-image class.
IMAGE_INSTALL = "packagegroup-core-boot packagegroup-base-extended \
                 ${CORE_IMAGE_EXTRA_INSTALL}"

inherit core-image
inherit extrausers

# set image root password
ROOT_PASSWORD = "secret"
DEV_PASSWORD = "hackme"

EXTRA_USERS_PARAMS = "\
   groupadd developers; \
   useradd -p `openssl passwd ${DEV_PASSWORD}` developer; \
   useradd -g developers developer; \
   usermod -p `openssl passwd ${ROOT_PASSWORD}` root; \
   "

The listing adds a group named developers and a user account named developer and adds the user account to the group. It also changes the password for the root account. Commands for adding and modifying groups, users, and passwords are added to the variable EXTRA_USERS_PARMS, which is interpreted by the class. The commands understood by the class are

  • useradd: Add user account

  • usermod: Modify user account

  • userdel: Remove user account

  • groupadd: Add user group

  • groupmod: Modify user group

  • groupdel: Remove user group

The class executes the respective Linux utilities with the corresponding names. Hence, the options are exactly the same and can easily be found in the Linux man pages. Note that the individual commands must be separated with a semicolon.

Using the option -p with the commands useradd and usermod sets the password of the user account. The password must be provided as the password hash. You can either calculate the password hash manually and add it to the recipe or, as shown in the example, have the recipe calculate it.

A word about the root user account: the build system sets up the root user for an image with an empty password if debug-tweaks is included with IMAGE_FEATURES. Removing debug-tweaks replaces the empty root password with *, which disables the account, so logging in as root from the console is no longer possible. For production use, we strongly recommend removing debug-tweaks from the build. If your embedded system requires console login capability, you can either set the root password as shown previously or add the sudo recipe and set up user accounts as sudoers.

For example, if you want to give the developer user account sudoer privileges, simply add sudo to IMAGE_INSTALL and usermod -a -G sudo developer to EXTRA_USERS_PARAMS.

7.3.6 Tweaking the Root Filesystem

For further customization of the root filesystem after it has been created by the build system and before the actual root filesystem images are created, ROOTFS_POSTPROCESS_COMMAND is available (see Listing 7-9). The variable holds a list of shell functions separated by semicolons.

Listing 7-9 ROOTFS_POSTPROCESS_COMMAND

SUMMARY = "Custom image recipe from scratch"
DESCRIPTION = "Directly assign IMAGE_INSTALL and IMAGE_FEATURES for \
               for direct control over image contents."

LICENSE = "MIT"

# We are using the assignment operator (=) below to purposely overwrite
# the default from the core-image class.
IMAGE_INSTALL = "packagegroup-core-boot packagegroup-base-extended \
                 ${CORE_IMAGE_EXTRA_INSTALL}"

inherit core-image

# Additional root filesystem processing
modify_shells() {
   printf "# /etc/shells: valid login shells\n/bin/sh\n/bin/bash\n" \
           > ${IMAGE_ROOTFS}/etc/shells
}
ROOTFS_POSTPROCESS_COMMAND += "modify_shells;"

The example adds the bash shell to /etc/shells. Be sure to always use the += operator to add to ROOTFS_POSTPROCESS_COMMAND, as the build system adds its own postprocessing commands to it.

Sudo Configuration

If you followed the example on giving a user sudoer privileges in the previous paragraph, you probably noticed that it does not work unless you uncomment the line %sudo ALL=(ALL) ALL in /etc/sudoers. A simple shell function added to ROOTFS_POSTPROCESS_COMMAND takes care of that when the root filesystem image is created (see Listing 7-10).

Listing 7-10 Sudo Configuration

modify_sudoers() {
   sed 's/# %sudo/%sudo/' < ${IMAGE_ROOTFS}/etc/sudoers > \
        ${IMAGE_ROOTFS}/etc/sudoers.tmp
   mv ${IMAGE_ROOTFS}/etc/sudoers.tmp ${IMAGE_ROOTFS}/etc/sudoers
}
ROOTFS_POSTPROCESS_COMMAND += "modify_sudoers;"

The script simply uncomments the line using sed.

SSH Server Configuration

All core images automatically include an SSH server for remote shell access to the system. By default, the server is configured to allow login with user name and password. Using public key infrastructure (PKI) provides an additional level of security but requires configuration of the root server and installation of keys into the root filesystem. A ROOTFS_POSTPROCESS_COMMAND can also easily be used to accomplish that task (see Listing 7-11).

Listing 7-11 SSH Server Configuration

configure_sshd() {
   # disallow password authentication
   echo "PasswordAuthentication no" >> ${IMAGE_ROOTFS}/etc/ssh/sshd_config
   # create keys in tmp/deploy/keys
   mkdir -p ${DEPLOY_DIR}/keys
   if [ ! -f ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot ]; then
      ssh-keygen -t rsa -N '' \
         -f ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot
   fi
   # add public key to authorized_keys for root
   mkdir -p ${IMAGE_ROOTFS}/home/root/.ssh
   cat ${DEPLOY_DIR}/keys/${IMAGE_BASENAME}-sshroot.pub \
       >> ${IMAGE_ROOTFS}/home/root/.ssh/authorized_keys
}
ROOTFS_POSTPROCESS_COMMAND += "configure_sshd;"

The script first disables authentication with user name and password for SSH. It then creates a key pair in tmp/deploy/keys inside the build environment using the name of the root filesystem image, essentially the name of the image recipe. If a previous build has already created a set of keys, they are preserved. Finally, the script adds the public key to the authorized_keys file in /home/root/.ssh, which is typical for SSH configuration. Login keys for other users can be created in a similar way.

This method works well if you do not require different keys for each device that you build, as every copy of the root filesystem of course contains the same keys. If you need different keys or, in general, individual configuration for your devices, then you need to devise a provisioning system for your device production.

InformIT Promotional Mailings & Special Offers

I would like to receive exclusive offers and hear about products from InformIT and its family of brands. I can unsubscribe at any time.

Overview


Pearson Education, Inc., 221 River Street, Hoboken, New Jersey 07030, (Pearson) presents this site to provide information about products and services that can be purchased through this site.

This privacy notice provides an overview of our commitment to privacy and describes how we collect, protect, use and share personal information collected through this site. Please note that other Pearson websites and online products and services have their own separate privacy policies.

Collection and Use of Information


To conduct business and deliver products and services, Pearson collects and uses personal information in several ways in connection with this site, including:

Questions and Inquiries

For inquiries and questions, we collect the inquiry or question, together with name, contact details (email address, phone number and mailing address) and any other additional information voluntarily submitted to us through a Contact Us form or an email. We use this information to address the inquiry and respond to the question.

Online Store

For orders and purchases placed through our online store on this site, we collect order details, name, institution name and address (if applicable), email address, phone number, shipping and billing addresses, credit/debit card information, shipping options and any instructions. We use this information to complete transactions, fulfill orders, communicate with individuals placing orders or visiting the online store, and for related purposes.

Surveys

Pearson may offer opportunities to provide feedback or participate in surveys, including surveys evaluating Pearson products, services or sites. Participation is voluntary. Pearson collects information requested in the survey questions and uses the information to evaluate, support, maintain and improve products, services or sites, develop new products and services, conduct educational research and for other purposes specified in the survey.

Contests and Drawings

Occasionally, we may sponsor a contest or drawing. Participation is optional. Pearson collects name, contact information and other information specified on the entry form for the contest or drawing to conduct the contest or drawing. Pearson may collect additional personal information from the winners of a contest or drawing in order to award the prize and for tax reporting purposes, as required by law.

Newsletters

If you have elected to receive email newsletters or promotional mailings and special offers but want to unsubscribe, simply email information@informit.com.

Service Announcements

On rare occasions it is necessary to send out a strictly service related announcement. For instance, if our service is temporarily suspended for maintenance we might send users an email. Generally, users may not opt-out of these communications, though they can deactivate their account information. However, these communications are not promotional in nature.

Customer Service

We communicate with users on a regular basis to provide requested services and in regard to issues relating to their account we reply via email or phone in accordance with the users' wishes when a user submits their information through our Contact Us form.

Other Collection and Use of Information


Application and System Logs

Pearson automatically collects log data to help ensure the delivery, availability and security of this site. Log data may include technical information about how a user or visitor connected to this site, such as browser type, type of computer/device, operating system, internet service provider and IP address. We use this information for support purposes and to monitor the health of the site, identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents and appropriately scale computing resources.

Web Analytics

Pearson may use third party web trend analytical services, including Google Analytics, to collect visitor information, such as IP addresses, browser types, referring pages, pages visited and time spent on a particular site. While these analytical services collect and report information on an anonymous basis, they may use cookies to gather web trend information. The information gathered may enable Pearson (but not the third party web trend services) to link information with application and system log data. Pearson uses this information for system administration and to identify problems, improve service, detect unauthorized access and fraudulent activity, prevent and respond to security incidents, appropriately scale computing resources and otherwise support and deliver this site and its services.

Cookies and Related Technologies

This site uses cookies and similar technologies to personalize content, measure traffic patterns, control security, track use and access of information on this site, and provide interest-based messages and advertising. Users can manage and block the use of cookies through their browser. Disabling or blocking certain cookies may limit the functionality of this site.

Do Not Track

This site currently does not respond to Do Not Track signals.

Security


Pearson uses appropriate physical, administrative and technical security measures to protect personal information from unauthorized access, use and disclosure.

Children


This site is not directed to children under the age of 13.

Marketing


Pearson may send or direct marketing communications to users, provided that

  • Pearson will not use personal information collected or processed as a K-12 school service provider for the purpose of directed or targeted advertising.
  • Such marketing is consistent with applicable law and Pearson's legal obligations.
  • Pearson will not knowingly direct or send marketing communications to an individual who has expressed a preference not to receive marketing.
  • Where required by applicable law, express or implied consent to marketing exists and has not been withdrawn.

Pearson may provide personal information to a third party service provider on a restricted basis to provide marketing solely on behalf of Pearson or an affiliate or customer for whom Pearson is a service provider. Marketing preferences may be changed at any time.

Correcting/Updating Personal Information


If a user's personally identifiable information changes (such as your postal address or email address), we provide a way to correct or update that user's personal data provided to us. This can be done on the Account page. If a user no longer desires our service and desires to delete his or her account, please contact us at customer-service@informit.com and we will process the deletion of a user's account.

Choice/Opt-out


Users can always make an informed choice as to whether they should proceed with certain services offered by InformIT. If you choose to remove yourself from our mailing list(s) simply visit the following page and uncheck any communication you no longer want to receive: www.informit.com/u.aspx.

Sale of Personal Information


Pearson does not rent or sell personal information in exchange for any payment of money.

While Pearson does not sell personal information, as defined in Nevada law, Nevada residents may email a request for no sale of their personal information to NevadaDesignatedRequest@pearson.com.

Supplemental Privacy Statement for California Residents


California residents should read our Supplemental privacy statement for California residents in conjunction with this Privacy Notice. The Supplemental privacy statement for California residents explains Pearson's commitment to comply with California law and applies to personal information of California residents collected in connection with this site and the Services.

Sharing and Disclosure


Pearson may disclose personal information, as follows:

  • As required by law.
  • With the consent of the individual (or their parent, if the individual is a minor)
  • In response to a subpoena, court order or legal process, to the extent permitted or required by law
  • To protect the security and safety of individuals, data, assets and systems, consistent with applicable law
  • In connection the sale, joint venture or other transfer of some or all of its company or assets, subject to the provisions of this Privacy Notice
  • To investigate or address actual or suspected fraud or other illegal activities
  • To exercise its legal rights, including enforcement of the Terms of Use for this site or another contract
  • To affiliated Pearson companies and other companies and organizations who perform work for Pearson and are obligated to protect the privacy of personal information consistent with this Privacy Notice
  • To a school, organization, company or government agency, where Pearson collects or processes the personal information in a school setting or on behalf of such organization, company or government agency.

Links


This web site contains links to other sites. Please be aware that we are not responsible for the privacy practices of such other sites. We encourage our users to be aware when they leave our site and to read the privacy statements of each and every web site that collects Personal Information. This privacy statement applies solely to information collected by this web site.

Requests and Contact


Please contact us about this Privacy Notice or if you have any requests or questions relating to the privacy of your personal information.

Changes to this Privacy Notice


We may revise this Privacy Notice through an updated posting. We will identify the effective date of the revision in the posting. Often, updates are made to provide greater clarity or to comply with changes in regulatory requirements. If the updates involve material changes to the collection, protection, use or disclosure of Personal Information, Pearson will provide notice of the change through a conspicuous notice on this site or other appropriate way. Continued use of the site after the effective date of a posted revision evidences acceptance. Please contact us if you have questions or concerns about the Privacy Notice or any objection to any revisions.

Last Update: November 17, 2020