vadddomain.1

NAME

vadddomain - Create a virtual domain

SYNOPSYS

vadddomain [ options ] virtual_domain [ postmaster_password ]

DESCRIPTION

vadddomain adds a new virtual domain. It creates the necessary qmail control files and a .qmail-default containing delivery instructions. vadddomain has setuid bit set and can be run by the root user, by the indimail user or if the user has the indimail group as a supplementary group. It also adds the RFC821 required postmaster account. Carries out the following steps to create the domain.

Create the domains directory (/var/indimail/domains/virtual_domain)

[step]
Create the .qmail-default file in the domains directory.

[step]
Add the domain to qmail assign file.

[step]
Add the domain to chkrcptdomains ('-R' option).

[step]
Add the domain to rcpthosts, virtualdomains (and etrnhosts for domains with ETRN/AUTOTURN support).

[step]
Create table indimail and indibak if used for the first time.

[step]
Sends SIGHUP to qmail-send.

[step]
Add entry to table dbinfo and mcdfile for a clustered domain ('-D' option).

[step]
Create the postmaster account for a non-clustered domain. For a clustered domain, the postmaster account is created on the first host on which the domain is created. Post adding the postmaster user, vadddomain adds abuse and mailer-daemon, as aliases to the postmaster account.

POST HANDLE

If the environment variable POST_HANDLE is set, vadddomain executes the program defined by the POST_HANDLE environment variable with the same with uid/gid of the indimail user in /etc/passwd. If POST_HANDLE is not defined, the program /usr/libexec/indimail/vadddomain will be executed with root privileges. The POST_HANDLE program/script is passed the same command line arguments as passed to vadddomain. The POST_HANDLE program is executed as the last step after all earlier steps have been successful.

OPTIONS

virtual_domain is mandatory. Rest are optional. If postmaster_password is not given, vadddomain will prompt for the password.

-v
make vaddomain be verbose

-B base_path
sets the BASE PATH for user's home directory for users created on this domain. This overrides the environment variable BASE_PATH and the default base path /home/mail. You can use this option to assign specific directories/filesystems to users added to a domain. The base path is maintained in the file /var/indimail/virtual_domain/.base_path

-l users_per_level
By default, vadduser uses an adaptive directory structure based on a table dir-control which is automatically managed by vadduser(1), vdeluser(1) and vreorg(8). The basic idea is to break up the user Maildir directories across multiple directories and sub-directories so that there are never more than 100 user directories in a single directory. Use this option to change the default compile time value of 100 users per directory.

-q quota_in_bytes
sets the quota for postmaster account

-b
bounces all mail that doesn't match a user, default

-E
email_address (forwards all non matching user to this address)

-u user
sets the uid/gid based on a user in /etc/passwd. Default is user indimail

-d dir
Defaults to /var/indimail. Sets the directory as dir/domains/virtual_domains for the domain virtual_domain in the file /etc/indimail/users/assign. See dot-qmail(5). All configuration files for the domain are placed in the directory dir/domains/virtual_domain.

-i uid
sets the uid to use for this domain

-g gid
sets the gid to use for this domain

-R
Sets RECIPIENT Check for this domain. qmail-smtpd(8) verifies all users in the RCPT TO command.

-O
optimize adding, for bulk adds set this for all except the last one

-f
sets the domain to use vfilter mechanism for mail filtering

-t
Enable ETRN/ATRN support for the domain. This requires you to authenticate and use vatrn(1) to configure access.

-T ip_address
Enable ETRN, AUTOTURN Support from the IP ip_address

-e
Set the encrypted Password field. This options disables the internal encryption routine which encrypts the password provided on the command line. This option sets the encrypted password field exactly as given on the command line without any encryption. It expects you to give a standard encrypted password or you can use this to set plaintext/salted password for CRAM authentication.

-r len
Generates Random Password of length len. Need not give password on command line.

-h hash
Specify hash which is one of DES, MD5, SHA-256, SHA-512. Here ID is the id in /etc/shadow. See incrypt(1).

HASH ID Description
DES - DES encryption (shouldn't be used)
MD5 1 MD5 encryption (shouldn't be used)
SHA-256 5 SHA256 encryption
SHA-512 6 SHA512 encryption

You can also set the environment variable PASSWORD_HASH to set the encryption method. The -h argument overrides the environment variable PASSWORD_HASH. The value of PASSWORD_HASH environment variable identifies the encryption method used and this then determines how the rest of the password string is interpreted. The following values of PASSWORD_HASH are supported:

PASSWORD_HASH Value	Description
0	DES encryption (shouldn't be used)
1	MD5 encryption (shouldn't be used)
2	SHA256 encryption
3	SHA512 encryption

-m scram
Sets the CRAM or SCRAM method for encryption. This will set SCRAM password in the scram field in indimail/indibak tables. For CRAM method, it will set clear text password when -C option is specified.

CRAM/SCRAM method	Description
-----------------	-----------
CRAM	Sets clear text password suitable for any
	CRAM method (CRAM-MD5, CRAM-SHA1, ...)
SCRAM-SHA-1	SHA1 encryption suitable for SCRAM-SHA-1.
SCRAM-SHA-256	SHA256 encryption suitable for SCRAM-SHA-256.

-C
Sets up authentication suitable for CRAM-MD5, CRAM-SHA1, CRAM-SHA224, CRAM-SHA256, CRAM-SHA384, CRAM-SHA512, CRAM-RIPEMD and DIGEST-MD5 methods. This works by storing the clear text credentials in the database. if the -m option is selected, this will additionally store a hex-encoded salted password for SCRAM methods, which can be used instead of clear text passwords by clients (for SCRAM authentication).

-S salt
Specify a base64 encoded salt to be used when generating SCRAM password. If not specified, this will be generated using libsodium/gsasl. Here base64 implies characters [0-9], [a-z], [A-Z] and the two characters [./].

-I iteration
Specify the iteration count to be used when generating SCRAM password. The default is 4096.

-D database
Adds domain information to dbinfo table. This implies use of the -H, -U, -P, -L options additionally

-H SqlServer
IP address or hostname of MySQL(1) server

-U User
User for accessing MySQL Database

-P Password
Password for the user to access the MySQL database

**-p **MySQL Port
Port to connect to for accessing the database

-c
Adds a clustered domain. This implies use of the -H, -U, -P, -L options

virtual_domain
Name of the new virtual domain. new_domain can contain alphanumeric characters besides '-' and '.' . However the first and the last character cannot be '-'.

[postmaster password]
The password for the RFC required postmaster account. If the password is not supplied on the command line then vadddomain will prompt for the password twice.

RETURN VALUE

0 if all steps were successful, non-zero otherwise. If any of the steps fail, a diagnostic message is printed.

NOTE

The virtual domain becomes active after running this program. No additional files need to be modified. A new directory is added under /var/indimail/domains to house all the .qmail files, configuration files for the new virtual domain.

[step]
vadddomain has the setuid bit set and runs as root.

[step]
Domain names can contain alphanumeric characters besides '-' and '.' . However the first and the last character cannot be '-'.

[step]
The postmaster account is created as an active account.

[step]
For a clustered domain, the postmaster id is added only for the first domain created as part of a cluster.

SEE ALSO

vaddaliasdomain(1), vmoddomain(1), vadduser(1), vdeldomain(1), valias(1), vdeluser(1), vdominfo(1), dbinfo(8), qmail-smtpd(8), vdelivermail(8), vatrn(1), dot-qmail(5),