From Qmailwiki

Contents 1 Introduction 2 Sample Protocol Sessions 2.1 Successful Authentication Session 2.2 Successful Authentication Session with compact option 2.3 Add New Email Account Session 2.4 Add New Account failure due to permissions 2.5 List Available Commands - help 3 Sample PHP code 4 Command Reference 4.1 login user@domain password 4.2 add_user user@domain password gecos<crlf> 4.3 del_user user@domain<crlf> 4.4 mod_user user@domain (option lines)<crlf>.<crlf> 4.5 user_info user_domain<crlf> 4.6 add_alias_domain domain alias<crlf> 4.7 add_domain domain postmaster@password<crlf> 4.8 del_domain domain<crlf> 4.9 dom_info domain<crlf> 4.10 mk_dir /full/path/to/dir<crlf> 4.11 rm_dir /full/path/to/dir<crlf> 4.12 list_dir /full/path/to/dir<crlf> 4.13 rm_file /full/path/to/file<crlf> 4.14 rename_file old_file new_file [overwrite 0/1 default 1]<crlf>.<crlf> 4.15 write_file /full/path (data lines)<crlf>.<crlf> 4.16 read_file /full/path<crlf> 4.17 stat_file /full/path<crlf> 4.18 list_domains [page per_page]<crlf> 4.19 find_domain domain [per-page]<crlf> 4.20 domain_count <crlf> 4.21 list_users domain<crlf> 4.22 list_alias domain<crlf> 4.23 list_lists domain<crlf> 4.24 get_ip_map domain<crlf> 4.25 add_ip_map domain ip<crlf> 4.26 del_ip_map domain<crlf> 4.27 show_ip_map domain<crlf> 4.28 get_limits domain<crlf> 4.29 set_limits domain (option lines)<crlf>.<crlf> 4.30 del_limits domain<crlf> 4.31 get_lastauth user@domain<crlf> 4.32 add_list domain listname (command line options)<crlf> 4.33 del_list domain listname<crlf> 4.34 mod_list domain listname (command line options)<crlf> 4.35 list_autoresponder domain<crlf> 4.36 add_autoresponder domain listname (command line options)<crlf> 4.37 del_autoresponder domain listname (command line options)<crlf> 4.38 quit 4.39 help help 5 Feature Requests 6 Bugs

[edit] Introduction

The vpopmail daemon is a daemon that runs under tcpserver to provide access to qmail/vpopmail information with the correct permissions. It provides a POP3 like protocol for authenticated vpopmail users.

There is a PHP object to access the daemon available at pmailadmin.sourceforge.net. Currently it is only available from CVS. You want the package vpopmaild-php and possibly vpopmail_util which provides some higher level functions.

[edit] Sample Protocol Sessions

For those of you who want to run the tests below add the example.com domain to your machine.

/home/vpopmail/bin/vadddomain example.com test

As an example, here is a protocol session between a client and the vpopmail daemon

vpopmaild: +OK
client: help
vpopmaild: +OK+
vpopmaild: login user@domain password [compact]
vpopmaild: help help
vpopmaild: quit quit
vpopmaild: .
client:    login postmaster@example.com foob
vpopmaild: -ERR 0105 invalid login

This example shows an invalid authentication attempt. Notice the + and - characters sent by vpopmaild. The + means everything is still okay. The - means there is an error. Also note that vpopmaild closes the connection after the third invalid login attempt. Limited help is available before login.

[edit] Successful Authentication Session

Here is a successful authentication session

vpopmaild: +OK
client:    login postmaster@example.com test
vpopmaild: +OK+
vpopmaild: vpopmail_dir /home/vpopmail
vpopmaild: domain_dir /home/vpopmail/domains/example.com
vpopmaild: uid 89
vpopmaild: gid 89
vpopmaild: name postmaster
vpopmaild: comment Postmaster
vpopmaild: quota NOQUOTA
vpopmaild: user_dir /home/vpopmail/domains/example.com/postmaster
vpopmaild: encrypted_password $1$QsZ1iWoV$NQtzSbUGVAw7.SrSST4Bs0
vpopmaild: clear_text_password test
vpopmaild: no_password_change 0
vpopmaild: no_pop 0
vpopmaild: no_webmail 0
vpopmaild: no_imap 0
vpopmaild: bounce_mail 0
vpopmaild: no_relay 0
vpopmaild: no_dialup 0
vpopmaild: user_flag_0 0
vpopmaild: user_flag_1 0
vpopmaild: user_flag_2 0
vpopmaild: user_flag_3 0
vpopmaild: no_smtp 0
vpopmaild: domain_admin_privileges 1
vpopmaild: override_domain_limits 0
vpopmaild: no_spamassassin 0
vpopmaild: delete_spam 0
vpopmaild: system_admin_privileges 0
vpopmaild: .

Notice after the client sends a valid user@domain password combination, vpopmaild responds with +OK+. The trailing + means there are 2 or more lines of results coming. +OK means just one line of status information is coming back. The end of a multiline +OK+ response always ends with a single . on a line by itself, similar to POP3 and SMTP protocols.

[edit] Successful Authentication Session with compact option

Here is a successful authentication session

vpopmaild: +OK
client:    login postmaster@example.com test compact
vpopmaild: +OK+
vpopmaild: vpopmail_dir /home/vpopmail
vpopmaild: domain_dir /home/vpopmail/domains/example.com
vpopmaild: uid 89
vpopmaild: gid 89
vpopmaild: name postmaster
vpopmaild: comment Postmaster
vpopmaild: quota NOQUOTA
vpopmaild: user_dir /home/vpopmail/domains/example.com/postmaster
vpopmaild: encrypted_password $1$QsZ1iWoV$NQtzSbUGVAw7.SrSST4Bs0
vpopmaild: clear_text_password test
vpopmaild: gidflags: 69632
vpopmaild: .

Notice instead of decoding each bit of the gidflags value the decimal equivalent is sent. This can substantially reduce the amount of time needed to transfer a large number of users or domains when issuing the various list commands. Once you login with compact mode enabled all bitmap values will be transmitted as a number, and the receiving program will have to decode the value.

[edit] Add New Email Account Session

This example show how a domain or system admin can add a new email account. This example assumes we already authenticated with the vpopmail daemon.

client   : add_user user1@example.com test User1
vpopmaild: +OK

Since the postmaster@example.com has domain administration privileges (domain_admin_privileges 1), we can successfully run the command.

[edit] Add New Account failure due to permissions

In this example, we authenticate as the user we just created and attempt to add a new user.

 vpopmaild: +OK
 client   : login user1@example.com test
 vpopmaild: +OK+
 vpopmaild: vpopmail_dir /home/vpopmail
 vpopmaild: domain_dir /home/vpopmail/domains/example.com
 vpopmaild: uid 89
 vpopmaild: gid 89
 vpopmaild: name user1
 vpopmaild: comment User1
 vpopmaild: quota NOQUOTA
 vpopmaild: user_dir /home/vpopmail/domains/example.com/user1
 vpopmaild: encrypted_password $1$Ss503s37$6yvf2/TmUtD.x6mWDzE920
 vpopmaild: clear_text_password test
 vpopmaild: no_password_change 0
 vpopmaild: no_pop 0
 vpopmaild: no_webmail 0
 vpopmaild: no_imap 0
 vpopmaild: bounce_mail 0
 vpopmaild: no_relay 0
 vpopmaild: no_dialup 0
 vpopmaild: user_flag_0 0
 vpopmaild: user_flag_1 0
 vpopmaild: user_flag_2 0
 vpopmaild: user_flag_3 0
 vpopmaild: no_smtp 0
 vpopmaild: domain_admin_privileges 0
 vpopmaild: override_domain_limits 0
 vpopmaild: no_spamassassin 0
 vpopmaild: delete_spam 0
 vpopmaild: system_admin_privileges 0
 vpopmaild: .

 client   : add_user user2@example.com test
 vpopmaild: -ERR XXX not authorized

Notice in this case that domain_admin_privileges and system_admin_privileges are 0. Which means this user has only the default user permissions. So they can only modify their own information. So they are not allowed to create new users.

[edit] List Available Commands - help

You can get a list of available commands and the parameters with the "help" function

client   : help
vpopmaild: +OK+
vpopmaild: login user@domain password
vpopmaild: add_user user@domain password gecos<crlf>
vpopmaild: del_user user@domain<crlf>
vpopmaild: mod_user user@domain (option lines)<crlf>.<crlf>
vpopmaild: user_info user_domain<crlf>
vpopmaild: add_alias_domain domain alias<crlf>
vpopmaild: add_domain domain postmaster@password<crlf>
vpopmaild: del_domain domain<crlf>
vpopmaild: dom_info domain<crlf>
vpopmaild: mk_dir /full/path/to/dir<crlf>
vpopmaild: rm_dir /full/path/to/dir<crlf>
vpopmaild: list_dir /full/path/to/dir<crlf>
vpopmaild: rm_file /full/path/to/file<crlf>
vpopmaild: rename_file old_file new_file [overwrite 0/1 default 1]<crlf>.<crlf>
vpopmaild: write_file /full/path (data lines)<crlf>.<crlf>
vpopmaild: read_file /full/path<crlf>
vpopmaild: stat_file /full/path<crlf>
vpopmaild: list_domains [page per_page]<crlf>
vpopmaild: find_domain domain [per-page]<crlf>
vpopmaild: domain_count <crlf>
vpopmaild: list_users domain<crlf>
vpopmaild: list_alias domain<crlf>
vpopmaild: list_lists domain<crlf>
vpopmaild: get_ip_map domain<crlf>
vpopmaild: add_ip_map domain ip<crlf>
vpopmaild: del_ip_map domain<crlf>
vpopmaild: show_ip_map domain<crlf>
vpopmaild: get_limits domain<crlf>
vpopmaild: set_limits domain (option lines)<crlf>.<crlf>
vpopmaild: del_limits domain<crlf>
vpopmaild: get_lastauth user@domain<crlf>
vpopmaild: add_list domain listname (command line options)<crlf>
vpopmaild: del_list domain listname<crlf>
vpopmaild: mod_list domain listname (command line options)<crlf>
vpopmaild: list_autoresponder domain<crlf>
vpopmaild: add_autoresponder domain listname (command line options)<crlf>
vpopmaild: del_autoresponder domain listname (command line options)<crlf>
vpopmaild: quit quit
vpopmaild: help help
vpopmaild: .

[edit] Sample PHP code

first create a socket

 $vd_sock = @socket_create(AF_INET, SOCK_STREAM, SOL_TCP);
 if (!($vd_sock)) {
    printf("vpopmaild_connect: couldnt initialize socket");
    return 0;
 }

then connect to the vpopmail daemon

 $ret = @socket_connect($vd_sock, "127.0.0.1", "89");
 if (!($ret)) {
    printf("vpopmaild_connect: couldnt connect");
    return 0;
 }

send the login command

 $str = "login user@domain pass\n\r";
 $ret = @socket_write($vd_sock, $str);
 if ($ret == FALSE) {
    @socket_close($vd_sock);
    printf("vpopmaild_write: socket_write failed");
    return 0;
 }

read the result

 $str = @socket_read($vd_sock, 1024, PHP_NORMAL_READ);
 if ($str == FALSE) {
    @socket_close($vd_sock);
    printf"vpopmaild_read: socket_read failed: " . socket_last_error());
    return 0;
 }

process the result

 if (ereg("^-ERR.*", $rs)) {
    if ($rs == "-ERR XXX invalid login") {
      printf("vpopmaild_connect: invalid login");
    }
    @socket_close($vd_sock);
    return 0;
 }

send an add user command

 $str = "add_user user@domain pass name\n\r";
 $ret = @socket_write($vd_sock, $str);
 if ($ret == FALSE) {
    @socket_close($vd_sock);
    printf("vpopmaild_write: socket_write failed");
    return 0;
 }

read the result

 $str = @socket_read($vd_sock, 1024, PHP_NORMAL_READ);
 if ($str == FALSE) {
    @socket_close($vd_sock);
    printf"vpopmaild_read: socket_read failed: " . socket_last_error());
    return 0;
 }

process the result

 /* error */
 if (ereg("^-ERR.*", $rs)) {
   if ($rs == "-ERR XXX not authorized")
     printf("v_adduser: not authorized");
   else if ($rs == "-ERR XXX Domain does not exist")
     printf("v_adduser: domain '" . $MODULE_ARGV[2] . "' does not exist");
   else if ($rs == "-ERR XXX Username exists")
     printf("v_adduser: user already exists");
   else
     printf("v_adduser: unexpected response from vpopmaild: '" . $rs . "'");
   return 0;
 }
 /* success */

[edit] Command Reference

• The daemon enforces a 60 second timeout, after which it disconnects you with

+OK 
-ERR XXX read timeout

[edit] login user@domain password

• Successful Login Output
  

root@mail: ~ # telnet localhost 89
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.domain.com.
Escape character is '^]'.
+OK 
login postmaster@domain.com password
+OK+
vpopmail_dir /usr/local/vpopmail
domain_dir /usr/local/vpopmail/domains/domain.com
uid 89
gid 89
name postmaster
comment Postmaster
quota NOQUOTA
user_dir /usr/local/vpopmail/domains/domain.com/postmaster
encrypted_password $1$PFB3FLWs$b6UFFXpEp3GvfX47G0eOi1
clear_text_password password
no_password_change 0
no_pop 0
no_webmail 0
no_imap 0
bounce_mail 0
no_relay 0
no_dialup 0
user_flag_0 0
user_flag_1 0
user_flag_2 0
user_flag_3 0
no_smtp 0
domain_admin_privileges 1
override_domain_limits 0
no_spamassassin 0
delete_spam 0
system_admin_privileges 0
.

• Successful Connection delimiter = +OK
• Successful Login delimiter = +OK+
• Command Termination delimiter is a single . on a line by itself.
  
  

---

• Login Failure Output

root@mail: ~ # telnet localhost 89
Trying ::1...
telnet: connect to address ::1: Connection refused
Trying 127.0.0.1...
Connected to localhost.domain.com.
Escape character is '^]'.
+OK 
login postmaster@domain.com password1
-ERR 0105 invalid login
Connection closed by foreign host.

• Error code = 0105

---

• Relevant MySQL Table Entry (Database = vpopmail - Table = vpopmail)

mysql> select * from vpopmail where pw_domain like 'domain.com';
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
| pw_name    | pw_domain  | pw_passwd                          | pw_uid | pw_gid | pw_gecos   | pw_dir                                            | pw_shell | pw_clear_passwd |
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
| postmaster | domain.com | $1$PFB3FLWs$b6UFFXpEp3GvfX47G0eOi1 |      0 |      0 | Postmaster | /usr/local/vpopmail/domains/domain.com/postmaster | NOQUOTA  | password        | 
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
1 row in set (0.00 sec)

[edit] add_user user@domain password gecos<crlf>

add_user user@domain.com mypass My Full Name
+OK 

• gecos field is REQUIRED, and can have multiple words.

add_user user2@domain.com mypass
-ERR 0306 gecos required

• See ?
• Command Error Code = 0306

• Relevant MySQL Table Entry (Database = vpopmail - Table = vpopmail)

mysql> select * from vpopmail where pw_domain like 'domain.com';
+------------+------------+------------------------------------+--------+--------+-----------------+---------------------------------------------------+----------+-----------------+
| pw_name    | pw_domain  | pw_passwd                          | pw_uid | pw_gid | pw_gecos        | pw_dir                                            | pw_shell | pw_clear_passwd |     
+------------+------------+------------------------------------+--------+--------+-----------------+---------------------------------------------------+----------+-----------------+
| postmaster | domain.com | $1$PFB3FLWs$b6UFFXpEp3GvfX47G0eOi1 |      0 |      0 | Postmaster      | /usr/local/vpopmail/domains/domain.com/postmaster | NOQUOTA  | password        | 
| user       | domain.com | $1$mjZ7yius$0U2XmD6iNJIt.Jl7hpSkD/ |      0 |      0 | My Full Name    | /usr/local/vpopmail/domains/domain.com/user       | NOQUOTA  | mypass          | 
+------------+------------+------------------------------------+--------+--------+-----------------+---------------------------------------------------+----------+-----------------+
2 rows in set (0.00 sec)

[edit] del_user user@domain<crlf>

• Successfully deleting a user.

del_user user@domain.com
+OK 

• Succesful Command delimiter = +OK
• Here's what an error looks like:

del_user
-ERR XXX email_address required

• Error code = XXX

• Relevant MySQL Table Entry (Database = vpopmail - Table = vpopmail)

mysql> select * from vpopmail where pw_domain like 'domain.com';
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
| pw_name    | pw_domain  | pw_passwd                          | pw_uid | pw_gid | pw_gecos   | pw_dir                                            | pw_shell | pw_clear_passwd |
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
| postmaster | domain.com | $1$PFB3FLWs$b6UFFXpEp3GvfX47G0eOi1 |      0 |      0 | Postmaster | /usr/local/vpopmail/domains/domain.com/postmaster | NOQUOTA  | password        | 
+------------+------------+------------------------------------+--------+--------+------------+---------------------------------------------------+----------+-----------------+
1 row in set (0.00 sec)

• Lovely!

[edit] mod_user user@domain (option lines)<crlf>.<crlf>

• You can adjust as many user attributes as you want before terminating your command with a single period on a line by itself.
• Below is an example of disabling POP3 mailbox access for user@domain.com:

user_info user@domain.com
<snip>
no_pop 0
<snip>
.

mod_user user@domain.com
no_pop 1
.
+OK 

user_info user@domain.com
<snip>
no_pop 1
<snip>
.

• Note: if you change the attribute "clear_text_password", the associated MD5 password hash is updated automatically.

mod_user flag bitmap:

--------------------------------------------------------------------------------------------------------------------------------------------
gid   | switch | vmoduser description                                       | vuserinfo limits field description
--------------------------------------------------------------------------------------------------------------------------------------------
0     |   -x   | clear all flags (reset gid to default of 0)                | limits: No user limits set.
1     |   -d   | don't allow user to change password                        | limits: password can not be changed by user
2     |   -p   | disable POP access                                         | limits: pop access closed
4     |   -w   | disable webmail [IMAP from localhost*] access              | limits: webmail access closed
8     |   -i   | disable non-webmail IMAP access                            | limits: imap access closed
16    |   -b   | bounce all mail                                            | limits: mail will be bounced back to sender
32    |   -r   | disable roaming user/pop-before-smtp                       | limits: user not allowed to relay mail
64    |   -u   | set no dialup flag (not used)                              | limits: no dialup flag has been set
128   |   -0   | set V_USER0 flag (either true or false)                    | limits: user flag 0 is set
256   |   -1   | set V_USER1 flag (either true or false)                    | limits: user flag 1 is set
512   |   -2   | set V_USER2 flag (either true or false)                    | limits: user flag 2 is set
1024  |   -3   | set V_USER3 flag (either true or false)                    | limits: user flag 3 is set
2048  |   -s   | disable SMTP AUTH access                                   | limits: smtp access is closed
4096  |   -a   | grant qmailadmin administrator privileges                  | limits: has qmailadmin administrator access
8192  |   -o   | user is not subject to domain limits                       | limits: user is not subject to domain limits
16384 |   -f   | disable spamassassin                                       | limits: spamassassin processing disabled
32768 |   -F   | delete spam                                                | limits: delete spam
65536 |   -S   | grant system administrator privileges - access all domains | limits: has system administrator access
131072|   -E   | grant expert privileges - edit .qmail files                | limits: has ability to edit .qmail files in a text box
      |        |                                                            |         (this is not supported by any programs yet)
--------------------------------------------------------------------------------------------------------------------------------------------

• Examples:
  • if you set -d (gid 1) and -p (gid 2), then the gid would be 3.
  • if you set -d (gid 1) and -s (gid 2048), then the gid would be 2049.

[edit] user_info user_domain<crlf>

• Dump all info associated with user@domain.com

user_info user@domain.com
+OK+
name user
comment myname
quota NOQUOTA
user_dir /usr/local/vpopmail/domains/domain.com/user
encrypted_password $1$iZWaMmOq$p/Ct58T0Zug8TD4U3O/f6/
clear_text_password mypass
no_password_change 0
no_pop 0
no_webmail 0
no_imap 0
bounce_mail 0
no_relay 0
no_dialup 0
user_flag_0 0
user_flag_1 0
user_flag_2 0
user_flag_3 0
no_smtp 0
domain_admin_privileges 0
override_domain_limits 0
no_spamassassin 0
delete_spam 0
system_admin_privileges 0
.

• Command Termination delimeter is a single period on a line by itself.

[edit] add_alias_domain domain alias<crlf>

• Successful alias domain addition:

add_alias_domain domain.com alias.com
+OK 

• Failure alias domain addition (due to account not having "system_admin_privileges 1" access.

add_alias_domain domain.com alias.com
-ERR XXX not authorized

[edit] add_domain domain postmaster@password<crlf>

See Bugs

• Successful Domain Addition

add_domain domain1.com domain1pass
+OK 

• Success Command delimiter = +OK

• If the domain already exists:

add_domain domain1.com domain1pass
-ERR XXX Domain already exists

• Failure Command delimeter -ERR XXX

[edit] del_domain domain<crlf>

• Successful domain deletion

del_domain domain1.com
+OK 

• Command Termination delimeter = +OK

• Example of non-existant domain removal attempt:

del_domain domain2.com
-ERR XXX Domain does not exist

[edit] dom_info domain<crlf>

• Dump information about a particular domain:

dom_info domain.com
+OK+
domain domain.com
path /usr/local/vpopmail/domains/domain.com
uid 89
gid 89
alias alias.com
.

• Command Termination delimiter is a single period on a line by itself.

[edit] mk_dir /full/path/to/dir<crlf>

• I guess you could code something here to create /etc/skel functionality for webmail spam folders or whatever...

mk_dir /root/test
-ERR XXX unauthorized directory
mk_dir /domains/test
-ERR XXX unauthorized directory
mk_dir /domains/domain.com/test
-ERR XXX unauthorized directory
mk_dir /usr/local/vpopmail/domains/test
+OK 

• Command Termination delimiter = +OK

root@mail: ~ # ls -al ~vpopmail/domains
total 10
drwx------  5 vpopmail  vchkpw  512 Nov  9 19:36 .
drwxr-xr-x  8 vpopmail  vchkpw  512 Nov  6 00:01 ..
drwx------  4 vpopmail  vchkpw  512 Nov  9 02:40 domain.com
drwx------  2 vpopmail  vchkpw  512 Nov  9 19:10 newdomain.com
drwx------  2 vpopmail  vchkpw  512 Nov  9 19:36 test
root@mail: ~ # 

[edit] rm_dir /full/path/to/dir<crlf>

• Not sure what you might use this for...

rm_dir /usr/local/vpopmail/domains/test
+OK 
rm_dir /tmp/test
-ERR XXX unauthorized directory

[edit] list_dir /full/path/to/dir<crlf>

list_dir ~vpopmail/domains
-ERR XXX invaild directory
list_dir /usr/local/vpopmail/domains/
+OK+
domain.com dir
newdomain.com dir
.

• Command Termination delimiter is a single period on a line by itself.
• Also note you must send the fully qualified path. Tilde $HOME shortcut, and symlink targets don't work.
  

i.e. ln -s /usr/local/vpopmail/domains /domains and then send "list_dir /domains" won't work.

[edit] rm_file /full/path/to/file<crlf>

• Can't remove unless you know the filename, so perhaps a function that incorporates list_dir and rm_file.

touch ~vpopmail/domains/testfile ; chown vpopmail:vchkpw ~vpopmail/domains/testfile

rm_file /usr/local/vpopmail/domains/testfile
+OK 

[edit] rename_file old_file new_file [overwrite 0/1 default 1]<crlf>.<crlf>

See Bugs

[edit] write_file /full/path (data lines)<crlf>.<crlf>

• Useful for submitting a Welcome message to new users.
• Useful for creating a "send test message" function for NOC employees, to save them time from sending mail from their client (albeit that does not test DNS).

write_file /usr/local/vpopmail/domains/domain.com/postmaster/Maildir/new/welcome.msg
Date: 9 Nov 2006 00:24:06 -0000
From: postmaster@domain.com
To: newuser@domain.com
Subject: Welcome to your new email account!

Welcome to your new email account.
Reception of this message verifies that your email client settings are correct.

If you have any further questions:

Email: support@domain.com
URL:   http://www.domain.com/support
Phone: 000-000-0000 from 9am-5pm.

Thanks for your business!
.
+OK 

• Command Termination delimiter = +OK

[edit] read_file /full/path<crlf>

• Perhaps a function that incorporates list_dir and read_file.
• Note, it follows normal UNIX filesystem permission rules, in my case default creates files as 0644 and read_file happily cats them to you.
• Need a function to parse the output into the GUI, perhaps with syntax highlight.

root@mail: /usr/local/vpopmail/domains # echo "my data" > testfile

root@mail: /usr/local/vpopmail/domains # ls -al
total 10
drwx------  4 vpopmail  vchkpw  512 Nov  9 20:09 .
drwxr-xr-x  8 vpopmail  vchkpw  512 Nov  6 00:01 ..
drwx------  4 vpopmail  vchkpw  512 Nov  9 02:40 domain.com
drwx------  2 vpopmail  vchkpw  512 Nov  9 19:10 newdomain.com
-rw-r--r--  1 root      vchkpw    8 Nov  9 20:08 testfile
root@mail: /usr/local/vpopmail/domains # 


read_file /usr/local/vpopmail/domains/testfile
+OK+
my data
.

• Command Termination delimiter is a single period on a line by itself.

[edit] stat_file /full/path<crlf>

See Bugs

[edit] list_domains [page per_page]<crlf>

• Output is:

<domain name><space><domain_name>
<domain name><space><alias_domain_name>

list_domains
+OK+
domain.com alias.com
domain.com domain.com
newdomain.com newdomain.com
.

• Command Termination delimiter is a single period on a line by itself.

[edit] find_domain domain [per-page]<crlf>

• Not really sure how useful this is...
• Someone tell me what the page # is, I guess I don't have enough domains added to this test box right now to see it in action.
• alias.com is an alias domain I added earlier, and it's page # is zero, but the real domain that corresponds to it is page1...

find_domain alias.com
+OK+
page 0
.
find_domain domain.com
+OK+
page 1
.
find_domain fakedomain.com
+OK+
page 0
.

[edit] domain_count <crlf>

• Simple and useful.

domain_count 
+OK+
count 3
.

• Command Termination delimiter is a single period on a line by itself.

[edit] list_users domain<crlf>

• Useful for a domain summary page.
• Notice that there is no delimiter between accounts, but your function can loop through each input line until it sees "^name", and you know a new account begins.

list_users domain.com
+OK+
name postmaster
comment Postmaster
quota NOQUOTA
user_dir /usr/local/vpopmail/domains/domain.com/postmaster
encrypted_password $1$PFB3FLWs$b6UFFXpEp3GvfX47G0eOi1
clear_text_password password
no_password_change 0
no_pop 0
no_webmail 0
no_imap 0
bounce_mail 0
no_relay 0
no_dialup 0
user_flag_0 0
user_flag_1 0
user_flag_2 0
user_flag_3 0
no_smtp 0
domain_admin_privileges 0
override_domain_limits 0
no_spamassassin 0
delete_spam 0
system_admin_privileges 1
name user
comment myNEWname
quota NOQUOTA
user_dir /usr/local/vpopmail/domains/domain.com/user
encrypted_password $1$iZWaMmOq$p/Ct58T0Zug8TD4U3O/f6/
clear_text_password mypass
no_password_change 0
no_pop 0
no_webmail 0
no_imap 0
bounce_mail 0
no_relay 0
no_dialup 0
user_flag_0 0
user_flag_1 0
user_flag_2 0
user_flag_3 0
no_smtp 0
domain_admin_privileges 0
override_domain_limits 0
no_spamassassin 0
delete_spam 0
system_admin_privileges 0
.

• Command Termination delimiter is a single period on a line by itself.

[edit] list_alias domain<crlf>

See Bugs

[edit] list_lists domain<crlf>

[edit] get_ip_map domain<crlf>

[edit] add_ip_map domain ip<crlf>

[edit] del_ip_map domain<crlf>

[edit] show_ip_map domain<crlf>

[edit] get_limits domain<crlf>

• Dump domain-wide limits.

get_limits domain.com
+OK+
max_popaccounts -1
max_aliases -1
max_forwards -1
max_autoresponders -1
max_mailinglists -1
disk_quota 0
max_msgcount 0
default_quota 0
default_maxmsgcount 0
disable_pop 0
disable_imap 0
disable_dialup 0
disable_password_changing 0
disable_webmail 0
disable_external_relay 0
disable_smtp 0
disable_spamassassin 0
delete_spam 0
perm_account 0
perm_alias 0
perm_forward 0
perm_autoresponder 0
perm_maillist 0
perm_quota 0
perm_defaultquota 0
perm_defaultquota 0
.

• Command Termination delimiter is a single period on a line by itself.

vlimits.default reference

[edit] set_limits domain (option lines)<crlf>.<crlf>

See Bugs

• Adjust the various possible limits of a domain as listed above.
• A function to adjust these settings system-wide is a nice-to-have I think (i.e. quota).

get_limits domain.com
+OK+
<snip>
disable_pop 0
<snip>
.

set_limits domain.com
disable_pop 1
.
+OK

get_limits domain.com
<snip>
disable_pop 1
<snip>
.

[edit] del_limits domain<crlf>

• Reset domain_limits to default settings, as set in vlimits.default.

del_limits domain.com
+OK 

[edit] get_lastauth user@domain<crlf>

See Bugs

• Get the timestamp/IP address that $USER last logged in at/from, respectively.
• The following example is output before a user ever logs in (i.e. immediately after creation):
• Timestamp is unixtime.

get_lastauth user@domain.com
+OK+
time 1163058021
ip 0.0.0.0

• The following example is output after I telnet'd to localhost on my test box and authenicated via POP3:

get_lastauth user@domain.com
+OK+
time 1163131133
ip 127.0.0.1

• Notice IP and timestamp have changed.

[edit] add_list domain listname (command line options)<crlf>

[edit] del_list domain listname<crlf>

[edit] mod_list domain listname (command line options)<crlf>

[edit] list_autoresponder domain<crlf>

[edit] add_autoresponder domain listname (command line options)<crlf>

[edit] del_autoresponder domain listname (command line options)<crlf>

[edit] quit

login postmaster@domain.com password
+OK+
<snip>
.
quit
+OK 
Connection closed by foreign host.

• Command Termination delimiter = +OK

[edit] help help

[edit] Feature Requests

• add_alias alias@domain.com destmailbox@otherdomain.com
• del_alias alias@domain.com
• list_aliases domain.com
• add_forward user@domain.com fwddest@otherdomain.com
• del_forward user@domain.com fwddest@otherdomain.com
• list_forwards user@domain.com
• get_lastauth deprecated, replaced by including it's functionality in user_info.
• stat_dir command that computes disk usage for a user's maildir (or add a switch to user_info that adds quota usage to output, but _not_ to output of list_domain)

[edit] Bugs

Found on vpopmail v5.4.17 + jms1 onchange patch 7

---

1) Here shows an add_domain command failure exit code, however the domain directory is created anyway. The new domain does not show up in MySQL vpopmail.vpopmail.

add_domain newdomain.com 12345678901234567890
-ERR XXX password too long

add_domain newdomain.com 1234567890
-ERR XXX Domain already exists

---

2) Sup wit dis ? Command listed in help output, but not yet implemented.

rename_file testfile testfile2 overwrite 0
-ERR XXX Invalid command 

---

3) Also...Command listed in help output, but not yet implemented.

stat_file /usr/local/vpopmail/domains/testfile
-ERR XXX Invalid command 

---

4) alias weirdness

root@mail: ~ # valias -i user@domain.com alias@domain.com
root@mail: ~ # valias -s domain.com
alias@domain.com -> user@domain.com
root@mail: ~ # 

list_alias domain.com
+OK+
.

---

5) no_pop is not a valid domain_limits command. In domain_limits, disable_pop is the command. However, the server still returns success code as you can see below. Should be -ERR invalid command. I haven't tested all the rest, but there might be other similar cases.

set_limits domain.com
no_pop 1
.
+OK 

---

6) get_lastauth has no command termination exit code. Should be a single period on a line by itself.

get_lastauth user@domain.com
+OK+
time 1163058021
ip 0.0.0.0