Creandus Auth Modules

Author:	Mike Kelly <pioto@pioto.org>
Date:	2007-12-25
Revision:	228
Version:	0.6.0

Introduction

One of the main design features of creandus is that it is easy to add in additional modules for authentication systems in different operating systems. This document defines the necessary features of any module.

Naming

Creandus modules follow this naming scheme:

nss-userland-elibc-action
nss
The name of the Name Service Switch [1] module being used. Usually, this is either compat or files, although it could also be something like nis or ldap. This is determined by the contents of your /etc/nsswitch.conf file. For example:
# /etc/nsswitch.conf:

passwd:   compat
shadow:   compat
group:    compat

# passwd: db files nis
# shadow: db files nis
# group:  db files nis
Of main interest to these scripts are the passwd and group lines, which define the backend used for users and groups, respectively.

userland

The userland is the general style of unix utilities provided in the system, e.g. "GNU", "BSD", or "Darwin"[2].

elibc

Similar to userland, this specifies the libc implementation. This is how various flavors of BSD, for example, are distinguished. Some samples: "glibc" (for GNU/Linux), "FreeBSD", "OpenBSD", "NetBSD", "Darwin".

action

The action to be performed. This is one of "useradd", "usermod", "userdel", "groupadd", "groupmod", or "groupdel".

[1]	NSS exists on most GNU, BSD, and Solaris systems, but not on Darwin (Mac OS X) systems. For consistency, if the nsswitch.conf file cannot be found, this value should be assumed to be `compat`.

[2]	Darwin is the underlying userland for Mac OS X.

Module File

The module file consists of a header and a function. The header is just basic boilerplate; copy what you see in one of the other modules.

The function must be named as discussed above (e.g. compat-GNU-glibc-useradd()). There should be no code run in the global scope; all your variables should be local. Your file itself should be named as discussed above, with .bash appended (e.g. compat-GNU-glibv-useradd.bash). Each of the six possible actions can expect the following arguments:

useradd

Adds a user to the system.

home - ${1}

The home directory of the user to be added.

groups - ${2}

A comma-separated list of the groups this user should belong to.

shell - ${3}

The default shell for the user to be added.

uid - ${4}

The uid for the user to be added.

comment - ${5}

The GECOS comment field for the user.

name - ${6}

The name of the user to be added.

root - ${7}

The root of the system we're working in.

usermod

Modifies an existing user. Receives the same arguments as useradd.

userdel

Deletes an existing user.

name - ${1}

The name of the user to be removed.

root - ${2}

The root of the system we're working in.

groupadd

Adds a user to the system.

gid - ${1}

The gid for the group to be added.

name - ${2}

The name of the group to be added.

root - ${3}

The root of the system we're working in.

groupmod

Modifies an existing group. Receives the same arguments as groupadd.

groupdel

Deletes an existing group.

name - ${1}

The name of the user to be removed.

root - ${2}

The root of the system we're working in.

Example

Below is an example script, compat-BSD-FreeBSD-useradd.bash.in:

# Copyright 2006 Mike Kelly
# Distributed under the terms of the GNU General Public License v2
#
# See docs/auth_modules.{txt,html} for more information on these files.
#
# $Id: auth_modules.txt.in 228 2007-12-25 22:51:51Z pioto $

compat-BSD-FreeBSD-useradd() {
    local home="${1}" groups="${2}" shell="${3}"
    local uid="${4}" comment="${5}" name="${6}"
    local root="${7}"

    pw -V "${root}/etc" useradd -d "${home}" -G "${groups}" \
        -s "${shell}" -u "${uid}" -c "${comment}" "${name}"
}
# vim: ts=4 :

And here is another, compat-GNU-glibc-userdel.bash.in:

# Copyright 2006 Mike Kelly
# Distributed under the terms of the GNU General Public License v2
#
# See docs/auth_modules.{txt,html} for more information on these files.
#
# $Id: auth_modules.txt.in 228 2007-12-25 22:51:51Z pioto $

compat-GNU-glibc-userdel() {
    local name="${1}" root="${2}"

    [[ "${root}" != "/" ]] && die "Linux currently can't modify users" \
        "when ROOT != /"

    userdel "${name}"
}
# vim: ts=4 :