summaryrefslogtreecommitdiff
path: root/eclass/user.eclass
blob: 02e1074fe4d68f319f5f70a06ec67c150e71059c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
# Copyright 1999-2022 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

# @DEAD
# @ECLASS: user.eclass
# @MAINTAINER:
# base-system@gentoo.org (Linux)
# Michał Górny <mgorny@gentoo.org> (NetBSD)
# @SUPPORTED_EAPIS: 6 7 8
# @BLURB: user management in ebuilds
# @DEPRECATED: acct-user/acct-group packages
# @DESCRIPTION:
# The user eclass contains a suite of functions that allow ebuilds
# to quickly make sure users in the installed system are sane.

case ${EAPI} in
	6|7) ;;
	8)
		if [[ ${CATEGORY} != acct-* ]]; then
			eerror "In EAPI ${EAPI}, packages must not inherit user.eclass"
			eerror "unless they are in the acct-user or acct-group category."
			eerror "Migrate your package to GLEP 81 user/group management,"
			eerror "or inherit user-info if you need only the query functions."
			die "Invalid \"inherit user\" in EAPI ${EAPI}"
		fi
		;;
	*) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;;
esac

if [[ -z ${_USER_ECLASS} ]]; then
_USER_ECLASS=1

inherit user-info

# @FUNCTION: _user_assert_pkg_phase
# @INTERNAL
# @USAGE: <calling func name>
# @DESCRIPTION:
# Raises an alert if the phase is not suitable for user.eclass usage.
_user_assert_pkg_phase() {
	case ${EBUILD_PHASE} in
	setup|preinst|postinst|prerm|postrm) ;;
	*)
		eerror "'$1()' called from '${EBUILD_PHASE}' phase which is not OK:"
		eerror "You may only call from pkg_{setup,{pre,post}{inst,rm}} functions."
		eerror "Package has serious QA issues.  Please file a bug."
		die "Bad package!  ${1} is only for use in some pkg_* functions!"
	esac
}

# @FUNCTION: user_get_nologin
# @INTERNAL
# @DESCRIPTION:
# Find an appropriate 'nologin' shell for the platform, and output
# its path.
user_get_nologin() {
	local eshell

	for eshell in /sbin/nologin /usr/sbin/nologin /bin/false /usr/bin/false /dev/null ; do
		[[ -x ${ROOT}${eshell} ]] && break
	done

	if [[ ${eshell} == "/dev/null" ]] ; then
		ewarn "Unable to identify the shell to use, proceeding with userland default."
		case ${USERLAND} in
			GNU)    eshell="/bin/false" ;;
			BSD)    eshell="/sbin/nologin" ;;
			Darwin) eshell="/usr/sbin/nologin" ;;
			*) die "Unable to identify the default shell for userland ${USERLAND}"
		esac
	fi

	echo "${eshell}"
}

# @FUNCTION: enewuser
# @USAGE: <user> [-F] [-M] [uid] [shell] [homedir] [groups]
# @DESCRIPTION:
# Same as enewgroup, you are not required to understand how to properly add
# a user to the system.  The only required parameter is the username.
# Default uid is (pass -1 for this) next available, default shell is
# /bin/false, default homedir is /dev/null, and there are no default groups.
#
# If -F is passed, enewuser will always enforce specified UID and fail if it
# can not be assigned.
# If -M is passed, enewuser does not create the home directory if it does not
# exist.
enewuser() {
	if [[ ${EUID} -ne 0 ]] ; then
		ewarn "Insufficient privileges to execute ${FUNCNAME[0]}"
		return 0
	fi
	_user_assert_pkg_phase ${FUNCNAME}

	local create_home=1 force_uid=
	while [[ ${1} == -* ]]; do
		case ${1} in
			-F) force_uid=1;;
			-M) create_home=;;
			*) die "${FUNCNAME}: invalid option ${1}";;
		esac
		shift
	done

	# get the username
	local euser=${1}; shift
	if [[ -z ${euser} ]] ; then
		eerror "No username specified!"
		die "Cannot call enewuser without a username"
	fi

	# lets see if the username already exists
	if [[ -n $(egetent passwd "${euser}") ]] ; then
		return 0
	fi
	elog "Adding user '${euser}' to your system ..."

	# options to pass to useradd
	local opts=()

	# handle for ROOT != /
	[[ -n ${ROOT} ]] && opts+=( --prefix "${ROOT}" )

	# handle uid
	local euid=${1}; shift
	if [[ -n ${euid} && ${euid} != -1 ]] ; then
		if [[ ${euid} -ge 0 ]] ; then
			if [[ -n $(egetent passwd ${euid}) ]] ; then
				[[ -n ${force_uid} ]] && die "${FUNCNAME}: UID ${euid} already taken"
				euid="next"
			fi
		else
			eerror "Userid given but is not greater than or equal to 0!"
			die "${euid} is not a valid UID"
		fi
	else
		[[ -n ${force_uid} ]] && die "${FUNCNAME}: -F with uid==-1 makes no sense"
		euid="next"
	fi
	if [[ ${euid} == "next" ]] ; then
		for ((euid = 999; euid >= 101; euid--)); do
			[[ -z $(egetent passwd ${euid}) ]] && break
		done
		[[ ${euid} -ge 101 ]] || die "${FUNCNAME}: no free UID found"
	fi
	opts+=( -u ${euid} )
	elog " - Userid: ${euid}"

	# handle shell
	local eshell=${1}; shift
	if [[ ! -z ${eshell} ]] && [[ ${eshell} != "-1" ]] ; then
		if [[ ! -e ${ROOT}${eshell} ]] ; then
			eerror "A shell was specified but it does not exist!"
			die "${eshell} does not exist in ${ROOT}"
		fi
		if [[ ${eshell} == */false || ${eshell} == */nologin ]] ; then
			eerror "Do not specify ${eshell} yourself, use -1"
			die "Pass '-1' as the shell parameter"
		fi
	else
		eshell=$(user_get_nologin)
	fi
	elog " - Shell: ${eshell}"
	opts+=( -s "${eshell}" )

	# handle homedir
	local ehome=${1}; shift
	if [[ -z ${ehome} ]] || [[ ${ehome} == "-1" ]] ; then
		ehome="/dev/null"
	fi
	elog " - Home: ${ehome}"
	opts+=( -d "${ehome}" )

	# handle groups
	local egroups=${1}; shift
	local g egroups_arr
	IFS="," read -r -a egroups_arr <<<"${egroups}"
	if [[ ${#egroups_arr[@]} -gt 0 ]] ; then
		local defgroup exgroups
		for g in "${egroups_arr[@]}" ; do
			if [[ -z $(egetent group "${g}") ]] ; then
				eerror "You must add group ${g} to the system first"
				die "${g} is not a valid GID"
			fi
			if [[ -z ${defgroup} ]] ; then
				defgroup=${g}
			else
				exgroups+=",${g}"
			fi
		done
		opts+=( -g "${defgroup}" )
		if [[ ! -z ${exgroups} ]] ; then
			opts+=( -G "${exgroups:1}" )
		fi
	fi
	elog " - Groups: ${egroups:-(none)}"

	# handle extra args
	if [[ $# -gt 0 ]] ; then
		die "extra arguments no longer supported; please file a bug"
	else
		local comment="added by portage for ${PN}"
		opts+=( -c "${comment}" )
		elog " - GECOS: ${comment}"
	fi

	# add the user
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		pw useradd "${euser}" "${opts[@]}" || die
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix option."
			ewarn "Please use: \"useradd ${opts[@]} ${euser}\" in a chroot"
		else
			useradd "${opts[@]}" "${euser}" || die
		fi
		;;

	*-openbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "OpenBSD's usermod does not support --prefix option."
			ewarn "Please use: \"useradd ${opts[@]} ${euser}\" in a chroot"
		else
			# all ops the same, except the -g vs -g/-G ...
			useradd -u ${euid} -s "${eshell}" \
				-d "${ehome}" -g "${egroups}" "${euser}" || die
		fi

		;;

	*)
		useradd -M -N -r "${opts[@]}" "${euser}" || die
		;;
	esac

	if [[ -n ${create_home} && ! -e ${ROOT}/${ehome} ]] ; then
		elog " - Creating ${ehome} in ${ROOT}"
		mkdir -p "${ROOT}/${ehome}"
		# Use UID if we are in another ROOT than /
		if [[ -n "${ROOT}" ]]; then
			euser=$(egetent passwd ${euser} | cut -d: -f3)
		fi
		chown "${euser}" "${ROOT}/${ehome}"
		chmod 755 "${ROOT}/${ehome}"
	fi
}

# @FUNCTION: enewgroup
# @USAGE: <group> [gid]
# @DESCRIPTION:
# This function does not require you to understand how to properly add a
# group to the system.  Just give it a group name to add and enewgroup will
# do the rest.  You may specify the gid for the group or allow the group to
# allocate the next available one.
#
# If -F is passed, enewgroup will always enforce specified GID and fail if it
# can not be assigned.
enewgroup() {
	if [[ ${EUID} -ne 0 ]] ; then
		ewarn "Insufficient privileges to execute ${FUNCNAME[0]}"
		return 0
	fi
	_user_assert_pkg_phase ${FUNCNAME}

	local force_gid=
	while [[ ${1} == -* ]]; do
		case ${1} in
			-F) force_gid=1;;
			*) die "${FUNCNAME}: invalid option ${1}";;
		esac
		shift
	done

	# get the group
	local egroup=${1}; shift
	if [[ -z ${egroup} ]] ; then
		eerror "No group specified!"
		die "Cannot call enewgroup without a group"
	fi

	# see if group already exists
	if [[ -n $(egetent group "${egroup}") ]] ; then
		return 0
	fi
	elog "Adding group '${egroup}' to your system ..."

	# handle gid
	local egid=${1}; shift
	if [[ -n ${egid} && ${egid} != -1 ]] ; then
		if [[ ${egid} -ge 0 ]] ; then
			if [[ -n $(egetent group ${egid}) ]] ; then
				[[ -n ${force_gid} ]] && die "${FUNCNAME}: GID ${egid} already taken"
				egid="next available; requested gid taken"
			fi
		else
			eerror "Groupid given but is not greater than or equal to 0!"
			die "${egid} is not a valid GID"
		fi
	else
		[[ -n ${force_gid} ]] && die "${FUNCNAME}: -F with gid==-1 makes no sense"
		egid="next available"
	fi
	elog " - Groupid: ${egid}"

	# handle different ROOT
	local opts
	[[ -n ${ROOT} ]] && opts=( --prefix "${ROOT}" )

	# handle extra
	if [[ $# -gt 0 ]] ; then
		die "extra arguments no longer supported; please file a bug"
	fi

	# Some targets need to find the next available GID manually
	_enewgroup_next_gid() {
		if [[ ${egid} == *[!0-9]* ]] ; then
			# Non numeric
			for ((egid = 999; egid >= 101; egid--)) ; do
				[[ -z $(egetent group ${egid}) ]] && break
			done
			[[ ${egid} -ge 101 ]] || die "${FUNCNAME}: no free GID found"
		fi
	}

	# add the group
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		_enewgroup_next_gid
		pw groupadd "${opts[@]}" "${egroup}" -g ${egid} || die
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix <dir> option."
			ewarn "Please use: \"groupadd -g ${egid} ${opts[@]} ${egroup}\" in a chroot"
		else
			_enewgroup_next_gid
			groupadd -g ${egid} "${opts[@]}" "${egroup}" || die
		fi
		;;

	*)
		if [[ ${egid} == *[!0-9]* ]] ; then
			# Non numeric; let groupadd figure out a GID for us
			#
			true # Do nothing but keep the previous comment.
		else
			opts+=( -g ${egid} )
		fi
		# We specify -r so that we get a GID in the system range from login.defs
		groupadd -r "${opts[@]}" "${egroup}" || die
		;;
	esac
}

# @FUNCTION: esethome
# @USAGE: <user> <homedir>
# @DESCRIPTION:
# Update the home directory in a platform-agnostic way.
# Required parameters is the username and the new home directory.
# Specify -1 if you want to set home to the enewuser default
# of /dev/null.
# If the new home directory does not exist, it is created.
# Any previously existing home directory is NOT moved.
esethome() {
	_user_assert_pkg_phase ${FUNCNAME}

	# get the username
	local euser=${1}; shift
	if [[ -z ${euser} ]] ; then
		eerror "No username specified!"
		die "Cannot call esethome without a username"
	fi

	# lets see if the username already exists
	if [[ -z $(egetent passwd "${euser}") ]] ; then
		ewarn "User does not exist, cannot set home dir -- skipping."
		return 1
	fi

	# Handle different ROOT
	local opts
	[[ -n ${ROOT} ]] && opts=( --prefix "${ROOT}" )

	# handle homedir
	local ehome=${1}; shift
	if [[ -z ${ehome} ]] ; then
		eerror "No home directory specified!"
		die "Cannot call esethome without a home directory or '-1'"
	fi

	if [[ ${ehome} == "-1" ]] ; then
		ehome="/dev/null"
	fi

	# exit with no message if home dir is up to date
	if [[ $(egethome "${euser}") == ${ehome} ]]; then
		return 0
	fi

	elog "Updating home for user '${euser}' ..."
	elog " - Home: ${ehome}"

	# ensure home directory exists, otherwise update will fail
	if [[ ! -e ${ROOT}/${ehome} ]] ; then
		elog " - Creating ${ehome} in ${ROOT}"
		mkdir -p "${ROOT}/${ehome}"
		chown "${euser}" "${ROOT}/${ehome}"
		chmod 755 "${ROOT}/${ehome}"
	fi

	# update the home directory
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		pw usermod "${opts[@]}" "${euser}" -d "${ehome}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update home"
		eerror "There was an error when attempting to update the home directory for ${euser}"
		eerror "Please update it manually on your system:"
		eerror "\t pw usermod \"${euser}\" -d \"${ehome}\""
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix <dir> option."
			ewarn "Please use: \"usermod ${opts[@]} -d ${ehome} ${euser}\" in a chroot"
		else
			usermod "${opts[@]}" -d "${ehome}" "${euser}" && return 0
			[[ $? == 8 ]] && eerror "${euser} is in use, cannot update home"
			eerror "There was an error when attempting to update the home directory for ${euser}"
			eerror "Please update it manually on your system (as root):"
			eerror "\t usermod -d \"${ehome}\" \"${euser}\""
		fi
		;;

	*)
		usermod "${opts[@]}" -d "${ehome}" "${euser}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update home"
		eerror "There was an error when attempting to update the home directory for ${euser}"
		eerror "Please update it manually on your system (as root):"
		eerror "\t usermod -d \"${ehome}\" \"${euser}\""
		;;
	esac
}

# @FUNCTION: esetshell
# @USAGE: <user> <shell>
# @DESCRIPTION:
# Update the shell in a platform-agnostic way.
# Required parameters is the username and the new shell.
# Specify -1 if you want to set shell to platform-specific nologin.
esetshell() {
	_user_assert_pkg_phase ${FUNCNAME}

	# get the username
	local euser=${1}; shift
	if [[ -z ${euser} ]] ; then
		eerror "No username specified!"
		die "Cannot call esetshell without a username"
	fi

	# lets see if the username already exists
	if [[ -z $(egetent passwd "${euser}") ]] ; then
		ewarn "User does not exist, cannot set shell -- skipping."
		return 1
	fi

	# Handle different ROOT
	local opts
	[[ -n ${ROOT} ]] && opts=( --prefix "${ROOT}" )

	# handle shell
	local eshell=${1}; shift
	if [[ -z ${eshell} ]] ; then
		eerror "No shell specified!"
		die "Cannot call esetshell without a shell or '-1'"
	fi

	if [[ ${eshell} == "-1" ]] ; then
		eshell=$(user_get_nologin)
	fi

	# exit with no message if shell is up to date
	if [[ $(egetshell "${euser}") == ${eshell} ]]; then
		return 0
	fi

	elog "Updating shell for user '${euser}' ..."
	elog " - Shell: ${eshell}"

	# update the shell
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		pw usermod "${opts[@]}" "${euser}" -s "${eshell}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update shell"
		eerror "There was an error when attempting to update the shell for ${euser}"
		eerror "Please update it manually on your system:"
		eerror "\t pw usermod \"${euser}\" -s \"${eshell}\""
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix <dir> option."
			ewarn "Please use: \"usermod ${opts[@]} -s ${eshell} ${euser}\" in a chroot"
		else
			usermod "${opts[@]}" -s "${eshell}" "${euser}" && return 0
			[[ $? == 8 ]] && eerror "${euser} is in use, cannot update shell"
			eerror "There was an error when attempting to update the shell for ${euser}"
			eerror "Please update it manually on your system (as root):"
			eerror "\t usermod -s \"${eshell}\" \"${euser}\""
		fi
		;;

	*)
		usermod "${opts[@]}" -s "${eshell}" "${euser}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update shell"
		eerror "There was an error when attempting to update the shell for ${euser}"
		eerror "Please update it manually on your system (as root):"
		eerror "\t usermod -s \"${eshell}\" \"${euser}\""
		;;
	esac
}

# @FUNCTION: esetcomment
# @USAGE: <user> <comment>
# @DESCRIPTION:
# Update the comment field in a platform-agnostic way.
# Required parameters is the username and the new comment.
esetcomment() {
	_user_assert_pkg_phase ${FUNCNAME}

	# get the username
	local euser=${1}; shift
	if [[ -z ${euser} ]] ; then
		eerror "No username specified!"
		die "Cannot call esetcomment without a username"
	fi

	# lets see if the username already exists
	if [[ -z $(egetent passwd "${euser}") ]] ; then
		ewarn "User does not exist, cannot set comment -- skipping."
		return 1
	fi

	# Handle different ROOT
	local opts
	[[ -n ${ROOT} ]] && opts=( --prefix "${ROOT}" )

	# handle comment
	local ecomment=${1}; shift
	if [[ -z ${ecomment} ]] ; then
		eerror "No comment specified!"
		die "Cannot call esetcomment without a comment"
	fi

	# exit with no message if comment is up to date
	if [[ $(egetcomment "${euser}") == ${ecomment} ]]; then
		return 0
	fi

	elog "Updating comment for user '${euser}' ..."
	elog " - Comment: ${ecomment}"

	# update the comment
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		pw usermod "${opts[@]}" "${euser}" -c "${ecomment}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update comment"
		eerror "There was an error when attempting to update the comment for ${euser}"
		eerror "Please update it manually on your system:"
		eerror "\t pw usermod \"${euser}\" -c \"${ecomment}\""
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix <dir> option."
			ewarn "Please use: \"usermod ${opts[@]} -c ${ecomment} ${euser}\" in a chroot"
		else
			usermod "${opts[@]}" -c "${ecomment}" "${euser}" && return 0
			[[ $? == 8 ]] && eerror "${euser} is in use, cannot update shell"
			eerror "There was an error when attempting to update the shell for ${euser}"
			eerror "Please update it manually on your system (as root):"
			eerror "\t usermod -s \"${eshell}\" \"${euser}\""
		fi
		;;

	*)
		usermod "${opts[@]}" -c "${ecomment}" "${euser}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update comment"
		eerror "There was an error when attempting to update the comment for ${euser}"
		eerror "Please update it manually on your system (as root):"
		eerror "\t usermod -c \"${ecomment}\" \"${euser}\""
		;;
	esac
}

# @FUNCTION: esetgroups
# @USAGE: <user> <groups>
# @DESCRIPTION:
# Update the group field in a platform-agnostic way.
# Required parameters is the username and the new list of groups,
# primary group first.
esetgroups() {
	_user_assert_pkg_phase ${FUNCNAME}

	[[ ${#} -eq 2 ]] || die "Usage: ${FUNCNAME} <user> <groups>"

	# get the username
	local euser=${1}; shift

	# lets see if the username already exists
	if [[ -z $(egetent passwd "${euser}") ]] ; then
		ewarn "User does not exist, cannot set group -- skipping."
		return 1
	fi

	# handle group
	local egroups=${1}; shift

	local g egroups_arr=()
	IFS="," read -r -a egroups_arr <<<"${egroups}"
	[[ ${#egroups_arr[@]} -gt 0 ]] || die "${FUNCNAME}: no groups specified"

	for g in "${egroups_arr[@]}" ; do
		if [[ -z $(egetent group "${g}") ]] ; then
			eerror "You must add group ${g} to the system first"
			die "${g} is not a valid GID"
		fi
	done

	local defgroup=${egroups_arr[0]} exgroups_arr=()
	# sort supplementary groups to make comparison possible
	readarray -t exgroups_arr < <(printf '%s\n' "${egroups_arr[@]:1}" | sort)
	local exgroups=${exgroups_arr[*]}
	exgroups=${exgroups// /,}
	egroups=${defgroup}${exgroups:+,${exgroups}}

	# exit with no message if group membership is up to date
	if [[ $(egetgroups "${euser}") == ${egroups} ]]; then
		return 0
	fi

	local opts=( -g "${defgroup}" -G "${exgroups}" )
	elog "Updating groups for user '${euser}' ..."
	elog " - Groups: ${egroups}"

	# Handle different ROOT
	[[ -n ${ROOT} ]] && opts+=( --prefix "${ROOT}" )

	# update the group
	case ${CHOST} in
	*-freebsd*|*-dragonfly*)
		pw usermod "${euser}" "${opts[@]}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update groups"
		eerror "There was an error when attempting to update the groups for ${euser}"
		eerror "Please update it manually on your system:"
		eerror "\t pw usermod \"${euser}\" ${opts[*]}"
		;;

	*-netbsd*)
		if [[ -n "${ROOT}" ]]; then
			ewarn "NetBSD's usermod does not support --prefix <dir> option."
			ewarn "Please use: \"usermod ${opts[@]} ${euser}\" in a chroot"
		else
			usermod "${opts[@]}" "${euser}" && return 0
			[[ $? == 8 ]] && eerror "${euser} is in use, cannot update shell"
			eerror "There was an error when attempting to update the shell for ${euser}"
			eerror "Please update it manually on your system (as root):"
			eerror "\t usermod -s \"${eshell}\" \"${euser}\""
		fi
		;;

	*)
		usermod "${opts[@]}" "${euser}" && return 0
		[[ $? == 8 ]] && eerror "${euser} is in use, cannot update groups"
		eerror "There was an error when attempting to update the groups for ${euser}"
		eerror "Please update it manually on your system (as root):"
		eerror "\t usermod ${opts[*]} \"${euser}\""
		;;
	esac
}

fi