The Tellpop Command Line Utility

(this page is still under construction !)

Tellpop provides a simple universal command line utility for controlling and monitoring the DPOP system. Of special note is the 'reload' command, which makes DPOP reload its configuration file. It is often used after manually editing the config file, so that you do not have to restart DPOP for the changes made to take effect.

It is used as follows:

Tellpop  command  parameters

Examples:

tellpop  status                 				 to check status of running DPOP system
tellpop  key 1234-567a-4321-1111 	to load new registration key 

Tellpop needs access to the same configuration file that DPOP is using. The default location for the configuration file, the default filename being dmail.conf, is system dependent

  • for most Unix variations
    	/etc/
  • for Windows 95 and NT
    	C:\winnt\system32\

In normal use Tellpop will find the configuration file automatically. When Tellpop is being used to control DPOP running on another machine the configuration file to be used is specified as follows, (example sends the status command).

tellpop -i another/path/fred.conf   status

NB: Tellpop will try to connect to the server domain, as set in your dmail.conf file with the dpop_host setting. If you have not set one then it will do a gethostname( ) type call to find the server's domain name.

Access to Tellpop manager commands can be limited in several ways:

  • Firstly a configuration file wildcard list limits the from address for Tellpop manager commands. The limits can be based on ip-name or ip-number wildcard lists, see the manager_ip_address setting.
  • Secondly a manager command password is used. This is normally generated on installation and stored in encrypted form in tellpass.dat, see the manager_password setting.
  • If Tellpop is being used remotely the manager password command is not normally sent across the network .

Tellpop command summary:

Note: Underscore characters in commands are optional so list_users or listusers can be used.

add_user Add a username bill to DPOP’s INTERNAL list of users.
abort Fred Abort current connection from user Fred
abort_chan n Abort current connection on channel n
bins Fred Shows status of bin files belonging to Fred
bulletin Create a new bulletin message for all users.
config List current values of all DPOP's configuration settings
del_user remove username from DPOP's internal list of users
drop Fred Converts all messages in Fred's bin files back into a drop file and deletes bin files
drop_all Converts all users bin files back into drop files. This may take some time.
erase_user Remove username from DPOP's internal list of users, and delete all associated files.
die Kills DPOP suddenly and horribly, ( i.e. emulation of behavior of some other packages :-)
disable Fred Temporarily prevent user Fred from connecting to DPOP
enable Fred Allow disabled user Fred to connect again.
expire Expire messages greater than a certain size, and older than a certain date.
flush_stats Flush per user stats records to disk. To allow stats command to use current file.
key xyz Loads a new registration key xyz
list_current List currently connected users
list_disabled List currently disabled users
list_diff_drops Lists all drop files that have changed since new hashing was adopted.
list_users Provides a list of all users of DPOP who have read mail or been added via add_user command.
list_users_addresses Lists addresses of all users in a specified domain and places that list in the specified filename.
list_users_drops Lists the drop files of all usernames containing a particular string.
log_level Set the logging level to control what information is stored in the DPOP log file.
offline Temporarily disables user connections to DPOP (i.e. stops people reading their mail)
online Enables connections to DPOP. (Lets people start reading their mail again)
password Saves a new manager password for DPOP. It is stored encrypted in tellpass.dat
prof_init Initialize counts and averages of profile information
profile Prints a summary of profile information for DPOP, Gives calls, elapsed and used CPU for key parts of DPOP
register Presents questions to allow DPOP to be registered. A register.txt file is created for emailing to Netwin.
reload Reloads the configuration file to ensure any changed settings are put into effect.
sleep n Puts DPOP to sleep for n seconds.
status Provides feedback on the current status of the DPOP server. The information returned includes:
shutdown n Shuts down the DPOP system when current connections = zero or in n seconds
stats Produces per user connection statistics from .stats files for accounting etc.
statistics Produces DSMTP usage statistics from the log files.
testfiles Determines the maximum number of files which can still be opened - can take several minutes on a slow system
 	      

Main Tellpop Commands

add_user bill

Add a username bill to DPOP’s INTERNAL list of users. The main purpose for this internal list is for license key limits.

NB: This does not control access to DPOP. Access can be limited by a variety of different means. See the valid_users setting for information on controlling access.

NB: This does not add email accounts to your POP server. To add users to your email system, see the adding users section.


bulletin

Creates a bulletin message for all users. The message is written to a file nnn.txt in the bulletins directory. nnn is the next free bulletin number. The message will be delivered to each user when they check their email.

As of DMail 2.9, Tellpop will prompt you to enter a list of domains to which the bulletin will be delivered. If you simply press enter, without typing any domain names, the bulletin will be delivered to all domains. For example, 'tellpop bulletin' will prompt you like this:

Press <cr>, or type a list of domains:

If you wanted to deliver the bulletin to the domains domain_one, fred, and foo, you would type:

Press <cr>, or type a list of domains:
domain_one fred foo


del_user

Del_user fred removes username fred from DPOP's internal user list. Note; if a user is deleted they can still connect to DPOP as the username will automatically be added on connection, however information such as the highest bulletin number that user has read will have been forgotten. User access can be restricted by use of controls on valid username wildcards, valid from ip name wildcards, valid Unix usernames and by disabling individual users.


erase_user bill

erase_user deletes user 'bill' from DPOPs internal user list, as does del_user. However, erase_user also deletes all files and directories associated with the user. Finally, if external authentication is used, erase_user removes the user from the authentication database.


password

The command tellpop password xyz will set a new manager password for DPOP. An encrypted form of this password is stored in the tellpass.dat file and is used automatically by DPOP, Tellpop and DMAdmin. The password is normally encrypted with a random token whenever it is sent across a network but can be used unencrypted if DPOP is being controlled manually using Telnet.


status

Provides feedback on the current status of the DPOP server. The information returned includes:

  • DPOP version number.
  • The time DPOP was started and current up time.
  • The number of current connections, the peak number of connections and the maximum number of connections allowed
  • The current license class and user limit

stats *jul*

Provides per user connections statistics for all users from matching statistics files. DPOP produces one .stats file per day with names dpopmmmdd.stats so the example above would process all stats files for July. This can be used to provide accounting or charging information. For each user it lists:

  • Username
  • IP number for last connection from this user
  • Total and average connection time in seconds and average connection time for checks when no mail was available.
  • Total number of connections and average time between connections
  • Total messages transferred and total quantity in bytes

A summary at the end gives grand totals for all users.

The output is written to the file, dpop.sum


flush_stats

If you want to use the tellpop stats command to lookup statistics for the current day you should first issue the flush_stats command to make sure current records are written to file. Otherwise the last few connections will not be included in the summaries.


register

Presents questions to allow DPOP to be registered. A register.txt file is created for emailing to Netwin.

Payment details are encrypted for safe transfer to NetWin Ltd..


key xyz

Loads a new registration key xyz


offline

Puts DPOP in offline mode in which new connections from users are disabled. Generally used prior to shutdown to ensure no current sessions are aborted. Can also be used to temporarily disable connections without stopping DPOP. Naturally DPOP will still accept manager command connections.


online

Puts DPOP back in online mode which enables normal client connections.


shutdown

Shuts down the DPOP system.


 

statistics

Produces DSMTP usage statistics from the log files.

NB: Requires that the DSMTP setting, oneline_stats is set to true in dmail.conf to create the dmDDMM.log files used. This command was added in version 2.9a

For each domain or user the number of messages sent, received, transfered or failed are displayed plus the respective total number of bytes associated with these messages. For each value the peak and average values are given and the time band in which the peak value occured.

Usage:
statistics [-U|D][-R|-S][-Dn][-Pn][-An][-sortby] timeframe
-D Calculates statistics by domain name
-U Calculates statistics by user name
-S Calculates statistics by sender or senders domain
-R Calculates statistics by receiver or receivers domain
-Dn Specifies the top n number of domains or users to display
-dall will display all users or domains
-d0 will display none(requires significantly less system resources)
-Pn Set size of the peak window(n) in seconds
-An Set size of dominator(n) used to calculate averages (in seconds)
-sortby Indicates statistic by which domains or users are to be compared.
Options: recv|sent|delv|fail|brecv|bsent|bdelv|bfail
timeframe  Period over which analysis will be preformed.
Options: [MM/dd] [hh.mm.ss] to [MM/dd] [hh.mm.ss]
hour the last hour
day the last day
week the last week
month the last month
so_far_today statistics since midnight
Examples:  tellpop statistics 1/15 to 1/20
Analyse period from the start of the 15th Jan to the end of 19th Jan
tellpop statistics -d100 -u hour
Displays the 100 users who logged the most sends in the last hour tellpop
statistics -p3600 -a1800 month
Analyse last month giving the peak hour(3600s) of usage for each given statistic. All averages will be quoted per half hour(1800s).
Defaults: statistics -d -s -d10 -p600 -a600 -sent so_far_today


reload

Reloads the configuration file to ensure any changed settings are put into effect.

NOTE : If you have modified a dmail.conf setting which is relevant to both DPOP and DSMTP, it is necessary to reload both servers individually with their reload configuration file commands, e.g. tellsmtp reload and tellpop reload. DMAdmin will do this automatically, but note that you can send the reload command from the command list in DMAdmin whenever you wish.

If you have an exceptionally large dmail.conf file this process of reloading could take as long as 30 seconds. You should not need to do reloads of the configuration file for DPOP very often so this sort of down time should not be too much of a problem. If it is then please contact support-dmail@netwinsite.com to discuss your situation.


list_diff_drops

Lists all drop files that have changed since new hashing was adopted.

Example:

tellpop list_users_drops

list_users

Provides a list of all users of DPOP who have read mail or been added via add_user command.


list_users_addresses

Usage:
list_users_addresses domain filename

Lists addresses of all users in a specified domain 'domain' and places that list in the specified filename 'filename'.

Example:

tellpop list_users_addresses mydomain.com output.txt

list_users_drops

Usage:
list_users_drops username

Lists the drop files of all usernames containing the search string 'username'

Example:

tellpop list_users_drops bob

log_level

This command will change DPOP's log level during runtime. It will not cause DPOP's config file to be re-written, so next time DPOP is run, it will use the log level setting found there. This command is useful for closely observing a particular transaction DPOP may be about to make.

The available log levels are:

error: the only information written will be errors, warnings, socket read and write information and minimal progress information.
info: as well as the error information, this setting gives much more progress information, as well as file open and close calls.
debug: as well as the info information, this setting gives a whole lot of internal status information, function calls...all sorts of stuff. However, it may slow down operation slightly and can produce large log files, so use sparingly.

If DPOP is crashing or doing very peculiar things, the most useful things to NetWin support are the config file and the log file.

Info is the default setting, and the usual setting for operating in. For more information see the Logging of information and error messages section.


expire

Usage:
expire <size bytes> <age days>

This command removes messages of specified size and age(days) from all users maildrops. It also appends a message to the users maildrop, informing the user of the expiry of messages.

If the file expire.tpl is found in the DPOP path, that template will be used to generate the expiry notice. %%x will be replaced by the number of expired messages, %%s with the e-mail address of the administrator, and %%m with a summary of the messages. This summary includes subjects, dates, and senders. If no expire.tpl is found, the message will be automatically generated in English.

A sample expire.tpl is listed below:

You have had messages removed from your inbox because they are too old. A total of %%x messages were removed. If you wish to contact someone regarding this, please e-mail %%s.

A summary of expired messages follows:
%%m

You can also set DPOP to run the expire process automatically, see expire_min.


Additional Tellpop commands for testing

drop_all

(Normally only used before reverting to another POP3 server and when 'read but undeleted' messages are left)

Turns all bins back into drop files for all users. Connection to DPOP while this command is executing is disabled.

Note: This command deletes the bin files for each user after successful conversion.


drop uuu

Turns user uuu's bin files back into a drop file.

Note: This command deletes the bin files if conversion is successful.


bins uuu

(Normally only used by NetWin - documentation only provided for completeness.)

show status of user uuu's bin files in terms of message numbers in each bin

Columns are bin number, file size, used bytes, number of messages in bin, (message numbers)


xtest n

(Normally only used by NetWin - documentation only provided for completeness.)

Add n users with names test0 up to testn


xusers n

(Normally only used by NetWin - documentation only provided for completeness.)

Add n users with random names


testfiles

(Normally only used by NetWin - documentation only provided for completeness.)

Check how many files can be opened concurrently. i.e. check number of free file handles available. Note: on average two handles are needed for each concurrent client connection to DPOP. Concurrent connections on some platforms is limited by the availability of file handles or descriptors.


die

(Dangerous! Normally only used by NetWin - documentation only provided for completeness.)

This command simulates the behavior of certain other much loved software i.e. Causes DPOP to perform an illegal command and die, generally producing a core dump etc.


Back to Top of Summary List