unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-3.1)
Page:
Section:
Apropos / Subsearch:
optional field

MAKEUSERDB(8)                                                    MAKEUSERDB(8)



NAME
       make - create /etc/courier/userdb

SYNOPSIS
       makeuserdb


       pw2userdb


       vchkpw2userdb [ --vpopmailhome=dir ] [ --todir=dir ]


DESCRIPTION
       makeuserdb   creates   /etc/courier/userdb.dat  from  the  contents  of
       /etc/courier/userdb.   /etc/courier/userdb's  contents  are   described
       later  in this document.  Maildrop, Courier, and other applications use
       /etc/courier/userdb.dat as  a  substitute/complement  for  your  system
       password  file.   The  usual  purpose for /etc/courier/userdb.dat is to
       specify "virtual" accounts - accounts that do not  have  an  associated
       system login.  Usually (but not necessarily) all virtual accounts share
       the same system userid.  /etc/courier/userdb.dat may also replace  your
       system  password file. Because the system password file is a text file,
       when there's a large number of accounts it will be significantly faster
       to  search  @userdb.dat@, which is a binary database, instead of a flat
       text file that the system password file usually is.

       The makeuserdb command can be  safely  executed  during  normal  system
       activity.

   FORMAT OF /ETC/COURIER/USERDB
       /etc/courier/userdb  is a plain text file that can be created using any
       text editor. Blank lines are ignored. Lines that start with the # char-
       acter  are  comments, and are also ignored.  Other lines define proper-
       ties of a single "account", one line per account.   /etc/courier/userdb
       may  be a directory instead of a plain file.  In that case all files in
       /etc/courier/userdb are essentially concatenated, and are treated as  a
       single file.  Each line takes the following format:

              name<TAB>field=value|field=value...
       name  is the account name.  name MUST contain only lowercase characters
       If Courier is configured to treat lowercase and uppercase account names
       as  identical,  name  is  followed by exactly one tab character, then a
       list of field/value pairs separated by vertical slashes.  field is  the
       name  of  the field, value is the field value.  Fields and values them-
       self cannot contain slashes or control characters.  Fields may be spec-
       ified  in  any  order. Here are all the currently defined fields.  Note
       that  not  every  field  is  used  by  every  application  that   reads
       /etc/courier/userdb.dat.


              uid  -  value  is a (possibly) unique numerical user ID for this
              account.

              gid - value is a (possibly) unique numerical group ID  for  this
              account.

              home - value is the account's home directory.

              shell - value is the account's default login shell.

              systempw  - value is the account's password. See userdbpw(8) for
              details on how to set up this field.

              pop3pw, esmtppw, imappw... - value specifies a separate password
              used  only  for  authenticating access using a specific service,
              such as POP3, IMAP, or anything else. If not  defined,  systempw
              is  always  used.  This  allows  access  to  an  account  to  be
              restricted only to certain services, such as POP3, even if other
              services are also enabled on the server.

              mail  -  value  specifies  the location of the account's Maildir
              mailbox. This is an optional field that is  normally  used  when
              userdb  is used to provide aliases for other mail accounts.  For
              example, one particular multi-domain E-mail  service  configura-
              tion that's used by both Qmail and Courier servers is to deliver
              mail for a mailbox in a  virtual  domain,  such  as  "user@exam-
              ple.com",  to a local mailbox called "example-user".  Instead of
              requiring the E-mail account holder to log in as  "example-user"
              to   download  mail  from  this  account,  a  userdb  entry  for
              "userATexample.com" is set up with mail set to  the  location  of
              example-user's  Maildir  mailbox,  thus hiding the internal mail
              configuration from the E-mail account holder's view.

              quota - value specifies the  maildir  quota  for  the  account's
              Maildir.   This has nothing to do with actual filesystem quotas.
              Courier has a software-based Maildir quota enforcement mechanism
              which   requires   additional   setup  and  configuration.   See
              maildirquota(7) for additional information.

   /ETC/COURIER/USERDBSHADOW.DAT
       All  fields  whose  name  ends   with   'pw'   will   NOT   copied   to
       /etc/courier/userdb.dat.    These    fields    will    be   copied   to
       /etc/courier/userdbshadow.dat.  makeuserdb creates /etc/courier/userdb-
       shadow.dat   without  any  group  and  world  permissions.   Note  that
       makeuserdb reports an error if /etc/courier/userdb  has  any  group  or
       world permissions.

   CONVERTING /ETC/PASSWD AND VPOPMAIL TO /ETC/COURIER/USERDB FORMAT
       pw2userdb  reads the /etc/passwd and /etc/shadow files and converts all
       entries to the /etc/courier/userdb format, printing the result on stan-
       dard   output.    The   output   of   pw2userdb   can   be   saved   as
       /etc/courier/userdb (or as some file  in  this  subdirectory).   Linear
       searches  of  /etc/passwd  can be very slow when you have tens of thou-
       sands  of  accounts.    Programs   like   maildrop   always   look   in
       /etc/courier/userdb  first.   By  saving  the  system  password file in
       /etc/courier/userdb it is possible to significantly reduce  the  amount
       of time it takes to look up this information.

       After  saving the output of pw2userdb, you must still run makeuserdb to
       create /etc/courier/userdb.dat.

       vchkpw2userdb converts a  vpopmail-style  directory  hierarchy  to  the
       /etc/courier/userdb format.  This is an external virtual domain manage-
       ment package that's often used with Qmail servers.

       Generally, an account named 'vpopmail' is reserved  for  this  purpose.
       In  that  account  the  file  users/vpasswd  has  the  same  layout  as
       /etc/passwd, and performs a similar function, except that all userid in
       users/vpasswd  have  the same userid.  Additionally, the domains subdi-
       rectory stores virtual accounts for  multiple  domains.   For  example,
       domains/example.com/vpasswd  has  the  passwd file for the domain exam-
       ple.com.  Some systems also have a  soft  link,  domains/default,  that
       points to a domain that's considered a "default" domain.

       The  vchkpw2userdb  reads all this information, and tries to convert it
       into the /etc/courier/userdb format.  The --vpopmailhost option  speci-
       fies  the  top  level directory, if it is not the home directory of the
       vpopmail account.

       The vchkpw2userdb script prints the  results  on  standard  output.  If
       specified, the --todir option tries to convert all vpasswd files one at
       a time, saving each one individually in dir. For example:


              mkdir /etc/courier/userdb
              vchkpw2userdb --todir=/etc/courier/userdb/vpopmail
              makeuserdb

       It is still necessary to run  makeuserdb,  of  course,  to  create  the
       binary database file /etc/courier/userdb.dat

       NOTE:   You  are still required to create the /etc/courier/userdb entry
       which maps system userids back to accounts, "uid=<TAB>name", if  that's
       applicable. vchkpw2userdb will not do it for you.

       NOTE:   makeuserdb  may  complain  about  duplicate  entries,  if  your
       "default" entries in users/vpasswd or domains/default/vpasswd  are  the
       same  as  anything  in  any other /etc/courier/userdb file.  It is also
       likely that you'll end up with duplicate,  but  distinct,  entries  for
       every  account  in  the  default  domain.  For example, if your default
       domain is example.com, you'll end up with duplicate  entries  -  you'll
       have entries for both user and user@example.com.

       If you intend to maintain the master set of accounts using vchkpw/vpop-
       mail, in order to avoid cleaning this up every time, you might want  to
       consider doing the following: run vchkpw2userdb once, using the --todir
       option.  Then, go into the resulting directory, and replace one of  the
       redundant  files with a soft link to /dev/null.  This allows you to run
       vchkpw2userdb without having to go in and  cleaning  up  again,  after-
       wards.

FILES
       /etc/courier/userdb
       /etc/courier/userdb.dat
       /etc/courier/userdbshadow.dat
       /etc/courier/userdb.tmp - temporary file
       /etc/courier/userdbshadow.tmp - temporary file

BUGS
       makeuserdb  is a Perl script, and uses Perl's portable locking.  Perl's
       documentation notes that certain combinations of  locking  options  may
       not work with some networks.

SEE ALSO
       userdb(8), maildrop(8), courier(8), maildirquota(7).



Double Precision, Inc.          27 August 2004                   MAKEUSERDB(8)