.\" to process use the following command
.\" groff -man -Tascii manpagename.1
.TH CPU-LDAP 8 "17 February 2003"
.SH NAME
cpu \- a user administration tool for LDAP backends
.SH SYNOPSIS
.B cpu
user{add,del,mod} [options] login

.B cpu
group{add,del,mod} [options] group

.B cpu
cat

.SH DESCRIPTION
The ldap module for cpu provides a means for administering groups and users
being stored on an LDAP backend. Complete compatibility with the GNU/Linux
versions of the shadow utils has tried to be maintained in terms of command
line options. This module also supports several options that traditional user
utilities do not such as; selecting which hash to use for the user, generating
random or linear uid's and gid's and pulling information for a user from
existing password and shadow files.

.SH LDAP OPTIONS
The LDAP options are options that are used specifically for the LDAP server.
They may be combined with any of the cpu functions.
.IP "-2, --2\fR"
Use LDAPv2 instead of LDAPv3
.IP "-a \fIfile\fR, --addfile=\fIfile\fR"
If a filename is given, it will be parsed and any additional ldap attributes
specified in this file will be added along with the user or group. This file
should not contain any attributes that CPU requires or that you have already
specified in the configuration file. If you do this the modification/addition
will fail or create multivalued attributes. The format of the file should be:
.LP
.nf
.ft tt
        <attrdesc>: <attrvalue>
        <attrdesc>: <attrvalue>
        <attrdesc>:: <base64-encoded-value>
        ...
.ft
.fi
.IP "-A \fIcn\fR, --cn=\fIcn\fR"
This options specifies for a user what the dn should look like. If you specify
\fB-A\fR foo for some user, their dn will look like foo=username,... This can be
specified in the configuration file with USER_CN_STRING
.IP "-B \fIbase\fR, --groupbase=\fIbase\fR"
This is the base to search for groups in. This is required for useradd and for
any group functions. This should be a fully qualified base such as
ou=groups,o=company,c=us. This corresponds to the GROUP_BASE configuration
option.
.IP "-D \fIbind_dn\fR, --binddn=\fIbind_dn\fR"
The bind_dn should be a DN with adequate credentials for the operation that
you are requesting. This corresponds to the BIND_DN configuration file option.
.IP "-F\fI[file]\fR, --passfile\fI[=file]\fR"
If an argument is provided, that file should be of a Unix style password
format. If no argument is provided, the configuration file variable
PASSWORD_FILE will be used. Please be sure that the switch (\fB-F\fR or
\fB--passfile\fR) has no trailing whitespace, it should be immediately followed
by the argument. The information associated with the user will be used for
populating their LDAP entry (uid, gid, gecos, home directory, shell).
.IP "-H \fIhash\fR, --hash=\fIhash\fR"
Hash should be one of sha1, md5, ssha1, smd5, crypt, md5crypt or clear. This
corresponds to the HASH configuration file variable. Select the hash that is
being used at your site.
.IP "-N \fIhostname\fR, --hostname=\fIhostname\fR"
Hostname should be the hostname that is running the LDAP service. This may be
an IP address or hostname. This corresponds to the LDAP_HOST variable in the
configuration file.
.IP "-o, --nonposix\fR"
Violate POSIX naming standards and allow characters in user and group names
not in the character set [A-Za-z0-9._-]. This is useful for things like adding
Samba machine accounts.
.IP "-P \fIport\fR, --port=\fIport\fR"
Port should be the port that the LDAP server is listening on. This corresponds
to the LDAP_PORT option in the configuration file.
.IP "-R \fIlength\fR, --random=\fIrandom\fR"
\fIlength\fR should be the length that you would like a randomly generated
password to be. This password will be displayed to the user.
.IP "-S\fI[file]\fR, --shadfile\fI[=file]\fR"
If an argument is provided, that file should be of a Unix style shadow
format. If no argument is provided, the configuration file variable
SHADOW_FILE will be used. Please be sure that the switch (\fB-S\fR or
\fB--shadfile\fR) has no trailing whitespace, it should be immediately followed
by the argument. The information associated with the user will be used for
populating their LDAP entry (password, sp_lstchg, sp_min, sp_max, sp_warn,
sp_inact, sp_expire).
.IP "-t \fItimeout\fR, --timeout=\fItimeout\fR"
This value is used to specify how long (in seconds) before LDAP operations
should time out. The corresponding configuration file is TIMEOUT.
.IP "-U \fIbase\fR, --userbase=\fIbase\fR"
This is the base to search for users in. This is required for any user
functions. This should be a fully qualified base such as
ou=users,o=company,c=us. This corresponds to the USER_BASE configuration option.
.IP "-w\fI[pass]\fR, --bindpass\fI[=pass]\fR"
If an argument is provided, that value will be used for the bind password. If
no argument is provided, the user will be prompted for a password. This option
can be omitted by specifying the password in the configuration file with the
option BIND_PASS. If a value is specified at the command line, the switch
should have no whitespace following it.
.IP "-x, --tls"
Try to starttls before talking with the ldap server.

.IP "The following options can be used for populating LDAP attributes."

.IP "-f \fIname\fR, --firstname=\fIname\fR"
Name is used in possible combination with lastname in order to have a more
complete CN. This value is also used for the givenName (gn) attribute. This
value is not required by RFC2307.
.IP "-E \fIname\fR, --lastname=\fIname\fR"
Name is used in possible combination with firstname in order to have a more
complete CN. This value is also used for the surname (sn) attribute. This
value is not required by RFC2307.
.IP "-e \fIaddress\fR, --email=\fIaddress\fR"
The value address is used to populate the mail attribute. This attribute is
not required by RFC2307 for posixAccount but many people's LDAP schemas do
require it. inetOrgPerson is one object that contains it.

.IP "The following options are not LDAP specific."

.IP "-h, --help"
Display help.
.IP "-v, --verbose"
Turn the verbose level up.
.IP "-V, --version"
Display the version of the module.

.SH cpu cat
The \fBcat\fR command will cause any users and groups stored in the LDAP
directory to be displayed in a Unix style format. \fBcat\fR requires no
options.

.SH cpu useradd [options] login
The \fBuseradd\fR function is used to add new users to an LDAP directory. The
options are similar to those used by traditional GNU/Linux user administration
utilities.
.IP "-c \fIcomment\fR, --gecos=\fIcomment\fR"
The value specified is used to populate the gecos attribute. You can specify a
default value in the configuration file using the GECOS variable. This is not
required by RFC2307. This can also be populated using the -F option (see
above).
.IP "-d \fIhome_dir\fR, --directory=\fIhome_dir\fR"
The new user will be created using \fIhome_dir\fR as the value for the user's
login directory. The default is to append \fIlogin\fR to HOME_DIRECTORY (from
the configuration file) and use that as the login directory name. This is
required by RFC2307.
.IP "-g \fIinitial_group\fR, --gid=\fIinitial_group\fR"
The group id or name of the user's initial login group. The group should exist
but does not have to. CPU will search the LDAP directory and warn you if that
group does not exist. If the group does exist, the users gidNumber will be set
to the gidNumber of that group. This is required by RFC2307. If unspecified CPU
will search for the next unused GID. This behavior can be adjusted by
MAX_GIDNUMBER, MIN_GIDNUMBER, ID_MAX_PASSES, and RANDOM in the configuration
file.
.IP "-G \fIgroup,[...]\fR --sgroup=\fIgroup,[...]\fR"
A list of supplementary groups which the user is also a member of. Each group
is separated from the next by a comma, with no intervening whitespace. CPU
will search the directory for these groups, and if found, add the user to
those groups. The default is for the user to belong only to the initial group.
.IP "-k\fI[skeleton_dir]\fR --skel\fI[=skeleton_dir]\fR"
This option is only useful is specified along with the \fB-m\fR option.
If both are specified, the contents of \fIskeleton_dir\fR will be copied to the
users new home directory. If \fIskeleton_dir\fR is specified it should have no
whitespace between the command line switch. If \fIskeleton_dir\fR is not
specified, the value of SKEL_DIR as specified in the configuration file will
be used.
.IP "-m, --makehome"
The user's home directory will be created if it does not exist. The files
contained in \fIskeleton_dir\fR will be copied to the home directory if the
\fB-k\fR option is used. The \fB-k\fR option is only valid in conjunction with
the \fB-m\fR options. The default is to not create the directory and to not
copy any files.
.IP "-p\fI[passwd]\fR --password\fI[=password]\fR"
The encrypted or unencrypted password. If no argument is given, the user is
prompted to enter a password. If CPU was compiled with libcrack, the password
will be checked for weakness. If the password is encrypted, hash should be the
value of the hash type that was used. If not specified at the command line or
found in the shadow file (if \fB-S\fR was used) * is used which should lock the
account.
.IP "-s \fIshell\fR, --shell=\fIshell\fR"
The name of the user's login shell. If not specified at the command line one
can specify it with the DEFAULT_SHELL configuration file option. This is not
required by RFC2307.
.IP "-u \fIuid\fR, --uid=\fIuid\fR"
The numerical value of the user's ID. This value must be unique, the value
must be non-negative. If unspecified CPU will search for an unused UID. This
behavior can be adjusted by MAX_UIDNUMBER, MIN_UIDNUMBER, ID_MAX_PASSES, and
RANDOM in the configuration file.
.IP "-X \fIscript\fR, --exec=\fIscript\fR"
After the user has successfully been added to the directory, execute this
script. The script is passed the login name. If this option is not supplied,
the configuration file will be checked for ADD_SCRIPT.

.SH cpu usermod [options] login
All options that apply to \fBuseradd\fR also apply to \fBusermod\fR except for
\fB-k\fR.
.IP "-l \fIlogin_name\fR, --newusername=\fIlogin_name\fR"
The name of the user will be changed from \fIlogin\fR to \fIlogin_name\fR. The
LDAP attributes cn and uid are changed to \fIlogin_name\fR, the users rdn is
also modified. If specified in conjunction with the \fB-m\fR switch, the users
old home directory will be copied the the appropriate new location (see
\fB-d\fR  switch for behavior).
.IP "-L, --lock\fR"
Lock the given user account
.IP "-U, --unlock\fR"
Unlock the given user account

.SH cpu userdel [options] login
The \fBuserdel\fR command modifies the LDAP directory, deleting all entries that
refer to \fIlogin\fR. The named user must exist. The options which apply to the
\fBuserdel\fR command are:
.IP "-r, --removehome"
Files in the user's home directory will be removed along with the home
directory itself. The users mail spool is not deleted. Files located in other
file systems will have to be searched for and deleted manually.
.IP "-X \fIscript\fR, --exec=\fIscript\fR"
After the user has successfully been removed from the directory, execute this
script. The script is passed the login name. If this option is not supplied,
the configuration file will be checked for DEL_SCRIPT.

.SH cpu groupadd [options] group
The \fBgroupadd\fR command creates a new group account using the values
specified on the command line and the default values from the configuration
file. The new group will be entered into the LDAP directory as needed. The
options which apply to the \fBgroupadd\fR command are
.IP "-g \fIgid\fR, --gid=\fIgid\fR"
The numerical value of the group's ID. This value should be unique. The value
must be non-negative. A new gid can be generated by not specifying this
option. This generation can be modified by changing the configuration file.

.SH cpu groupmod [options] group
The \fBgroupmod\fR command modifies the \fIgroup\fR specified at the command
line. The options which apply to the \fBgroupmod\fR command are
.IP "-g \fIgid\fR, --gid=\fIgid\fR"
The numerical value of the group's ID. This value should be unique. The value
must be non-negative.
.IP "-n \fIgroup_name\fR, --newgroupname=\fIgroup_name\fR"
The name of the group will be changed from \fIgroup\fR to \fIgroup_name\fR.
The cn and rdn will also be modified.

.SH cpu groupdel [options] group
The \fBgroupdel\fR command removes the \fIgroup\fR specified at the command
line from the LDAP directory.

.SH SEE ALSO
.B cpu.conf(5) cpu(8)
.SH AUTHORS
Blake Matheny <bmatheny@purdue.edu>

The current version of this software is always available at
.I http://cpu.sourceforge.net
.SH BUGS

To report a bug or problem, please e-mail:

cpu-users@lists.sourceforge.net

.SH TODO
See TODO file that accompanied software. Please e-mail us with any additional suggestions.