The tellmail command line utilty

tellmail is a command line utility that allows you to perform some administrative tasks with SurgeMail such as adding users and domains to locating a users mailbox. To use tellmail you just need to type tellmail at the shell or command prompt. On Windows you can get to the command prompt by going left clicking on the start button, then program files, then accessories then command prompt.

Example:
C:\>tellmail <command>

All commands are preceeded by typing tellmail

General tellmail commands

help
status
reload
shutdown
queue

Misc. tellmail commands

aspam_retrain
g_relay_allow_ip
suspend
resume
surgeplus
surgehost_update

User commands

path <user@domain>
add_user <user@domain>
delete_user <user@domain>
change_pass <user@domain> <password>
add_user_alias <user> <alias>
delete_user_alias <user> <alias>
add_domain <domain>
delete_domain <domain>
clear_cache [user@domain]

logout <user@domain>
showlocks
expire
expire_status
expire_user <user@domain> <days> <bytes>
set_authfield fieldname file.txt [apply]
find_user <domain> <field_name> <field_value>
user_send_max <user@domain>
add_member <list> <user@domain>
add_rules <file>
rescan_aliases_file
rescan_aliases
list_rcpt <domain> [type]

Quota Commands

quota <user@domain> - Displays the users quota
quota_rebuild <user@domain> - Rebuilds user's quota.
quota_domain <domain> - Displays how much data the domain is currently using.
quota_rebuild_domain <domain> - Rebuilds the quota usage for this domain
quota_set_domain <domain> <size> - Sets the used disk for the specified domain
quota_resetall - Rebuilds all quotas for all users.
quota_set <user@domain> <amount> - sets the users quota.

Migration commands

imap_import <localuser@localdomain> <oldimaphost> <olduser> <oldpass> <delete|keep> <create|nocreate>
pstat_delete user@xyz.com   - Forget about the user so it may re-import the user (dependent on other settings)

License commands

activate<registration> [email address]
deactivate<registration> [email address]

Mirroring

resync_config
resync_fast
resync_nwauth
resync_mkdir

help

Lists the commands you case use and a brief description

status

This gives you a ton of information on the server.

reload

This allows you reload SurgeMail without having to stop and restart it which means it won't interrupt users that are currently online. Great if you have edited surgemail.ini manually and need to activate your changes without disrupting service.

shutdown

This simply tells SurgeMail to shutdown.

queue

This displays the current delivery queue.

path <user@domain>

This allows you to find where a users mailbox is stored on the disk.
example:

C:\>tellmail path stu@catch.netwin.co.nz
C:\surgemail\mbox\catch.netwin.co.nz\xc\lg\stu\

add_user <user@domain>

This allows you to add users easily to SurgeMail.

delete_user <user@domain>

This allows you to delete users from SurgeMail. The deletion process is as follows.

• Deletes user from authentication database
• Removes cache entry
• Decreases registration count
• Decreases user count for domain
• Removes WebMail files (tells webmail to)
• Removes SurgeMail files (users mail)
• Removes aliases
• Removes mailing list subscriptions
• Records them in users_YYYYMMDD.rec

change_pass <user@domain> <pass>

This allows you to change users passwords easily.

add_user_alias <user> <alias>

This allows you to add aliases for users.

delete_user_alias <user> <alias>

This allows you to delete aliases for users.

add_domain <domain>

Adds a domain to SurgeMail. This command makes use of the domain_defaults.txt file specified here.

delete_domain <domain>

Deletes a domain from SurgeMail.

clear_cache [user@domain]

This allows you to clear SurgeMail's authentication cache.
Examples:
tellmail clear_cache - With no argument it will clear the entire cache.
tellmail clear_cache test@localdomain - This will clear only this users cache out
tellmail clear_cache *@domain2.com - Clears the cache for all users at domain2.com

quota <user@domain>

Displays the users current disk usage and their allowed quota.

logout <user@domain>

This will logout a user that is currently connected to on IMAP or POP you can see the current locks by using the tellmail showlocks command

Example:
tellmail logout stu@blah.com

showlocks

This shows the current software locks used by IMAP and POP in SurgeMail. When a user logs into POP or IMAP SurgeMail creates a lock for that user to prevent multiple connections to the same account.

Example:

tellmail showlocks
Lock (catch.netwin.co.nz#stu#_) n=1 f=0 locktype=pop thid=2332

expire

This starts the expire process.

expire_status

Gives the status on the expire process.

expire_user <user@domain> <days> <bytes>

This expires mail in the specified users INBOX, and optionally Trash folders based on the specified criteria, you may specify an age in days and/or a max size in bytes, any message exceeding these will be expired.

find_user <domain> <field name > <field value >

This lets you search for a user or users that match the criteria you have set.

Examples:

To get a list of accounts of a certain status:
tellmail find_user foo.com mailstatus suspended
tellmail find_user foo.com mailstatus payup
tellmail find_user foo.com mailstatus closed

To find out who is using friends
tellmail find_user foo.com friends true

To find users in a certain group
tellmail find_user foo.com mailaccess groupname

set_authfield fieldname file.txt [apply]

This allows you to apply new authent values for one field based on the text file file.txt and fieldname the name of the field to change. Without [apply] flag this is run in preview mode to see what changes to the database would be made and run with [apply] flag to actually make the changes.

where file.txt contains user, new value pairs
user1@domain,value1
user2@domain,value2
...
eg.
user1@mydomain.com,20mb
user2@mydomain.com,30mb

tellmail set_authfield quota newvalues.txt

Processing file (a.a) PREVIEWING CHANGES ...
2 records updated, 0 records did not exist
Original nwauth records stored in pre.txt and updated records in post.txt for review

user_send_max <user@domain>

Reports the number of emails the user has sent in the last 24 hour period.

add_member <list> <user@domain>

Adds the specified email to the specified mailing list.

add_rules <file>

Reads <file>, expects lines formatted:

email:rule

where "email" is the users email address i.e. user@domain.com and "rule" is a user exception rule formatted as expected in the users friend.rul file (create some rules for a user to discover the format, it can be different for different rules and we may change or extend it in future).

This command will not add duplicate rules. This command will only add rules for existing users.

rescan_aliases_files

scan aliases.txt, make domuser.newdat

rescan_aliases

scans domuser.dat, make aliases.txt

list_rcpt

Attempts to list all valid receipt addresses for the server. Can be run as:

tellmail list_rcpt
tellmail list_rcpt domain.name
tellmail list_rcpt domain.name [redirect|lists|alias|blog|misc]

The first gets all receipts.
The next gets only those for the specified domain.
The last gets only those for the specified domain and type.

 

imap_import <localuser@localdomain> <oldimaphost> <olduser> <oldpass> <delete|keep> <create|nocreate>

You can use this command to import users from another serverm this is for importing imap accounts.

1. The username and domain to which the account will be created in surgemail
2. The ip of the server you are migrating the account from
3. The login name of the account on the server you are migrating from.
4. The accounts password on the server you are migrating from
5. Whether you want to delete or keep the messages on the old server
6. Whether you want the account created on the surgemail server, unless you have already created the account this must be create.
   

Example:

old server: 10.0.0.5
old user account: fred
old account password: test
username and domain to create on surgemail: fred@mydomain.com

tellmail fred@mydomain.com 10.0.0.5 fred test keep create

activate <registration> [email address]

This tells SurgeMail to contact the netwinsite.com database and activate your SurgeMail server.

deactivate <registration> [email address]

This tells SurgeMail to deactivate SurgeMail. You should do this if you are going to move SurgeMail to a new machine and then can reactivate on the new machine.

resync_config

This tells SurgeMail to send the config file to the other mirror, you would run this on the machine that has the data you want transferred.

resync_fast

This tells SurgeMail to resend missing files to the slave, this uses a separate thread.
You run this on the machine that has the extra data, if both machines for some reason have data that each other doesn't have it is safe to run this command on both slave and master. This command only sends data the other machine does NOT have, so is considered a very safe command.

resync_nwauth

This resends NWAuth to the other machine, usually run on the master, but if the master had a disk crash and lost NWAuth you would run this on the slave.

resync_config

This resends the surgemail.ini to the other machine, usually run on the master, but if the master had a disk crash and lost it's config you would run this on the slave. This is required every time you enable g_mirror_config, i.e. add it, or go from FALSE to TRUE on either machine.

resync_mkdir

This command creates emtpy folders on the destination server, normally the mirroring only sends messages so doesn't create empty imap folders.

surgeplus

surgeplus is used for doing various SurgePlus commands. use "tellmail surgeplus" for a full list of SurgePlus commands. Some common surgeplus commands are

• tellmail surgeplus status - View current surgeplus status
• tellmail surgeplus rebuild - Delete cached client downloads so they will be rebuilt next time a user tries to download them. Useful if you have customized a SurgePlus image file.
• tellmail surgeplus activate (24-digit-license-key) - Tell SurgeMail to use your new SurgePlus license key.
• tellmail surgeplus download - Download the latest SurgePlus beta and release versions from netwinsite.com to make available to your users.
• tellmail surgeplus reload - Reloads and SurgePlus config files from disk.

aspam_retrain

You should only run this command if you manually change Aspam files.

g_relay_allow_ip <ip>

This allows you to check if an IP is allowed to relay or not.

eg tellmail g_relay_allow_ip 192.168.0.1

suspend

This command will stop SurgeMail from sending any mail out, instead it will just queue it until a tellmail resume command is issued.

resume

This command will make SurgeMail start sending the queue out again after it has been placed in suspend mode by the tellmail suspend command.

surgehost_update

This command will make SurgeMail generate a new surgehost.ini file for use with webmail. It will run through all the domains in surgemail and update surgehost.ini for each domain.