====== Managing users ======

Joyent Shared Accelerators do not have a concept of pure mailboxes (i.e. mailboxes and nothing else). Instead, there are //users// which are always implicit mailboxes (with IMAP, POP3 and SMTP logins), and may take on other optional roles as well:

  * SFTP login
  * MySQL login
  * Subversion login
  * WebDAV login

A user may at all times receive mail at ''USER@SERVER.joyent.us'' (where USER is the user's login name, and SERVER is the respective hosting server's name). In addition, each user's mailbox may be associated with one or more mail addresses under one or more of domains hosted on your shared hosting account. Mail will be delivered to the user's mailbox by default, unless changed by mail options (see below).

<note important>A user's login name for SFTP, IMAP, POP3 and SMTP will be assembled from the name part that you enter into the //Email address// field (see below) and the first part of the domain name of the virtual server. So, if the user's name is ''joe'' and the domain name is ''example.com'', Joe's login will be ''joe-example''. You can edit the suffix taken from the domain name //before you create any users// via: **Edit Virtual Server -> Configurable settings -> Mailbox name prefix**</note>

<note important>Make sure you have enabled mail for your domain, otherwise your user will not be able to send or receive email. You can enable mail from Virtualmin by doing the following:

  - Sign in to Virtualmin (see [[Logins]]).
  - Select a virtual server from the drop-down in the left-hand navigation (your main virtual server should be already selected when you first login to Virtualmin).
  - Click **Edit Virtual Server** in the left-hand navigation. 
  - Click **Enabled features**
  - Select **Mail for domain enabled?** and click **Save Virtual Server**
</note>

===== Adding a single user =====

  - Sign in to Virtualmin (see [[Logins]]).
  - Select a virtual server from the drop-down in the left-hand navigation (your main virtual server should be already selected when you first login to Virtualmin). The virtual server you select here will be the one that you'll be adding a user to.
  - Click **Edit Mail and FTP Users** in the left-hand navigation. 
  - Click **Add a user to this server.**
  - For //Email address//, enter whatever you want to appear as first part of the user's email address). The entire value (e.g. ''joe@mysite.com'') will be the user's primary email address.
  - For //Real name//, enter a name for your user (e.g. first name and surname).
  - The //Password// field will already be populated with password for your user. We recommend using the password that Virtualmin has created as they are fairly secure and you should also make a note of this password in case you need it (you can retrieve the password on the same page later on though).
  - If you'd like to set a quota for this user, click **Quota and home directory settings**, and enter a value in bytes, kb, MB, or GB.
<note warning>The quota displayed is only updated every 30 minutes, If you changed the setting for the user it may now show **unlimited**.  Check back in 30 minutes and you will see that the actual value you set will be shown.</note>
The **Email settings** and **Mail forwarding settings** sections control how mail is handled for the user:

  * The **Primary email address enabled?** option control whether the user should receive mail at his primary email address (the //Email address// line on the top of the page).
  * The **Additional email addresses** option lists all other addresses (aliases) that the user should be able to receive mail at; these can be under the domain of the current virtual server (alias without @domain is ok), or other domains that are set up on your account, one per line.
  * The **Send new account email to** field can carry another email address that the user/mailbox set up email should be sent to. It will contain mail and SFTP login information for the user.
  * **Deliver to this user normally** - do not forget to enable this option if you use any other of the mail forwarding or handling options, otherwise mail would **not** be stored in the mailbox at all.
  * **Forward to other address?** - enable to have mail forwarded to mail addresses entered in the input box below.
  * **Send automatic reply?** - enable to have the response entered below automatically sent back to senders of any mail you receive at this address.
  * For //Minimum time between autoreplies//, select the option next to **minutes** and enter a reasonable delay in the text field, such as ''10'' minutes. This will prevent an automatic response from being created for someone who has sent more than one message in the given time period (in this case, 10 minutes), which helps avoid creating endless loops.
  * For //Automatic reply start date// and //Automatic reply end date//, you may set dates when an automatic response should enable (start) and disable (end) itself automatically, e.g. on the days of your vacation.

<note tip>If you click on **Advanced mode** on the top of //Mail forwarding settings// section on the page, a different interface will show - one that will let you change the mail configuration the same way as above and more, ending up with a potentially long list of actions (e.g. have mail delivered to several mailboxes). Click the **Alias destinations** link there to get a description of all the options available.</note>

There are other privileges you can grant to the user under **Other user permissions**:

  * **FTP login enabled** is actually SFTP access on Joyent Shared Accelerators. The user will be allowed to login over SFTP and upload/download files (to his home directory only by default).
  * **DAV login enabled** creates a WebDAV login for the user (this is the only case where a longform username is used - the user's primary email address, e.g. ''joe@mysite.com'' instead of ''joe-mysite''). This option only appears if you have the //DAV logins enabled// feature enabled for the virtual server.
  * **Allow access to repositories** creates a Subversion login for the user (a shortform username is used here - just the first part of the primary email address, e.g. ''joe'' instead of ''joe-mysite''). All Subversion repositories that the user needs access to have to be explicitly selected from the list. This option only appears if you have the //DAV logins enabled// feature enabled for the virtual server.
  * **Allow access to databases** creates a MySQL login for the user (a shortform username is used here - just the first part of the primary email address, e.g. ''joe'' instead of ''joe-mysite''). All MySQL databases that the user needs access to have to be explicitly selected from the list. This option only appears if you have the //DAV logins enabled// feature enabled for the virtual server.

When you are done configuring the user, click **Create** to create your new user.

<note warning>There is a hard coded limitation in MySQL that allows usernames to be up to 16 characters long only. If the resulting username were longer than 16 characters (e.g. because of a domain suffix being added by Virtualmin), it would be truncated to 16 characters. This may present a conflict in cases where two usernames would only differ on the 17th character or further, and Virtualmin will not be able to create the other one. The solution is name the user as short as possible in such case.</note>

===== Adding multiple users in batches =====

If you have to add many users to your account you can do so easily by following these steps rather than creating each user one at a time.

  - Sign in to Virtualmin (see [[Logins]]).
  - Select a virtual server from the drop-down in the left-hand navigation (your main virtual server should be already selected when you first login to Virtualmin). The virtual server you select here will be the one that you'll be adding a user to.
  - Click **Edit Mail and FTP Users** in the left-hand navigation. 
  - Click **Batch create users**.
  - Create a batch file that lists all the users that you want to create and their permissions. The batch file is just a plain text file with that must list one user per line and each line must be in the following format: <code>username:realname:password:ftp-flag:email-flag:quota:[extras]:[forwards]:[databases]</code>
    * For more information on the file format and the batch alias creation process, click **Help..** at the top-left of the page.
  - Select **Uploaded file** and click **Choose File** to upload your batch file or select **Batch lines below..** to enter the same information in the provided text field.
  - Finally, click **Create** to create your users.

===== Editing and deleting a user =====

You can edit a user on the same screen as when creating it, just by clicking its name in the list. To delete, either click Delete on the particular user page, or select one or more from the list by ticking the boxes, and click **Delete selected users**.

Furthermore, you can batch edit users by selecting them from the list and clicking **Modify selected users**. The various options on the following page will be applied to all selected users.

===== Error messages =====

''**Failed to save mailbox** : The additional email domain 'your-domain-name.tdl' is not managed by Virtualmin'' (when creating a user mailbox)\\
You forgot to enable Mail for the domain. You can do this at:\\
**Edit Virtual Server -> Enabled Features -> Mail for domain enabled?**