Fix changelog: mention which tool we modified
[mirror/userdir-ldap.git] / doc / ud-useradd.8.yo
1 mailto(admin@db.debian.org)
2 manpage(ud-useradd)(8)(17 Sep 1999)(userdir-ldap)()
3 manpagename(ud-useradd)(Interactive user addition program)
4
5 manpagesynopsis()
6   ud-useradd [options]
7    
8 manpagedescription()
9 ud-uaseradd is an interactive program for adding new users to the directory. 
10 It takes care of all steps of user addition including generating a random
11 new password and sending a greeting form letter.
12
13 The operator is taken through a set of prompts to determine the data to be
14 loaded into the directory:
15
16 startdit()
17 dit(PGP Key Fingerprint)
18 The first prompt is to determine the user's PGP key. For this to be
19 successfull the key must have already been loaded into a keyring referenced
20 by the GPG configuration file. The search specification is passed directly
21 to GPG and then the results are presented, when a single match is found then
22 it is taken as the correct key.
23
24 dit(Account Name)
25 This is the UID of the user, their login name and email local part. If the
26 name already exists then it is possible to update the account directly. This
27 feature should probably be used very infrequently as ud-info can adjust
28 all of the values.
29
30 dit(First, Last and Middle Name)
31 The proper name of the user, split into three components. The name
32 name attached to the PGP key is provided as a default. In most cases this
33 should be adaquate and correct.
34
35 dit(Email Forwarding Address)
36 The address that all general email should be forwarded to. This is analogous 
37 to a .forward file in the users home directory except that it applies
38 globally to all machines. The email address attached to the PGP key is
39 provided as a default.
40
41 dit(Debian-Private Subscription)
42 The address the user should be subscribed to debian-private with. Currently
43 this sets the field in the DB and emails a subscription form to the
44 list server.
45
46 dit(Group ID Number)
47 Main group the user will be part of. The group the user is assigned to
48 determines which welcome form they are sent. The default is taken from
49 the global configuration file
50
51 dit(UID)
52 The uid is selected automatically based on the first found free UID.
53
54 dit(Password)
55 The password can be specified if the user is not legaly able to use
56 encryption (they live in France for instance) otherwise pressing enter at 
57 this prompt will generate a random new password. The password to be entered
58 is the plain text version, the script will crypt it automatically.
59 enddit()
60
61 After the information has been collected a summary is displayed and
62 confirmation is required to proceed. Once confirmed the script will create a
63 new entry and fill it with the given values. Then it will open the greeting
64 form bf(/etc/userdir-ldap/templates/welcome-message-<GID>) and perform a
65 variable substitution before sending it. Then the debian-private subscription
66 form is sent.
67
68 It is expected that the PGP key of the user has already been inserted into a
69 local keyring known to GPG.
70
71 manpagesection(Substitution Variables)
72 A number of values are provided as substitution variables for the greeting
73 and subscription message, they are:
74
75 itemize(
76   it() __REALNAME__ The combined First/Middle/Last name
77   it() __WHOAMI__ The invoking user ID [unix ID]
78   it() __DATE__ The current date in RFC 822 form
79   it() __LOGIN__ The new users login ID
80   it() __PRIVATE__ The address to subscribe to debian-private
81   it() __EMAIL__ The normal email address of the user
82   it() __PASSWORD__ An ascii armored PGP packet containing the users 
83        password.
84   it() __LISTPASS__ The contents of the file ~/.debian-lists_passwd
85 )
86
87 manpageoptions()
88 startdit()
89 dit(bf(-u))
90 Set the authentication user. This is the user who's authority is used when 
91 accessing the LDAP directory. The default is to use the current system user
92 name.
93
94 dit(bf(-m))
95 Force resending of the greeting emails.
96
97 dit(bf(-a))
98 Use all available key rings.
99 enddit()
100
101 manpagefiles()
102 itemize(
103   it() /etc/userdir-ldap/userdir-ldap.conf
104   Configuration variables to select what server and what base DN to use.
105   it() /etc/userdir-ldap/templates/welcome-message-<GID>
106   The welcoming message to send to the user. Each primary group has its
107   own message
108   it() ~/.debian-lists_passwd
109   Authentication password for the list server
110 )
111
112 manpageauthor()
113 userdir-ldap was written by Jason Gunthorpe <jgg@debian.org>.