Repository files navigation

RIMS is Ruby IMap Server.This gem provides a complete IMAP server by itself. The IMAPserver can run as a daemon, mailboxes are provided and messagescan be delivered to them.

Add this line to your application's Gemfile:

gem'rims'

And then execute:

$ bundle

Or install it yourself as:

$ gem install rims

Type following to show usage.

$ bundle exec rims helpusage: rims command optionscommands:    help               Show this message.    version            Show software version.    server             Run IMAP server.    daemon             Daemon start/stop/status tool.    post-mail          Post mail to any user.    imap-append        Append message to IMAP mailbox.    mbox-dirty-flag    Show/enable/disable dirty flag of mailbox database.    unique-user-id     Show unique user ID from username.    show-user-mbox     Show the path in which user's mailbox data is stored.command help options:    -h, --help

Something to need for RIMS setup are following:

• IP address of your server to run RIMS.
• At least one pair of username and password.
• Your e-mail client that can use IMAP.

In this tutorial, IP address is192.168.56.101, username isfoo,and password isbar.

Let's try to start RIMS. Type following on your console. And somemessages are shown at console.

$ bundle exec rims server -u foo -w barI, [2015-01-24T21:02:37.030415 #24475]  INFO -- : start server.I, [2015-01-24T21:02:37.035052 #24475]  INFO -- : open socket: 0.0.0.0:1430I, [2015-01-24T21:02:37.036329 #24475]  INFO -- : opened: [AF_INET][1430][0.0.0.0][0.0.0.0]I, [2015-01-24T21:02:37.036569 #24475]  INFO -- : process ID: 24475I, [2015-01-24T21:02:37.037105 #24475]  INFO -- : process privilege user: toki(1000)I, [2015-01-24T21:02:37.037401 #24475]  INFO -- : process privilege group: toki(1000)

Add e-mail account to your e-mail client:

• Username isfoo.
• IMAP server is192.168.56.101. This may be replaced to your serverhostname or IP address.
• IMAP port number is1430. This is default of RIMS.
• IMAP authentication password isbar.

If setup is success, empty mailbox named INBOX is shown at new mailaccount of your e-mail client.

Last, type Ctrl+C on your console to stop server.

Password at command line parameter is insecure because password ispeeped from another user usingps aux. Username and password shouldbe written at configuration file.

RIMS configuration file format is YAML. Type following in file ofconfig.yml and save.

user_list:  -{ user: foo, pass: bar }

And start RIMS with-f config.yml option.

$ bundle exec rims server -f config.ymlI, [2015-01-26T23:20:24.573462 #6106]  INFO -- : start server.I, [2015-01-26T23:20:24.574507 #6106]  INFO -- : open socket: 0.0.0.0:1430I, [2015-01-26T23:20:24.581892 #6106]  INFO -- : opened: [AF_INET][1430][0.0.0.0][0.0.0.0]I, [2015-01-26T23:20:24.582044 #6106]  INFO -- : process ID: 6106I, [2015-01-26T23:20:24.596335 #6106]  INFO -- : process privilege user: toki(1000)I, [2015-01-26T23:20:24.596985 #6106]  INFO -- : process privilege group: toki(1000)

If setup is success, empty mailbox named INBOX is shown at mailaccount of your e-mail client.

Last, type Ctrl+C on your console to stop server.

In this section, the way that you deliver mail to mailbox on RIMS isdescribed. Prepare a sample mail text file that is picked from youre-mail client. The sample mail file is namedmail.txt on descriptionof this section.

Simple way is that you use IMAP APPEND command.rims tool has IMAPAPPEND command. Type following on your console.

$ bundle exec rims imap-append -v -n 192.168.56.101 -o 1430 -u foo -w bar mail.txtstore flags: ()server greeting: OK RIMS vX.Y.Z IMAP4rev1 service ready.server capability: IMAP4REV1 UIDPLUS AUTH=PLAIN AUTH=CRAM-MD5login: OK LOGIN completedappend: OK  APPEND completed

The option of-v is verbose mode. If you don't need displayinformation, no verbose option exists. If mail delivery is success,you will see that message appears in INBOX on your e-mail client.

The advantage of IMAP APPEND is to be able to use it by any IMAP mailserver as well as RIMS. The disadvantage of IMAP APPEND is that itrequires your password. This may be insecure.

Special user is defined to deliver mail to any user's mailbox on RIMS.By special user, it is possible to deliver mail without your password.The disadvantage of special user is that it can be used only in RIMS.

At first, you prepare a special user to deliver mail. Type followingin configuration file. And start RIMS.

user_list:  -{ user: foo, pass: bar }  -{ user: "#postman", pass: "#postman" }

And type following on your console.

$ bundle exec rims post-mail -v -n 192.168.56.101 -o 1430 -w '#postman' foo mail.txtstore flags: ()server greeting: OK RIMS vX.Y.Z IMAP4rev1 service ready.server capability: IMAP4REV1 UIDPLUS AUTH=PLAIN AUTH=CRAM-MD5login: OK LOGIN completedappend: OK  APPEND completed

The option of-v is verbose mode. If you don't need displayinformation, no verbose option exists. If mail delivery is success,you will see that message appears in INBOX on your e-mail client.

Default port number of RIMS is 1430. IMAP protocol well known portnumber is 143. If RIMS opens server socket with 143 port, it needs tobe root user process at unix. But RIMS doesn't need to be root userprocess as IMAP server.

To open server socket with well known 143 port at RIMS:

1. RIMS starts at root user.
2. RIMS opens server socket with 143 port by root user privilege.
3. RIMS calls setuid(2). And privilege of process is changed from rootuser to another.
4. RIMS starts IMAP server with another's process privilege.

For example, port number isimap2 (it is service name of well knownport of 143), process user privilege istoki (uid 1000), and processgroup privilege istoki (gid 1000). Type following in configurationfile.

user_list:  -{ user: foo, pass: bar }  -{ user: "#postman", pass: "#postman" }imap_port:imap2process_privilege_user:tokiprocess_privilege_group:toki

And type following on your console.

$ sudo bundle exec rims server -f config.yml[sudo] password for toki: I, [2015-01-31T21:32:30.069848 #9381]  INFO -- : start server.I, [2015-01-31T21:32:30.070068 #9381]  INFO -- : open socket: 0.0.0.0:imap2I, [2015-01-31T21:32:30.070374 #9381]  INFO -- : opened: [AF_INET][143][0.0.0.0][0.0.0.0]I, [2015-01-31T21:32:30.070559 #9381]  INFO -- : process ID: 9381I, [2015-01-31T21:32:30.070699 #9381]  INFO -- : process privilege user: toki(1000)I, [2015-01-31T21:32:30.070875 #9381]  INFO -- : process privilege group: toki(1000)

If RIMS server is started from console terminal, RIMS server processis terminated on closing its console terminal. At unix, serverprocess has to be started as daemon process for the server to keeprunning its service.

RIMS server can start as daemon process. Type following on yourconsole.

$ sudo bundle exec rims daemon start -f config.yml

sudo is required for well known 143 port (see previous section).Daemon process is started quietly and prompt of console terminal isreturned immediately. But daemon process is running at background.To see background daemon process, type following on your console.

$ ps -elf | grep rims5 S root      3191  1720  0  80   0 - 23026 wait   21:10 ?        00:00:00 ruby /home/toki/rims/vendor/ruby/2.2.0/bin/rims daemon start -f config.yml5 S toki      3194  3191  0  80   0 - 26382 inet_c 21:10 ?        00:00:00 ruby /home/toki/rims/vendor/ruby/2.2.0/bin/rims daemon start -f config.yml

RIMS daemon is two processes. 1st root process is controller process.2nd process that isn't root is server process. RIMS daemon doesn'tdisplay messages and errors at console. You should see log files toverify normal running of RIMS daemon.

To see log of controller process, watch syslog at system directory.Type following on your console.

$ tail -f /var/log/syslogFeb  1 21:10:00 vbox-linux rims-daemon[3191]: start daemon.Feb  1 21:10:00 vbox-linux rims-daemon[3191]: run server process: 3194

To see log of server process, watch imap.log at local directory. Typefollowing on your console.

$ tail -f imap.logI, [2015-02-01T21:10:00.989859 #3194]  INFO -- : start server.I, [2015-02-01T21:10:00.990084 #3194]  INFO -- : open socket: 0.0.0.0:imap2I, [2015-02-01T21:10:00.990989 #3194]  INFO -- : opened: [AF_INET][143][0.0.0.0][0.0.0.0]I, [2015-02-01T21:10:00.991393 #3194]  INFO -- : process ID: 3194I, [2015-02-01T21:10:00.991615 #3194]  INFO -- : process privilege user: toki(1000)I, [2015-02-01T21:10:00.991703 #3194]  INFO -- : process privilege group: toki(1000)

RIMS daemon process can be controlled from command line tool. Definedoperations are start, stop, restart and status. Start operation isalready described.

Stop operation:

$ sudo bundle exec rims daemon stop -f config.yml

Restart operation:

$ sudo bundle exec rims daemon restart -f config.yml

Status operation:

$ sudo bundle exec rims daemon status -f config.ymldaemon is running.$ sudo bundle exec rims daemon status -f config.ymldaemon is stopped.

Server options on start may be described at config.yml file.Config.yml is a YAML format file and its contents are explainedat later.

To start server with config.yml file, type following.

$ bundle exec rims server -f a_server_directory/config.yml

base_dir

This parameter describes a base directory of server. Mailbox data is located at inside of base directory. Default is a parent directory of config.yml file. Explicit description of this parameter is interpreted as a relative path from a parent directory of config.yml file.

log_stdout

This parameter describes a severity level of logging messages that is written to standard output. See description of Logger class for more detail of logging. This parameter is one value selected from DEBUG, INFO, WARN, ERROR or FATAL. If QUIET value is chosen, standard output logging is disabled. Default is INFO. The danger is that password may be embedded in message on user authentication in DEBUG logging level.

log_file

This parameter describes a path of log file. Default is "imap.log" under the base_dir. Explicit description of this parameter is interpreted as a relative path from a base_dir.

log_level

This parameter describes a severity level of logging messages. See description of Logger class for more detail of logging. This parameter is one value selected from DEBUG, INFO, WARN, ERROR or FATAL. Default is INFO. The danger is that password may be embedded in message on user authentication in DEBUG logging level.

log_shift_age

This parameter describes a number of old rotated log files to keep or periodical log rotation. Decimal number is interpreted as a number of files to keep. Periodical log rotation is one value selected from daily, weekly or monthly. Default is none. See description of Logger.new class method for more detail of log rotation.

log_shift_size

This parameter describes a maximum log file size on log file rotation. Default is none. See description of Logger.new class method for more detail of log rotation.

key_value_store_type

This parameter describes a type of key-value store. Key-value store is used to save a mailbox data. This parameter is only one value of GDBM, and it is default value.

use_key_value_store_checksum

This parameter decides whether to use checksum. This parameter is boolean, true or false. If this parameter is true, a mailbox data is saved with its checksum to an entry of key-value store, and a checksum is checked on loading a mailbox data from an entry of key-value store. Default is true.

hostname

This parameter describes a hostname of server. Default is the name displayed by hostname(1) command.

username

This parameter describes a name of mailbox user. This parameter and the next password parameter are the pair. If there are two or many users, user_list parameter should be used instead of this parameter. At least one user is need to start a server.

password

This parameter describes a password of mailbox user. This parameter and the previous username parameter are the pair. If there are two or many users, user_list parameter should be used instead of this parameter. At least one user is need to start a server.

user_list

This parameter describes many users of mailbox. The value of this parameter is a sequence of maps. A map in the sequence should have two entries, the two entries are user and pass. user entry describes name of a user. pass entry describes password of a user. At least one user is need to start a server.

imap_host

This parameter describes hostname or IP address of a server socket to listen(2) and accept(2). Default is 0.0.0.0.

imap_port

This parameter describes IP port number or service name of a server socket to listen(2) and accept(2). Default is 1430.

mail_delivery_user

This parameter describes a special user to deliver mail to any user. Password definition of this special user is same to a normal user. Default is "#postman".

process_privilege_user

This parameter describes a privilege user name or ID for server process. When server process starts on root user, setuid(2) is called and server process privilege user is changed from root user to this parameter user. Default is 65534 (typical user ID of nobody) and should be changed.

process_privilege_group

This parameter describes a privilege group name or ID for server process. When server process starts on root user, setgid(2) is called and server process privilege group is changed from root group to this parameter group. Default is 65534 (typical group ID of nogroup) and should be changed.

Mailbox data exists under the base directory. Next picture is aoverview of mailbox data filesystem under the base directory.

a_base_directory|+-- mailbox.2/    |    +-- 2c/        |        +-- 26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae/            |            +-- message            |            +-- meta            |            +-- mailbox_1            |            +-- mailbox_2            |            ...

There is a MAILBOX_DATA_STRUCTURE_VERSION directory under firstinside of the base directory. When mailbox data structure will bechanged in future, MAILBOX_DATA_STRUCTURE_VERSION directory will bechanged too. Now latest version is "mailbox.2".

There are user directories under the MAILBOX_DATA_STRUCTURE_VERSIONdirectory. A user is identified by unique user ID. Unique user ID isa SHA256 HEX digest of a username. For example, type following todisplay a "foo" user's unique user ID.

$ bundle exec rims unique-user-id foo2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae

First two characters of unique user ID is used as a bucket directory.Unique user ID substring from 3rd character to last exists as a userdirectory under the bucket directory. Shortcut tool to search a twolevel directory of a user under a base directory exists. For example,type following to display a "foo" user's directory.

$ bundle exec rims show-user-mbox a_base_directory fooa_base_directory/mailbox.2/2c/26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae

There are three types of files under the user directory. Three typesare message, meta and mailbox. Each file is key-value store. Onlyone type of key-value store is available now, it is GDBM. A GDBMkey-value store file has a filename suffix, the suffix is ".gdbm".Mailbox data does not depend on a specific type of key-value store.

Message key-value store file preserves all messages of a user. Perone user, only one file exists about this file type. Contents ofmessage key-value store is simple. A key is a message ID, and a valueis message text. A message ID is a unique number of a message in RIMSinternal. For example, type following to see overview of contents ata message key-value store.

$ bundle exec rims debug-dump-kvs --dump-size --no-dump-value a_base_directory/mailbox.2/2c/26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae/message"2": 21938 bytes"1": 126014 bytes"4": 22928 bytes"0": 6326 bytes"3": 65168 bytes

Meta key-value store file preserves all meta data of message andfolders. Per one user, only one file exists about this file type.Contents of meta key-value store is complex, and only outline ofcontent is described here.

dirty

Dirty flag. If enabled, this flag exists. If disabled, this flag doesn't exists. This flag will be enabled on updating mailbox data.

cnum

A change number of mailbox data. If mailbox data is modified, this number is increased.

msg_id

The next number of message ID. Message ID is unique number of message in RIMS internal.

uidvalidity

The next number of uidvalidity. Uidvalidity is unique number of mailbox in IMAP.

mbox_set

Mailbox set of a user.

mbox_id2name-#

Mapping from mailbox ID to mailbox name.

mbox_name2id-#

Mapping from mailbox name to mailbox ID.

mbox_id2uid-#

The next uid at a mailbox. Uid is unique number of message at a mailbox in IMAP.

mbox_id2msgnum-#

Number of messages at a mailbox.

mbox_id2flagnum-#-#

Number of flags at a mailbox.

msg_id2date-#

Mapping from message ID to internal date of a message. Internal date is a message attribute in IMAP.

msg_id2flag-#

Set of flags at a message.

msg_id2mbox-#

Mapping from message ID to mailbox's uid.

For example, type following to see overview of contents at a meta key-value store.

$ bundle exec rims debug-dump-kvs a_base_directory/mailbox.2/2c/26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae/meta"msg_id2mbox-3": 25 bytes: {1=>#<Set: {4}>}"msg_id2date-2": 49 bytes: 2013-11-08 13:34:10 +0900"mbox_id2uid-1": 1 bytes: "6""msg_id2mbox-1": 25 bytes: {1=>#<Set: {2}>}"msg_id2flag-2": 6 bytes: "recent""mbox_id2msgnum-1": 1 bytes: "5""uidvalidity": 1 bytes: "2""mbox_id2flagnum-1-recent": 1 bytes: "5""msg_id2date-0": 49 bytes: 2013-11-08 06:47:50 +0900"cnum": 1 bytes: "6""msg_id2date-4": 49 bytes: 2013-11-08 11:57:28 +0900"msg_id2mbox-2": 25 bytes: {1=>#<Set: {3}>}"mbox_set": 1 bytes: "1""msg_id2flag-0": 6 bytes: "recent""msg_id2flag-4": 6 bytes: "recent""msg_id2date-1": 49 bytes: 2013-11-08 19:31:03 +0900"msg_id": 1 bytes: "5""mbox_id2name-1": 5 bytes: "INBOX""msg_id2mbox-0": 25 bytes: {1=>#<Set: {1}>}"mbox_name2id-INBOX": 1 bytes: "1""msg_id2mbox-4": 25 bytes: {1=>#<Set: {5}>}"msg_id2flag-1": 6 bytes: "recent""msg_id2date-3": 49 bytes: 2013-11-08 12:47:17 +0900"msg_id2flag-3": 6 bytes: "recent"

Mailbox key-value store file preserves key-value pairs of uid andmessage ID. Per one user, plural files exist about this type of filebecause plural mailboxes are allowed at one user. Mailbox key-valuestore filenames are "mailbox_1", "mailbox_2", ... And 1,2,... aremailbox ID. Contents of mailbox key-value store is simple. A key isa uid, and a value is message ID. A uid is a unique number of amessage in a mailbox in IMAP. A message ID is a unique number of amessage in RIMS internal. For example, type following to see overviewof contents at a mailbox key-value store.

$ bundle exec rims debug-dump-kvs a_base_directory/mailbox.2/2c/26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae/mailbox_1"2": 1 bytes: "1""5": 1 bytes: "4""1": 1 bytes: "0""4": 1 bytes: "3""3": 1 bytes: "2"

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request