Makedev syntax documentation

The makedev syntax is used in several places in Buildroot to define changes to be made for permissions, or which device files to create and how to create them, in order to avoid calls to mknod.

This syntax is derived from the makedev utility, and more complete documentation can be found in the package/makedevs/README file.

It takes the form of a space separated list of fields, one file per line; the fields are:

name

type

mode

uid

gid

major

minor

start

inc

count

There are a few non-trivial blocks:

  • name is the path to the file you want to create/modify

  • type is the type of the file, being one of:

    • f: a regular file

    • d: a directory

    • r: a directory recursively

    • c: a character device file

    • b: a block device file

    • p: a named pipe

  • mode are the usual permissions settings (only numerical values are allowed)

  • uid and gid are the UID and GID to set on this file; can be either numerical values or actual names

  • major and minor are here for device files, set to - for other files

  • start, inc and count are for when you want to create a batch of files, and can be reduced to a loop, beginning at start, incrementing its counter by inc until it reaches count

Let’s say you want to change the permissions of a given file; using this syntax, you will need to write:

/usr/bin/foo f 755 0 0 - - - - -
/usr/bin/bar f 755 root root - - - - -
/data/buz f 644 buz-user buz-group - - - - -

Alternatively, if you want to change owner/permission of a directory recursively, you can write (to set UID to foo, GID to bar and access rights to rwxr-x--- for the directory /usr/share/myapp and all files and directories below it):

/usr/share/myapp r 750 foo bar - - - - -

On the other hand, if you want to create the device file /dev/hda and the corresponding 15 files for the partitions, you will need for /dev/hda:

/dev/hda b 640 root root 3 0 0 0 -

and then for device files corresponding to the partitions of /dev/hda, /dev/hdaX, X ranging from 1 to 15:

/dev/hda b 640 root root 3 1 1 1 15

Extended attributes are supported if BR2_ROOTFS_DEVICE_TABLE_SUPPORTS_EXTENDED_ATTRIBUTES is enabled. This is done by adding a line starting with |xattr after the line describing the file. Right now, only capability is supported as extended attribute.

|xattr

capability

  • |xattr is a "flag" that indicate an extended attribute

  • capability is a capability to add to the previous file

If you want to add the capability cap_sys_admin to the binary foo, you will write :

/usr/bin/foo f 755 root root - - - - -
|xattr cap_sys_admin+eip

You can add several capabilities to a file by using several |xattr lines. If you want to add the capability cap_sys_admin and cap_net_admin to the binary foo, you will write :

/usr/bin/foo f 755 root root - - - - -
|xattr cap_sys_admin+eip
|xattr cap_net_admin+eip

Makeusers syntax documentation

The syntax to create users is inspired by the makedev syntax, above, but is specific to Buildroot.

The syntax for adding a user is a space-separated list of fields, one user per line; the fields are:

username

uid

group

gid

password

home

shell

groups

comment

Where:

  • username is the desired user name (aka login name) for the user. It can not be root, and must be unique. If set to -, then just a group will be created.

  • uid is the desired UID for the user. It must be unique, and not 0. If set to -1 or -2, then a unique UID will be computed by Buildroot, with -1 denoting a system UID from [100…​999] and -2 denoting a user UID from [1000…​1999].

  • group is the desired name for the user’s main group. It can not be root. If the group does not exist, it will be created.

  • gid is the desired GID for the user’s main group. It must be unique, and not 0. If set to -1 or -2, and the group does not already exist, then a unique GID will be computed by Buildroot, with -1 denoting a system GID from [100…​999] and -2 denoting a user GID from [1000…​1999].

  • password is the crypt(3)-encoded password. If prefixed with !, then login is disabled. If prefixed with =, then it is interpreted as clear-text, and will be crypt-encoded (using MD5). If prefixed with !=, then the password will be crypt-encoded (using MD5) and login will be disabled. If set to *, then login is not allowed. If set to -, then no password value will be set.

  • home is the desired home directory for the user. If set to '-', no home directory will be created, and the user’s home will be /. Explicitly setting home to / is not allowed.

  • shell is the desired shell for the user. If set to -, then /bin/false is set as the user’s shell.

  • groups is the comma-separated list of additional groups the user should be part of. If set to -, then the user will be a member of no additional group. Missing groups will be created with an arbitrary gid.

  • comment (aka GECOS field) is an almost-free-form text.

There are a few restrictions on the content of each field:

  • except for comment, all fields are mandatory.

  • except for comment, fields may not contain spaces.

  • no field may contain a colon (:).

If home is not -, then the home directory, and all files below, will belong to the user and its main group.

Examples:

foo -1 bar -1 !=blabla /home/foo /bin/sh alpha,bravo Foo user

This will create this user:

  • username (aka login name) is: foo

  • uid is computed by Buildroot

  • main group is: bar

  • main group gid is computed by Buildroot

  • clear-text password is: blabla, will be crypt(3)-encoded, and login is disabled.

  • home is: /home/foo

  • shell is: /bin/sh

  • foo is also a member of groups: alpha and bravo

  • comment is: Foo user

test 8000 wheel -1 = - /bin/sh - Test user

This will create this user:

  • username (aka login name) is: test

  • uid is : 8000

  • main group is: wheel

  • main group gid is computed by Buildroot, and will use the value defined in the rootfs skeleton

  • password is empty (aka no password).

  • home is / but will not belong to test

  • shell is: /bin/sh

  • test is not a member of any additional groups

  • comment is: Test user

Caveat with automatic UIDs and GIDs

When updating buildroot or when packages are added or removed to/from the configuration, it is possible that the automatic UIDs and GIDs are changed. This can be a problem if persistent files were created with that user or group: after upgrade, they will suddenly have a different owner.

Therefore, it is advisable to perpetuate the automatic IDs. This can be done by adding a users table with the generated IDs. It is only needed to do this for UIDs that actually create persistent files, e.g. database.

Migrating from older Buildroot versions

Some versions have introduced backward incompatibilities. This section explains those incompatibilities, and for each explains what to do to complete the migration.

General approach

To migrate from an older Buildroot version, take the following steps.

  1. For all your configurations, do a build in the old Buildroot environment. Run make graph-size. Save graphs/file-size-stats.csv in a different location. Run make clean to remove the rest.

  2. Review the specific migration notes below and make the required adaptations to external packages and custom build scripts.

  3. Update Buildroot.

  4. Run make menuconfig starting from the existing .config.

  5. If anything is enabled in the Legacy menu, check its help text, unselect it, and save the configuration.

  6. For more details, review the git commit messages for the packages that you need. Change into the packages directory and run git log <old version>.. — <your packages>.

  7. Build in the new Buildroot environment.

  8. Fix build issues in external packages (usually due to updated dependencies).

  9. Run make graph-size.

  10. Compare the new file-size-stats.csv with the original one, to check if no required files have disappeared and if no new big unneeded files have appeared.

  11. For configuration (and other) files in a custom overlay that overwrite files created by Buildroot, check if there are changes in the Buildroot-generated file that need to be propagated to your custom file.

Migrating to 2016.11

Before Buildroot 2016.11, it was possible to use only one br2-external tree at once. With Buildroot 2016.11 came the possibility to use more than one simultaneously (for details, see [outside-br-custom]).

This however means that older br2-external trees are not usable as-is. A minor change has to be made: adding a name to your br2-external tree.

This can be done very easily in just a few steps:

  • First, create a new file named external.desc, at the root of your br2-external tree, with a single line defining the name of your br2-external tree:

    $ echo 'name: NAME_OF_YOUR_TREE' >external.desc
    Note

    Be careful when choosing a name: It has to be unique and be made with only ASCII characters from the set [A-Za-z0-9_].

  • Then, change every occurence of BR2_EXTERNAL in your br2-external tree with the new variable:

    $ find . -type f | xargs sed -i 's/BR2_EXTERNAL/BR2_EXTERNAL_NAME_OF_YOUR_TREE_PATH/g'

Now, your br2-external tree can be used with Buildroot 2016.11 onward.

Note:

This change makes your br2-external tree incompatible with Buildroot before 2016.11.

Migrating to 2017.08

Before Buildroot 2017.08, host packages were installed in $(HOST_DIR)/usr (with e.g. the autotools' --prefix=$(HOST_DIR)/usr). With Buildroot 2017.08, they are now installed directly in $(HOST_DIR).

Whenever a package installs an executable that is linked with a library in $(HOST_DIR)/lib, it must have an RPATH pointing to that directory.

An RPATH pointing to $(HOST_DIR)/usr/lib is no longer accepted.