Copyright © 2003 AddUser-NG Development Team
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
List of Examples
Table of Contents
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.
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.
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
The authors of the program are (alphabetical order):
Table of Contents
This chapter describes the ways of installing AddUser-NG
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 “cdk” User Interface (Debian package: libcdk-perl)
Quota, if you intend to use “Quota” plugin (Debian package: libquota-perl)
In order to install AddUser-NG from the source, follow these steps:
Get the most recent program sources. You can do this in the traditional way:
from the WWW of this project: http://adduser.linux.pl/download/
using an anonymous ftp: ftp://ftp.adduser.linux.pl/
or by an anonymous access to BitKeeper repository :
bash$
bk clone bk://bk.adduser.linux.pl/stable AddUser-NG
In case when sources were downloaded via www or ftp, unpack them in this way:
bash$
bzcat AddUser-NG-current.tar.bz2 | tar x
Change directory to the source directory:
bash$
cd AddUser-NG
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
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
If you want to install AddUser-NG from Debian packages go through following steps:
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 |
execute following commands (as root user)
|
|
You can now enjoy AddUser-NG installed on your machine.
Table of Contents
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 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:
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.
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 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.
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.
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)
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 ...
[GroupOfTheOptions]
in this file appears only one and is called
[adduser]
, it should not be changed.
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
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
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.
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.
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)
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.
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.
Table of Contents
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
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.
This is a list of most common questions with answers:
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
| |
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. |