From 1f3af04db77f9e9e707bd37ee85f6508aef797f2 Mon Sep 17 00:00:00 2001 From: "Yann E. MORIN" Date: Fri, 12 Apr 2013 07:14:18 +0000 Subject: packages: add ability for packages to create users Packages that install daemons may need those daemons to run as a non-root, or an otherwise non-system (eg. 'daemon'), user. Add infrastructure for packages to create users, by declaring the FOO_USERS variable that contain a makedev-syntax-like description of the user(s) to add. Signed-off-by: "Yann E. MORIN" Cc: Samuel Martin Cc: Cam Hutchison Cc: Thomas Petazzoni Acked-by: Arnout Vandecappelle (Essensium/Mind) Signed-off-by: Peter Korsgaard --- docs/manual/adding-packages-generic.txt | 16 +++++- docs/manual/appendix.txt | 1 + docs/manual/makeusers-syntax.txt | 87 +++++++++++++++++++++++++++++++++ 3 files changed, 102 insertions(+), 2 deletions(-) create mode 100644 docs/manual/makeusers-syntax.txt (limited to 'docs') diff --git a/docs/manual/adding-packages-generic.txt b/docs/manual/adding-packages-generic.txt index a615ae2c9..aa94b8869 100644 --- a/docs/manual/adding-packages-generic.txt +++ b/docs/manual/adding-packages-generic.txt @@ -53,7 +53,11 @@ system is based on hand-written Makefiles or shell scripts. 36: /bin/foo f 4755 0 0 - - - - - 37: endef 38: -39: $(eval $(generic-package)) +39: define LIBFOO_USERS +40: foo -1 libfoo -1 * - - - LibFoo daemon +41: endef +42: +43: $(eval $(generic-package)) -------------------------------- The Makefile begins on line 7 to 11 with metadata information: the @@ -140,7 +144,10 @@ On line 31..33, we define a device-node file used by this package On line 35..37, we define the permissions to set to specific files installed by this package (+LIBFOO_PERMISSIONS+). -Finally, on line 39, we call the +generic-package+ function, which +On lines 39..41, we define a user that is used by this package (eg. +to run a daemon as non-root) (+LIBFOO_USERS+). + +Finally, on line 43, we call the +generic-package+ function, which generates, according to the variables defined previously, all the Makefile code necessary to make your package working. @@ -307,6 +314,11 @@ information is (assuming the package name is +libfoo+) : You can find some documentation for this syntax in the xref:makedev-syntax[]. This variable is optional. +* +LIBFOO_USERS+ lists the users to create for this package, if it installs + a program you want to run as a specific user (eg. as a daemon, or as a + cron-job). The syntax is similar in spirit to the makedevs one, and is + described in the xref:makeuser-syntax[]. This variable is optional. + * +LIBFOO_LICENSE+ defines the license (or licenses) under which the package is released. This name will appear in the manifest file produced by +make legal-info+. diff --git a/docs/manual/appendix.txt b/docs/manual/appendix.txt index ef34169f8..c48c3b169 100644 --- a/docs/manual/appendix.txt +++ b/docs/manual/appendix.txt @@ -5,6 +5,7 @@ Appendix ======== include::makedev-syntax.txt[] +include::makeusers-syntax.txt[] [[package-list]] Available packages diff --git a/docs/manual/makeusers-syntax.txt b/docs/manual/makeusers-syntax.txt new file mode 100644 index 000000000..21996546c --- /dev/null +++ b/docs/manual/makeusers-syntax.txt @@ -0,0 +1,87 @@ +// -*- mode:doc -*- ; + +[[makeuser-syntax]] +Makeuser 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. +- +uid+ is the desired UID for the user. It must be unique, and not + +0+. If set to +-1+, then a unique UID will be computed by Buildroot + in the range [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+, and the group does not already exist, then + a unique GID will be computed by Buildroot in the range [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. +- +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 https://en.wikipedia.org/wiki/Gecos_field[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+ -- cgit v1.2.3