AddUser Next Generation -- Manual

Abstract

This document describes the usage (the design, the assumptions, the abilities and the configuration) of AddUser-NG program. If you want to know how to achieve the best results using this program, this document is for you.


Table of Contents

1. Introduction
What is AddUser-NG?
Why was this program created?
License for use and distribution
Authors
Robert 'teon' Olejnik
Bartosz 'liar' Oler
2. Installation
Installing from the source
Requirements
Installation
Debain GNU/Linux packages installation
3. AddUser-NG cabilities
Plugins
User interface
Configuration
adduser-ng.conf
Group files (plugins configuration)
4. Program usage
Execution
User Interface
5. FAQ - Frequently Asked Questions

List of Examples

3.1. Keyword example
3.2. Example of a keyword (that picks chars from beggining )
3.3. Example of a keyword (that picks chars from the end)
3.4. Other keywords usage
3.5. An example of valid keyword usage.
3.6. Example of invalid keywords usage
4.1. Program execution example
4.2. Example of batch UI usage

Chapter 1. Introduction

What is AddUser-NG?

AddUser-NG is a new/another/different version of adduser script (and was named after this script, as it has similar functionality). But our philosophy and assumptions were completly different. Are they better? Judge it yourself.

For people who don't know the adduser script, we can describe AddUser-NG in the following way: it is a program designed for *nix systems administrators, that can be used for the creation of accounts for the new users.

Why was this program created?

The first and main reason we created the AddUser-NG is a fact, that there is no other good simillar program (or we don't know about its existence). Apart from this, as every project, it brought us new experience, sleepless nights, and of course... lots of fun.

License for use and distribution

AddUser-NG is a free software. It can be distributed or modified under the terms of the GNU GPL version 2. Copy of the license is available at: http://www.gnu.org/copyleft/gpl.html

Authors

The authors of the program are (alphabetical order):

Robert 'teon' Olejnik

Bartosz 'liar' Oler

Chapter 2. Installation

This chapter describes the ways of installing AddUser-NG

Installing from the source

Requirements

Before you start the installation, you must install the following perl modules:

  • Config::IniFiles (Debian package: libconfig-inifiles-perl)

  • Getopt::Mixed (Debian package: libgetopt-mixed-perl)

  • XML::Simple (Debian package: libxml-simple-perl)

  • Term::ReadLine::Gnu (Debian package: libterm-readline-gnu-perl)

and also:

  • Cdk, if you intend to use “cdkUser Interface (Debian package: libcdk-perl)

  • Quota, if you intend to use “Quota” plugin (Debian package: libquota-perl)

Installation

In order to install AddUser-NG from the source, follow these steps:

  1. Get the most recent program sources. You can do this in the traditional way:

  2. In case when sources were downloaded via www or ftp, unpack them in this way:

    bash$ bzcat AddUser-NG-current.tar.bz2 | tar x
                                

  3. Change directory to the source directory:

    bash$ cd AddUser-NG
                                

  4. Next, execute as root user:

    bash# make
                                

    It will install the program and its files onto your system.

    By default the directory where files are installed is /usr, so the main executable will be placed in /usr/sbin/adduser-ng. You can change this by setting the PREFIX when executing make command, like this:

    bash# make PREFIX=/usr/local
                                    

    it will install program in /usr/local/sbin/adduser-ng.

    For the configuration files we have a simmilar situation. By default prefix is set to /, so the configuration files are installed in /etc/adduser-ng. We can change this by using CONFIG_PREFIX option, while installing, like this:

    bash# make PREFIX=/usr/local CONFIG_PREFIX=/usr/local
                                    

  5. Note

    AddUser-NG has also additional plugins, and full documentation (during the installation only plugins' documetation is installed)

    If you want to have additional plugins installed, use command (also as root):

    bash# make install_all_plugins
                                

    Of course, if you wish, you can use other PREFIX value.

    In order to install the entire documentation, type:

    bash# make install_docs
                                

Debain GNU/Linux packages installation

If you want to install AddUser-NG from Debian packages go through following steps:

  1. Add these lines to /etc/apt/sources.list, depending on what distribution you use:

    # AddUser-NG for stable
    deb http://zaron.debian.pl/debian stable main

    # AddUser-NG for testing
    deb http://zaron.debian.pl/debian testing main

    # AddUser-NG for unstable
    deb http://zaron.debian.pl/debian unstable main

  2. execute following commands (as root user)

    bash# apt-get update
    bash# apt-get install adduser-ng

You can now enjoy AddUser-NG installed on your machine.

Chapter 3. AddUser-NG cabilities

While designing AddUser-NG, we followed some guidelines, here they are:

  • module structure

  • possibilty to choose user interface

  • configuration flexibility

Thanks to these guidelines, it is the user who decides how the program is working. Now, we will describe how it was acomplished.

Plugins

Plugins extend functionality of the program. AddUser-NG itself is only capable of loading the plugins. All basic operations, like adding users or groups, is done by standard plugins, that are shipped with the program).

While configuring AddUser-NG, the user chooses which plugins are to be loaded and configures them. The precise configuration process is described in the section called “Configuration” section.

As the whole program functionality is based on plugins, it is crucial to know at least basic informations on plugins configuration.

When the plugins are loaded, the following actions are taken for each of them:

  1. Each plugin is configured, it means that the values for every plugin option are set up. If an option is not defined, user is asked for its value through UI (user interface).

    If there is an error during the configuration process, program quits, with no changes made.

  2. When all plugins are configured, the program itself starts (“plugins' execution stage”). That means the realization of all the tasks each plugin is supposed to do. It is the main stage of the AddUser-NG. At this moment user is being added, quota is set up, etc.

    If any error occurs during this stage, no further plugins are loaded, and process of restoring previous state is started. Its task is to run for each plugin (in reversed order, starting from plugin that failed to load) the rollback method, that will restore all changes made. If you are not a developer, all you really need to know is that if something fails, AddUser-NG will simply remove any changes made to the system.

In the standard program distribution you can find the following packages:

  • GroupAdd - this plugin is responsible for adding a group to the system

  • UserAdd - adds a new user

  • PasswdUser - sets a password for a new user

These plugins give only the basic functionality. In order to gain better functionality, additional plugins are available (for example the “Quota” plugin) as source packages (and Debian packages), so anyone could choose, which plugin he (or she) needs. There is also a possibility of writing your own plugins. More detailed information on this subject can be found in developer documentation.

The precise description of all plugins and their options can be found in the project documentation directory.

User interface

User interface in AddUser-NG program is used to query a user for the options' values of a certain plugin. User is asked to enter a value for a given option, when the option already has no specified value in a group configuration file. More about this issue can be found in the section called “Group files (plugins configuration)” and the section called “User Interface”.

AddUser-NG has many User Interfaces. All of them have been written as plugins, so it is easy to write and add your own User Interface. Batch, readline and cdk are shipped with the program. The first one is simmilar to “command line” in *nix systems user interface, second one is more like bash, it has a completion mechanism, history, etc. The third one is a ncurses interface. While configuration process user can choose the interface he wants.

Configuration

AddUser-NG, has a flexible configuration, that enables to automate the process of adding new system users accounts. Lets take a look into its capabilities.

adduser-ng.conf

This file is a configuration file for a program itself, it states where files (documentation, group catalog, etc) are located, it doesn't configure plugins (“group files” are used for this purpose, we will talk about them in the next chapter)

Caution

After installing the program, the only option that user should change is the User Interface, other opions should be left unchanged, unless you know what you are doing.

The file has a “dosini” syntax, so:

[GroupOfTheOptions]

# comment
option_1 = value
...
option_N = value

...
                    

Important

[GroupOfTheOptions] in this file appears only one and is called [adduser], it should not be changed.

Available options

  • groups_dir - this option tells where the groups' configuration files are

  • default_ui - using this option you can choose what user interface, should be used to comunicate with user.

  • documentation_dir - this option defines where the documentation files for every plugin are stored

Group files (plugins configuration)

In the *nix systems, natural is that a user belongs to a system group/groups. AddUser-NG has a simmilar philosophy, using “group files” as its main configuration. Group AddUser-NG can be treated as group of plugins that are executed while adding a new user, or as a system group, for which the account is being created. The best way to understand what the group files are, is by an example, so lets go on.

Group files directory is set by the groups_dir option in the main configuration file. Usually it is the /etc/AddUser-NG/groups/ directory. The group file name can be custom, as long as user remembers it. It is one of the parameters required for program execution (name of the group file that user belongs to must be specified).

Group files also have the “dosini” syntax, although there is a difference in the syntax between group files and the main configuration file. Group file looks like this:


[Name_of_the_plugin_to_be_loaded_by_program]

# comment
some_example_option = value

# this option has a keyword assigned
other_option_login_for_instance = %(main.login)

# this option is commented out so the program will ask for it.
# option = value

# this option has an empty value, program will not ask for it
# it will stay empty, assuming that this option has no value
option =

[Plugin_that_should_be_loaded_as_second]

example_option_for_second_plugin = value

[Third]

option = %(Plugin_that_should_be_loaded_as_second.example_option_for_second_plugin)
...
                    

Lets analyse this example. [PluginName] makes AddUser-NG load plugin called“[PluginName]”. Next, plugin is being configured, like this:

  • option = value - no comment is required here

  • option = %(KEYWORD) - AddUser-NG supports special keywords, which will be described later

  • # comment - everything that follows “#” is interpreted as comment and is skipped

Important

The order of the “[PluginName]” tags is important! The order in which the plugins will be configurated and loaded depends on the [PluginName] tags order in the groups' files.

Keywords

As mentioned above, AddUser-NG supports keywords, that can be used as values for plugins' options, like this:

  • %(PluginName.Option) - means: get the “Option” option of “PluginName” plugin and switch it, so the keyword %(PluginName.Option) will be replaced with desired value, for instance:

    Example 3.1.  Keyword example

    %(UserAdd.home_dir)

    will be replaced with the home directory of added user


  • %(PluginName.Option-numericvalue) - means: get “numericvalue” of chars from the beggining of “PluginName” plugin's “Option” option and replace it. for example:

    Example 3.2.  Example of a keyword (that picks chars from beggining )

    %(UserAdd.comment-1)

    will be replaced with the first comment char (Gecos)


  • %(PluginName.Option+numericvalue) - means: get “numericvalue” of chars from the end of “PluginName” plugin's “Option” option and replace it. for example:

    Example 3.3.  Example of a keyword (that picks chars from the end)

    %(GroupAdd.group_name+3)

    will be replaced with three last chars from newly created user group


There are two additional keywords, that are not a part of any plugin:

  • %(main.group) - this keyword is replaced with value of the group file name (or just the group name), to which the user was added. In other words - it is a value of the first parameter used in program execution.

  • %(main.login) - this keyword is the login name of the user we are creating (it is the second parameter used in program execution.

Note

Of course there is also a possibility of using “-” and “+” operators.

Example 3.4.  Other keywords usage

[UserAdd]
# this is usefull for people who are adding many user accounts and want
# them sorted alphabethically

home_dir = %(main.login-1)


Important

It is crutial to understand that a value have to be previously specified by program, for a keyword to allow its usage. Let's take a look on an example configuration file:

Example 3.5.  An example of valid keyword usage.

[UserAdd]
# %(main.login) keyword is automaticaly defined after program startup
# so we can use it at any time we want
home_dir = /home/%(main.login)

# 'home_dir' option is used above, so %(UserAdd,home_dir) is already defined
# this means we can use it:
comment = %(UserAdd.home_dir)
                            


According to comments the configuration file used in the exmple is valid. Although it is not a useful configuration, becouse it sets the user's home directory as value of user comment, it is only an example. Now lets take a look on the invalid configuration file:

Example 3.6.  Example of invalid keywords usage

# first the system group adding plugin will be configurated (and executed)
[GroupAdd]

# the name of newly added group, is using as a keyword the value of 'comment'
# option from 'UserAdd' plugin, which is wrong, because this option has yet
# no value, as 'UserAdd' plugin will be configurated later (after this plugin)
group_name = %(UserAdd.comment)

# load the UserAdd plugin, now notice that this plugin will be configured
# after configuring the GroupAdd plugin, because of the plugins order in this
# file.
[UserAdd]

# now the value for 'comment' is being defined, but it is already too late,
# and it is an invalid group file configuration.
comment = User %(main.login), group %(main.group)
                            


I suppose that comments used in this file make it clear why this file configure is invalid.

Few advices concerning group files configuration

By now you should already know how to configure AddUser-NG, you can go on and make your own group files now, but before you do, we have got some advices for you.

Despite the fact that each plugin can be loaded at any time you want (as you already seen, you decide in what order the plugins are loaded),it would be wise to:

  • when there is a new group set for every new user (as adduser command does), you should always load the GroupAdd plugin first (becouse group must already exist when we add new user),and then load UserAdd plugin.

  • Even if you don't add separate group for every new user (GroupAdd plugin is not needed), you should always place UserAdd plugin first in the configuraion file (it will be loaded first: configured and “executed”). It will prevent you from possible configuration mistakes, as setting quota byQuota plugin for non-existing user.

Chapter 4. Program usage

Table of Contents

Execution
User Interface

Execution

AddUser-NG has following execution syntax:

adduser-ng [[-h] | [--help]] [[-u] | [--user-interface]] [[-S] | [--skip]] [[-v] | [--verbose]] [[-V] | [--version]] group_name login

Program options:

[[-h] | [--help]]

Show help and exit.

[[-u] | [--user-interface]]

Use other user interface, than the one defined in configuration.

[[-S] | [--skip]]

In case any plugin returns information that it has been already executed, skip it silently.

[[-v] | [--verbose]]

Show more messages during program work (especially usefull for developers and users that wish to know what is happening during program work).

[[-V] | [--version]]

Print program version number and exit.

Program parameters

                    

group_name

Group name (group file name), to add new user to.

                    

login

New account name.

Example 4.1.  Program execution example

bash# adduser-ng clients
mark

User Interface

We have already wrote about user interfaces in chapter about AddUser-NG cabilities. Now, that you have knowledge about configuration, we will summarize.

User Interface in AddUser-NG, is designed to comunicate with user. It is executed when any option from any plugin needs to be configurated, its value is not set in group file or commented out. In this case, user is being informed: what option, from which plugin, some help for the option is displyed, and the default value (if the option has one). User will be asked then to enter value for this option. If user stops program execution at this moment, no changes will be made, and program will quit.

Additonaly, User Interface is called by program if errors occure, in order to make user aware of them. If -V | --verbose option is used, verbose mode is on, and program informs user about what it is doing.

As there are different User Interfaces, the way they get data and present it is also different for each one.

  • UI: readline

    This is the default interface, it gets data from user like system shell. It displays help message concerning specific option, and prompt, which is option's name. Additionally, if an option has default value, it will be automaticly set as the answer value, so that user can simply affirm it by pressing “ENTER”.

    This interface has values history, just press “up arrow” and previously entered values will appear.

  • UI: cdk

    This UI looks simmilar to dialog program, and it also acts alike. In this UI dialog windows are displayed, each has title (plugin/option name) and help concerning the option. Additionally, if option has a default value, it will be also displayed, and affirmed with “ENTER”.

  • UI: batch

    It is special UI that gets data from program parameters, it does not display anything. It is usefull for writing scripts with AddUser-NG program. Syntax is as follows:

    bash# adduser-ng Plugin_name.Option=value 
    Other_plugin_name.This_plugins_option=other_value group username
                                

    Is it clear? If it isn't take a look at an example.

    Example 4.2. Example of batch UI usage

    bash# adduser-ng UserAdd.comment="Added by bath UI" PasswdUser.passwd=qwerty123456 customers alice                    
                


    In this UI, if you give no value for an option, and it has a default one, the default one will be automaticaly used.

Chapter 5. FAQ - Frequently Asked Questions

This is a list of most common questions with answers:

5.1. Where can I find the latest program version:
5.2. In adduser package there is also deluser command. Is there DelUser-NG?
5.3. Why do you use BitKeepera instead of CVS?
5.1.

Where can I find the latest program version:

Use adresses given in instalation from sources part,or, if you are a Debian GNU/Linux User, install packages and when updating systen you will always have the latest version.

5.2.

In adduser package there is also deluser command. Is there DelUser-NG?

Acctually, AddUser-NG is basically prepared for deleting users it created, because it has the resotring mechanism, it can be done using the rollback method for each plugin in reversed order. But there is no DelUser-NG now, it will for sure be in the next version of AddUser-NG. Please be patient.

5.3.

Why do you use BitKeepera instead of CVS?

Because BitKeeper is much better! If you haven't been using it before- try and you will not regret.