[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     a47f823e94931580ffebcc76f160dc7dcf53e02b
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Fri Sep  2 00:21:20 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Sep  2 00:21:20 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=a47f823e

ebuild-writing/users-and-groups: fix enewuser calling convention #592702

enewuser stopped passing extra arguments, shown as '[params]' in the
docs, to useradd. Update the docs to reflect the eclass change.

Gentoo-Bug: https://bugs.gentoo.org/592702

 ebuild-writing/users-and-groups/text.xml | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index e1d0fcd..536be3b 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -52,7 +52,7 @@ To add a user, use the <c>enewuser</c> function:
 </p>
 
 <pre>
-enewuser &lt;user&gt; [uid] [shell] [homedir] [groups] [params]
+enewuser &lt;user&gt; [uid] [shell] [homedir] [groups]
 </pre>
 
 <p>
@@ -77,11 +77,6 @@ wrapped correctly, for example:
 enewuser frozd -1 -1 -1 "backup,frozd"
 </pre>
 
-<p>
-Finally, any data left over for the <c>params</c> argument is passed directly to
-useradd.
-</p>
-
 <note>
 User IDs should rarely be hardcoded. If this is the case, you should
 probably check first on gentoo-dev.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Ulrich Müller]

commit:     fd833333ad0b4b6be3ee7bb238cf04d63a9fa320
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Nov 16 15:53:31 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Nov 16 15:55:02 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fd833333

ebuild-writing/users-and-groups: Sync with QA policy

UIDs and GIDs can be chosen from the range 101..749.

Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 9b2b49d..392a5b4 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -14,12 +14,12 @@ categories.
 
 <p>
 First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID
-assignment list</uri> and choose a free UID/GID in the range between
-101 and 499. If you are adding a user and a group with the same name,
-use the same number for their UID and GID, respectively. When in doubt,
-take the next free number from 499 downwards. The helper script
-<c>./bin/used_free_uidgids.sh</c> available in the data/api.git repository can
-be used to find the next available UID or GID.
+assignment list</uri> and choose a free UID/GID in the range between 101 and
+749. If you are adding a user and a group with the same name, use the same
+number for their UID and GID, respectively. When in doubt, take the next free
+number from 101 upwards. The helper script <c>./bin/used_free_uidgids.sh</c>
+available in the data/api.git repository can be used to find the next available
+UID or GID.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Ulrich Müller]

commit:     04eb21f7dd1f689488f0b04f0153484573a25243
Author:     Joonas Niilola <juippis <AT> gentoo <DOT> org>
AuthorDate: Mon Feb 15 06:29:54 2021 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Fri Feb 19 06:40:47 2021 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=04eb21f7

ebuild-writing/users-and-groups: add note about used_free_uidgids.sh

 - it's a helper script that suggests the next free UID, GID or UID+GID for
   the user, while printing number of available IDs too.

Closes: https://github.com/gentoo/devmanual/pull/189
Signed-off-by: Joonas Niilola <juippis <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 388b97d..9b2b49d 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -16,9 +16,10 @@ categories.
 First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID
 assignment list</uri> and choose a free UID/GID in the range between
 101 and 499. If you are adding a user and a group with the same name,
-use the same number for their UID and GID, respectively. When in
-doubt,
-take the next free number from 499 downwards.
+use the same number for their UID and GID, respectively. When in doubt,
+take the next free number from 499 downwards. The helper script
+<c>./bin/used_free_uidgids.sh</c> available in the data/api.git repository can
+be used to find the next available UID or GID.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Ulrich Müller]

commit:     56eb6bc591c3daff893e9060faed0c04b4adb7f1
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Thu Jan 23 19:29:35 2020 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Thu Jan 23 19:29:35 2020 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=56eb6bc5

ebuild-writing/users-and-groups: Use example ebuilds from tree.

The acct-user/group ebuilds for suricata are rather typical examples,
so replace the fictitious user 123 by them.

This also has ${PN} as single element in ACCT_USER_GROUPS, and it
drops the uncommon ACCT_USER_{SHELL,HOME{,_OWNER,_PERMS}} variables
from the example.

Original patch from Michael Orlitzky <mjo <AT> gentoo.org> (who asked me to
put my own name on it).

Closes: https://bugs.gentoo.org/702508
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 22 +++++++++-------------
 1 file changed, 9 insertions(+), 13 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 184f890..294d558 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -42,8 +42,8 @@ and must not be used for new packages.
 
 <p>
 Group ebuilds are placed in <c>acct-group</c> category, with the package name
-matching the group name.  The following can be used as a template for writing
-group ebuilds:
+matching the group name. The following ebuild for <c>acct-group/suricata</c>
+can be used as a template for writing group ebuilds:
 </p>
 
 <pre>
@@ -54,8 +54,8 @@ EAPI=7
 
 inherit acct-group
 
-DESCRIPTION="Meaningful description of the group"
-ACCT_GROUP_ID=123
+DESCRIPTION="Group for Suricata IDS"
+ACCT_GROUP_ID=477
 </pre>
 
 <p>
@@ -71,8 +71,8 @@ ACCT_GROUP_ID=123
 
 <p>
 User ebuilds are placed in <c>acct-user</c> category, with the package name
-matching the user name.  The following can be used as a template for writing
-user ebuilds:
+matching the user name. The following ebuild for <c>acct-user/suricata</c>
+can be used as a template for writing user ebuilds:
 </p>
 
 <pre>
@@ -83,13 +83,9 @@ EAPI=7
 
 inherit acct-user
 
-DESCRIPTION="Meaningful description of the user"
-ACCT_USER_ID=123
-ACCT_USER_SHELL=/usr/bin/foo
-ACCT_USER_HOME=/var/lib/foo
-ACCT_USER_HOME_OWNER=foo:bar
-ACCT_USER_HOME_PERMS=0775
-ACCT_USER_GROUPS=( foo bar baz )
+DESCRIPTION="User for Suricata IDS"
+ACCT_USER_ID=477
+ACCT_USER_GROUPS=( ${PN} )
 
 acct-user_add_deps
 </pre>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     bd6d454f759e735611b6bd6cc85c0c82379b29fd
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Thu Dec 26 22:16:02 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Dec 26 22:16:02 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=bd6d454f

ebuild-writing/users-and-groups: post-merge enhancements

Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 1bb87b3..c556fd9 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -14,16 +14,18 @@ categories.
 
 <p>
 First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID
-assignment list</uri> and choose a free UID/GID in range 101..499. If you are
-adding a matching user and group, use the same number for both. When in doubt,
+assignment list</uri> and choose a free UID/GID in the range between
+101 and 499. If you are adding a user and a group with the same name,
+use the same number for their UID and GID, respectively. When in
+doubt,
 take the next free number from 499 downwards.
 </p>
 
 <p>
-The aforementioned list can be found in the
-<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri> repository
-on <c>git.gentoo.org</c>. Add your new user(s) and group(s)
-to the <c>uid-gid.txt</c> file and push them before adding the actual packages.
+Add your new user(s) and group(s) to the <c>uid-gid.txt</c> file
+located in the
+<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri>
+repository and push them before adding the actual packages.
 This counts as reserving the identifiers and will prevent collisions.
 Afterwards, you can push the new ebuilds.
 </p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     19a7ba32b83fc16f51f907358a978fe6ace4bedb
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Fri Dec 20 16:47:23 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Thu Dec 26 22:01:53 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=19a7ba32

ebuild-writing/users-and-groups: Update policy

Closes: https://github.com/gentoo/devmanual/pull/125
Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 29 +++++++++++++++++------------
 1 file changed, 17 insertions(+), 12 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 26d23ab..1bb87b3 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -6,21 +6,26 @@
 <body>
 <p>
 Creating users and groups is governed by <uri
-link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>.  It is implemented
-via <c>acct-user</c> and <c>acct-group</c> eclasses.
+link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>. It is implemented
+via <c>acct-user</c> and <c>acct-group</c> eclasses. New users and groups
+are created as packages respectively in <c>acct-user</c> and <c>acct-group</c>
+categories.
 </p>
 
 <p>
-New users and groups are created as packages respectively in <c>acct-user</c>
-and <c>acct-group</c> categories.  First, choose UIDs/GIDs that are not used by
-any other package.  You should consult the <uri
-link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/UID_GID_Assignment">
-UID/GID assignment list</uri> maintained by the QA project, and possibly the
-UID/GID registries maintained by other distributions that are linked on the
-same page.  Afterwards, send the proposed ebuilds to the <c>gentoo-dev</c>
-mailing list for review.  The naming conventions for user and group ebuilds are
-explained in the following sections. Finally, after getting positive reviews,
-commit the new user and group packages.
+First, check the <uri link="https://api.gentoo.org/uid-gid.txt">UID/GID
+assignment list</uri> and choose a free UID/GID in range 101..499. If you are
+adding a matching user and group, use the same number for both. When in doubt,
+take the next free number from 499 downwards.
+</p>
+
+<p>
+The aforementioned list can be found in the
+<uri link="https://gitweb.gentoo.org/data/api.git">data/api.git</uri> repository
+on <c>git.gentoo.org</c>. Add your new user(s) and group(s)
+to the <c>uid-gid.txt</c> file and push them before adding the actual packages.
+This counts as reserving the identifiers and will prevent collisions.
+Afterwards, you can push the new ebuilds.
 </p>
 
 <p>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Ulrich Müller]

commit:     7a723385b93d3b864f17a9f14b1de73b734794bd
Author:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
AuthorDate: Tue Dec 10 08:30:13 2019 +0000
Commit:     Ulrich Müller <ulm <AT> gentoo <DOT> org>
CommitDate: Tue Dec 10 08:31:57 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=7a723385

ebuild-writing/users-and-groups: Fix document structure.

Fixes: 9613e9e69ae16e6981f90135f92811ded641b52c
Acked-by: Göktürk Yüksek <gokturk <AT> gentoo.org>
Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 1a811bc..26d23ab 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -116,6 +116,7 @@ re-evaluate your user's name, shell, home directory, and its
 permissions. Our GLEP 81 implementation will reveal many user
 management issues that were allowed to fester in the past.
 </p>
+</body>
 
 <subsection>
 <title>Choosing a shell</title>
@@ -258,6 +259,9 @@ usually exploitable.
 </body>
 </subsection>
 
+<subsection>
+<title>Epilogue</title>
+<body>
 <p>
 These suggestions are not rules and are not written in stone, except
 perhaps for the world-writable warning. There are packages in the tree
@@ -273,6 +277,7 @@ Unless your package is exceptional, though, following these guidelines
 will minimize the potential for problems down the road.
 </p>
 </body>
+</subsection>
 </section>
 
 <section>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     9613e9e69ae16e6981f90135f92811ded641b52c
Author:     Michael Orlitzky <mjo <AT> gentoo <DOT> org>
AuthorDate: Sun Sep  1 16:17:41 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Tue Dec 10 02:31:26 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9613e9e6

ebuild-writing/users-and-groups: GLEP 81 user data guidelines.

GLEP 81 significantly changes the way that user management is handled,
and reveals some subtle issues in existing packages that have remained
hidden until now. Many of these issues can be avoided (in GLEP 81, but
also in general) by exercising some discipline when choosing the data
for new users and groups:

  * User and group names
  * Default shell
  * Home directory
  * Home directory ownership and permissions

This commit adds a few new sections to the "Users and Groups" chapter
that explain the current best practices, and give suggestions for
choosing the user and group data listed above. The rationale for these
choices is explained, and some notable exceptions are mentioned.

Closes: https://bugs.gentoo.org/693964
Closes: https://github.com/gentoo/devmanual/pull/116
Signed-off-by: Michael Orlitzky <mjo <AT> gentoo.org>
Signed-off-by: Göktürk Yüksek <gokturk <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 169 +++++++++++++++++++++++++++++++
 1 file changed, 169 insertions(+)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 190a099..1a811bc 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -103,6 +103,175 @@ The defaults are the user and primary group for the owner, and 0755 for the
 permissions.
 </p>
 
+<important>
+Whenever possible, the default shell and home directory should be
+used. The rationale for this is explained below.
+</important>
+
+<p>
+You should embark upon a GLEP81 migration like an EAPI
+update. Rather than simply copy your user's settings into an
+<c>acct-user</c> package, you should take the opportunity to
+re-evaluate your user's name, shell, home directory, and its
+permissions. Our GLEP 81 implementation will reveal many user
+management issues that were allowed to fester in the past.
+</p>
+
+<subsection>
+<title>Choosing a shell</title>
+<body>
+<p>
+In most cases, the default shell (that is, no shell) should be
+used. Services can still be started as a user who has no shell, and
+daemons are able to drop privileges to a user who has no shell. If
+necessary, the administrator can override a user's default shell with
+<c>su -s &lt;shell&gt; &lt;username&gt;</c>. This is sufficient for
+testing, management of SSH credentials, and for initial configuration
+in an ebuild's <c>pkg_config</c> phase.
+</p>
+<p>
+An obvious exception to this rule is if a human being will need to log
+into the account interactively, as is the case with the <c>root</c>
+user. Other exceptions certainly exist, but should be evaluated
+case-by-case. In other words, if you haven't checked, don't set your
+user's shell to <c>/bin/bash</c> because you think he <e>might</e>
+need it.
+</p>
+<p>
+The goal here is twofold. First, the principle of least privilege says
+that if a user doesn't need a real shell, he shouldn't have one. And
+along those same lines, not having a shell gives the system
+administrator some peace of mind: he doesn't have to be as concerned
+with whether or not that user has a password (and how strong it is),
+or whether or not its filesystem permissions are all set correctly, or
+whether or not it can log in via SSH, et cetera.
+</p>
+</body>
+</subsection>
+
+<subsection>
+<title>Choosing a home directory</title>
+<body>
+<p>
+In most cases, the default home directory (that is, no home directory)
+should be used. GLEP81 changed two aspects of user management with
+respect to home directories:
+</p>
+
+<ol>
+  <li>
+    Creating a user can now modify the permissions on an existing
+    directory. Should the need arise, this is necessary for a new
+    version of an <c>acct-user</c> package to be able to fix the
+    ownership and permissions of its home directory.
+  </li>
+  <li>
+    All user data aside from the username became non-local to ebuilds
+    that depend on that user. This is merely a side-effect of moving
+    the user creation out of the client package, and into a separate
+    <c>acct-user</c> package.
+  </li>
+</ol>
+
+<p>
+The first item means that you should be conservative when choosing a
+home directory. If at all possible, avoid choosing a home directory
+that is used by another package. In particular, no two
+<c>acct-user</c> packages should use the same home directory. At best,
+the ownership and permissions on a shared home directory would need to
+be kept synchronized between all packages that share it. At worst, one
+package goes out-of-sync and introduces a security hole for the others
+who no longer have the expected permissions.
+</p>
+<p>
+The second item means that if your package requires a user, you can
+no longer be sure of that user's home directory or its ownership and
+permissions. If your package requires a directory to be owned and
+writable by some user, then your package's ebuild should create that
+directory and ensure that it is writable by the user. In other
+words, you should not rely on the directory being created
+"transitively" by a dependency, even if that dependency is an
+<c>acct-user</c> package.
+</p>
+<p>
+In summary,
+</p>
+<ul>
+  <li>
+    Avoid using an <c>ACCT_USER_HOME</c> that belongs to another
+    package.
+  </li>
+  <li>
+    No two acct-user packages should define the same
+    <c>ACCT_USER_HOME</c>.
+  </li>
+
+  <li>
+    If for example your package's configuration needs &lt;username&gt;
+    to be able to write to <c>/var/lib/&lt;username&gt;</c>, then your
+    package's ebuild should create that directory and set its
+    ownership and permissions. Barring any other considerations, the
+    corresponding <c>acct-user</c> package should leave
+    <c>ACCT_USER_HOME</c> at its default (empty) value; setting
+    <c>ACCT_USER_HOME=/var/lib/&lt;username&gt;</c> creates
+    unnecessary duplication and risks desynchronizing the permissions.
+  </li>
+</ul>
+</body>
+</subsection>
+
+<subsection>
+<title>Choosing home directory ownership</title>
+<body>
+<p>
+In most cases, the default home directory ownership is correct.  If a
+non-default home directory is needed at all, then it should be
+writable by its user and giving ownership of it to someone else would
+prevent that. Being unwritable indicates that a shared and potentially
+sensitive location was chosen. Moreover, the fact that the home
+directory is not writable suggests that the default home directory
+(which is also not writable) would suffice instead; the home directory
+guidelines explain why the default is preferable in that case. For
+example, setting <c>ACCT_USER_HOME_OWNER="root:root"</c> is suspicious
+because it appears intended to "undo" the ownership changed by your
+user package, and that would only be necessary if the path in question
+is used by some other package.
+</p>
+</body>
+</subsection>
+
+<subsection>
+<title>Choosing home directory permissions</title>
+<body>
+<p>
+In many cases, the default home directory permissions (0755) will
+suffice. But, if your package will work with mode 0700 or 0750, then
+those are preferable. This is the principle of least privilege
+again. If your package works with a non-writable home directory, then
+you should probably be using the default of <e>no</e> home directory!
+</p>
+<warning>
+The world-writable bit should never be set in
+<c>ACCT_USER_HOME_PERMS</c>. This should never be necessary, and is
+usually exploitable.
+</warning>
+</body>
+</subsection>
+
+<p>
+These suggestions are not rules and are not written in stone, except
+perhaps for the world-writable warning. There are packages in the tree
+that <c>chroot()</c> to <c>$HOME</c>, and require that directory to be
+owned by <c>root:root</c> for security reasons. In cases like that,
+it's impossible to avoid implicitly tying the user to the package that
+needs it via the home directory, and the best you can do is attempt to
+ensure that the users and paths are unique so that no conflicts arise.
+</p>
+
+<p>
+Unless your package is exceptional, though, following these guidelines
+will minimize the potential for problems down the road.
+</p>
 </body>
 </section>
 

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     fc00e95707919314996280083e61a929e2ad61a7
Author:     Michał Górny <mgorny <AT> gentoo <DOT> org>
AuthorDate: Mon Jul 22 16:42:58 2019 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Fri Aug 30 15:33:56 2019 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=fc00e957

ebuild-writing/users-and-groups: Update for GLEP 81

Signed-off-by: Michał Górny <mgorny <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 133 ++++++++++++++++++++++---------
 1 file changed, 96 insertions(+), 37 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 536be3b..190a099 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -5,82 +5,141 @@
 
 <body>
 <p>
-If your ebuild requires a user or group to be added for a daemon, for example,
-this should be performed via the functions available in <c>user.eclass</c>.
-Regardless of whether you are adding a group or a user, this should be performed
-in the <c>pkg_setup</c> phase function. <c>pkg_setup</c> is called
-before the compile process, with
-<uri link="::general-concepts/sandbox">sandbox</uri>
-disabled, so a build that requires the user to exist will
-have it, and is also called for both binary and source packages. You may also
-use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if
-the user is not required during or before <c>src_install</c>.
+Creating users and groups is governed by <uri
+link="https://gentoo.org/glep/glep-0081.html">GLEP 81</uri>.  It is implemented
+via <c>acct-user</c> and <c>acct-group</c> eclasses.
+</p>
+
+<p>
+New users and groups are created as packages respectively in <c>acct-user</c>
+and <c>acct-group</c> categories.  First, choose UIDs/GIDs that are not used by
+any other package.  You should consult the <uri
+link="https://wiki.gentoo.org/wiki/Project:Quality_Assurance/UID_GID_Assignment">
+UID/GID assignment list</uri> maintained by the QA project, and possibly the
+UID/GID registries maintained by other distributions that are linked on the
+same page.  Afterwards, send the proposed ebuilds to the <c>gentoo-dev</c>
+mailing list for review.  The naming conventions for user and group ebuilds are
+explained in the following sections. Finally, after getting positive reviews,
+commit the new user and group packages.
+</p>
+
+<p>
+The historical way of using <c>user.eclass</c> directly is now deprecated
+and must not be used for new packages.
 </p>
 </body>
 
 <section>
-<title>Adding Groups</title>
+<title>Group ebuilds</title>
 <body>
 
 <p>
-To add a group, use the <c>enewgroup</c> function:
+Group ebuilds are placed in <c>acct-group</c> category, with the package name
+matching the group name.  The following can be used as a template for writing
+group ebuilds:
 </p>
 
 <pre>
-enewgroup &lt;name&gt; [gid]
+# Copyright 2019 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI=7
+
+inherit acct-group
+
+DESCRIPTION="Meaningful description of the group"
+ACCT_GROUP_ID=123
 </pre>
 
 <p>
-By default the next available group ID is selected. To set a specfic group ID,
-pass it an extra argument to <c>enewgroup</c>.
+<c>ACCT_GROUP_ID</c> must be set to the requested GID.
 </p>
 
-<note>
-Group IDs should rarely be hardcoded. If this is the case, you should
-probably check first on gentoo-dev.
-</note>
-
 </body>
 </section>
 
 <section>
-<title>Adding Users</title>
+<title>User ebuilds</title>
 <body>
 
 <p>
-To add a user, use the <c>enewuser</c> function:
+User ebuilds are placed in <c>acct-user</c> category, with the package name
+matching the user name.  The following can be used as a template for writing
+user ebuilds:
 </p>
 
 <pre>
-enewuser &lt;user&gt; [uid] [shell] [homedir] [groups]
+# Copyright 2019 Gentoo Authors
+# Distributed under the terms of the GNU General Public License v2
+
+EAPI=7
+
+inherit acct-user
+
+DESCRIPTION="Meaningful description of the user"
+ACCT_USER_ID=123
+ACCT_USER_SHELL=/usr/bin/foo
+ACCT_USER_HOME=/var/lib/foo
+ACCT_USER_HOME_OWNER=foo:bar
+ACCT_USER_HOME_PERMS=0775
+ACCT_USER_GROUPS=( foo bar baz )
+
+acct-user_add_deps
 </pre>
 
 <p>
-By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user
-ID or group ID to the new user or group - if not, you explicitly have to specify
-one.
+<c>ACCT_USER_ID</c> must be set to the requested GID.  <c>ACCT_USER_GROUPS</c>
+should list all the groups user belongs to, the primary group first.  All
+the other keys are optional.
 </p>
 
 <p>
-Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do
-not want to specify a fixed user ID however but do want to set a specific shell,
-for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other
-parameter where you want to keep the default setting.
+<c>ACCT_USER_SHELL</c> can be used to set the shell for the user.  If unset,
+the best system equivalent of nologin is used.  <c>ACCT_USER_HOME</c> specifies
+the home directory, with <c>/dev/null</c> being the default.
+<c>ACCT_USER_HOME_OWNER</c> can be used to override the ownership of the home
+directory, and <c>ACCT_USER_HOME_PERMS</c> to override the default permissions.
+The defaults are the user and primary group for the owner, and 0755 for the
+permissions.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Utilizing users and groups in packages</title>
+<body>
+
+<p>
+In order to make your package install specific users and groups, specify them
+as dependencies.  Accounts needed at build time must be included
+in <c>DEPEND</c>, and accounts needed at runtime must be included
+in <c>RDEPEND</c>.
 </p>
 
 <p>
-Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and
-wrapped correctly, for example:
+For example, an ebuild requiring the user and group <c>foo</c> at runtime would
+specify:
 </p>
 
 <pre>
-enewuser frozd -1 -1 -1 "backup,frozd"
+RDEPEND="
+    acct-user/foo
+    acct-group/foo"
 </pre>
 
-<note>
-User IDs should rarely be hardcoded. If this is the case, you should
-probably check first on gentoo-dev.
-</note>
+<p>
+This would also be sufficient if ownership of installed files were set
+in <c>pkg_preinst</c>.  However, if the ebuild needs the user and group
+to be present at build-time already, it would specify:
+</p>
+
+<pre>
+RDEPEND="
+    acct-user/foo
+    acct-group/foo"
+DEPEND="${RDEPEND}"
+</pre>
 
 </body>
 </section>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Göktürk Yüksek]

commit:     b6eb727944e8fffc8c9b9e2ee97944007a3cc850
Author:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
AuthorDate: Mon Aug 29 17:58:03 2016 +0000
Commit:     Göktürk Yüksek <gokturk <AT> gentoo <DOT> org>
CommitDate: Mon Aug 29 17:58:03 2016 +0000
URL:        https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=b6eb7279

ebuild-writing/users-and-groups: clarify the language wrt sandbox in pkg_setup.

pkg_setup is not sandbox safe, it's sandbox-disabled.

Reported-By: David Seifert <soap <AT> gentoo.org>

 ebuild-writing/users-and-groups/text.xml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 5030318..e1d0fcd 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -8,8 +8,10 @@
 If your ebuild requires a user or group to be added for a daemon, for example,
 this should be performed via the functions available in <c>user.eclass</c>.
 Regardless of whether you are adding a group or a user, this should be performed
-in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe,
-is called before the compile process so a build that requires the user to exist will
+in the <c>pkg_setup</c> phase function. <c>pkg_setup</c> is called
+before the compile process, with
+<uri link="::general-concepts/sandbox">sandbox</uri>
+disabled, so a build that requires the user to exist will
 have it, and is also called for both binary and source packages. You may also
 use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if
 the user is not required during or before <c>src_install</c>.

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Markos Chandras]

commit:     e295e156782236a015c8eecc3f396c30be1806c6
Author:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
AuthorDate: Fri May 10 18:54:24 2013 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Fri May 10 18:54:24 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=e295e156

users-and-groups: enew{user,group} functions moved to user.eclass

Fixes bug #401187

---
 ebuild-writing/users-and-groups/text.xml |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index 2dfbedb..5030318 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -6,7 +6,7 @@
 <body>
 <p>
 If your ebuild requires a user or group to be added for a daemon, for example,
-this should be performed via the functions available in <c>eutils.eclass</c>.
+this should be performed via the functions available in <c>user.eclass</c>.
 Regardless of whether you are adding a group or a user, this should be performed
 in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe,
 is called before the compile process so a build that requires the user to exist will

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Markos Chandras]

commit:     f8c2e3f3382257ece2ff7441ec56af669ccefd9d
Author:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
AuthorDate: Mon May  6 20:50:56 2013 +0000
Commit:     Markos Chandras <hwoarang <AT> gentoo <DOT> org>
CommitDate: Mon May  6 20:50:56 2013 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=f8c2e3f3

users-and-groups: Replace second pkg_setup reference with pkg_postinst

Fixes bug #460918

---
 ebuild-writing/users-and-groups/text.xml |    4 ++--
 1 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index c7d0983..2dfbedb 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -10,8 +10,8 @@ this should be performed via the functions available in <c>eutils.eclass</c>.
 Regardless of whether you are adding a group or a user, this should be performed
 in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe,
 is called before the compile process so a build that requires the user to exist will
-have it, and is also called for both binary and source packages. You may also 
-use the <c>pkg_preinst</c> or <c>pkg_setup</c> functions for user creation, if
+have it, and is also called for both binary and source packages. You may also
+use the <c>pkg_preinst</c> or <c>pkg_postinst</c> functions for user creation, if
 the user is not required during or before <c>src_install</c>.
 </p>
 </body>

[gentoo-commits] proj/devmanual:master commit in: ebuild-writing/users-and-groups/

[Richard Freeman]

commit:     ab086a42a70e1a8d20184a7f3647fcfe9d090478
Author:     Richard Freeman <rich0 <AT> gentoo <DOT> org>
AuthorDate: Sat Nov  3 18:41:32 2012 +0000
Commit:     Richard Freeman <rich0 <AT> gentoo <DOT> org>
CommitDate: Sat Nov  3 18:41:32 2012 +0000
URL:        http://git.overlays.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=ab086a42

Fix bug 293629.  pkg_preinst follows src_install.

---
 ebuild-writing/users-and-groups/text.xml |    2 +-
 1 files changed, 1 insertions(+), 1 deletions(-)

diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
index c48e820..c7d0983 100644
--- a/ebuild-writing/users-and-groups/text.xml
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -12,7 +12,7 @@ in the <c>pkg_setup</c> function: <c>pkg_setup</c> is sandbox-safe,
 is called before the compile process so a build that requires the user to exist will
 have it, and is also called for both binary and source packages. You may also 
 use the <c>pkg_preinst</c> or <c>pkg_setup</c> functions for user creation, if
-the user is not required during <c>src_compile</c>.
+the user is not required during or before <c>src_install</c>.
 </p>
 </body>