rims 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29c18b0a88fc771e30319973c66baff76e8a4c6c9d7bc9c8c239dd78cf25b9c1
+  data.tar.gz: d6e6f213bfea0ff8684de0b79e625face9f6ad22c6e6f94d23aaa900ca526805
+SHA512:
+  metadata.gz: ee07de390442b50d654e4290488be4ca99b72ee42ca6f4dcae6a745a43155d001284d8356a56ab4231ecd3dfc19a02965efd6fd007e5ec44c2f3128d9e296896
+  data.tar.gz: 4519d3182df3ada8bf8a9cf6fa1a8d89673db9fdb7f500735fbf703e211dce4a851e5e9630976be3de89839eb79541aec75d87fc409a11560005d1b10a110064

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/ChangeLog

@@ -0,0 +1,379 @@
+2019-02-18  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* README.md, rims.gemspec: fixed for release to rubygems.
+
+	* lib/rims/version.rb : start to version 0.2.1.
+
+2018-12-02  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/gdbm_kvs.rb, lib/rims/kvs.rb,
+	lib/rims/server.rb ,lib/rims/test.rb:
+	key-value store. added plug-in API.
+
+2018-11-13  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* README.md: modified installation example.
+
+	* lib/rims/mail_store.rb (RIMS::MailFolder),
+	lib/rims/protocol/decoder.rb (RIMS::Protocol::UserMailboxDecoder):
+	IMAP IDLE interruption control is moved from
+	RIMS::Protocol::UserMailboxDecoder class to
+	RIMS::MailFolder class.
+
+	* lib/rims/mail_store.rb (RIMS::MailStore): open a mailbox
+	database on demand.
+
+2018-11-03  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb (RIMS::Cmd#cmd_post_mail, RIMS::Cmd#cmd_imap_append):
+	it should be treated as binary to be neutral to message
+	encoding. the message from standard input was not binary, so it
+	was fixed to binary.
+
+2018-10-05  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol/parser.rb, lib/rims/protocol/decoder.rb:
+	split from lib/rims/protocol.rb.
+
+2017-06-17  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims.rb, lib/rims/error.rb, lib/rims/lock.rb,
+	lib/rims/protocol.rb: API errors should be defined at API
+	implementations.
+
+2017-03-26  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* test/test_protocol_fetch.rb: fixed for warning: constant
+	::Bignum is deprecated.
+
+2016-12-25  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb, lib/rims/rfc822.rb: some body fields at
+	BODYSTRUCTURE response should be uppercase letters.
+
+2016-12-11  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/mail_store.rb, lib/rims/protocol.rb: IMAP IDLE command
+	is implemented.
+
+2016-09-22  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims.rb, lib/rims/mail_store.rb, lib/rims/pool.rb,
+	lib/rims/protocol.rb, lib/rims/server.rb, test/test_mail_store.rb,
+	test/test_protocol_decoder.rb: untagged server response.
+
+2016-08-22  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/mail_store.rb, lib/rims/protocol.rb: the message
+	numbers that are returned from a folder's expunge_mbox method
+	should be always consistent with a client side message number
+	list. and close command should be return expunge response.
+
+	* lib/rims/mail_store.rb: late loading message number list of
+	mailbox folder.
+
+	* lib/rims/error.rb, lib/rims/lock.rb, lib/rims/mail_store.rb,
+	lib/rims/protocol.rb: read-write lock and lock-try timeout is
+	defined for IMAP command interaction.
+
+2016-08-21  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/server.rb: defined I/O-buffered writer for response
+	sender socket.
+
+2016-07-18  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: protocol decoder. IMAP commands I/F are
+	changed to block method. refactoring IMAP command implementations
+	to suit a method call given block.
+
+2016-07-02  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/rfc822.rb: header field name should not contain a colon
+	character.
+
+2016-06-29  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: fixed a bug of protocol decoder chain
+	cleanup. cleanup method should be called from last decoder of
+	chain. the bug is that cleanup method was called from first
+	decoder of chain. therefor next decoders cleanup method was not
+	called.
+
+2016-06-26  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb: a unique user ID should not be modified.
+
+2016-06-05  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb, lib/rims/rfc822.rb,
+	test/test_db_recovery.rb, test/test_mail_store.rb,
+	test/test_protocol_auth.rb, test/test_protocol_decoder.rb,
+	test/test_protocol_fetch.rb: clear warning messages
+
+	* lib/rims/mail_store.rb: abort handling of transaction is
+	changed.
+
+2016-05-29  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/rfc822.rb: special character double-quote is handled to
+	parsing mail address
+
+2016-03-27  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/version.rb: version number is changed to 0.2.0.
+
+2015-11-03  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb, lib/rims/passwd.rb, test/test_passwd.rb:
+	refactored API of password source plug-in. explanation comments
+	are added for passowrd source plug-in API.
+
+2015-10-11  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb, lib/rims/passwd.rb, lib/rims/server.rb:
+	logging and start/stop hooks are defined at password source plug-in
+	mechanism.
+
+2015-05-10  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/server.rb: a configuration parameter to load libraries
+	is defined.
+
+	* lib/rims.rb, lib/rims/auth.rb, lib/rims/cmd.rb,
+	lib/rims/passwd.rb, lib/rims/server.rb: password source plug-in
+	mechanism is defined. plain password source and hash password
+	soruce are registered. pass-hash tool for hash password source is
+	defined.
+
+2015-02-22  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* RIMS version 0.1.0 is released.
+
+2015-02-08  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: returning response with user data recovery
+	message from IMAP server is step by step.
+
+2015-02-03  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* README.md: Tutorial section is written.
+
+2015-01-25  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: fixed response of search command bad pattern.
+
+2015-01-24  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: search command optimization.
+
+	* lib/rims/mail_store.rb: message list attribute of mailbox folder
+	is encapsulated. and small message sequence set access on mailbox
+	folder may be fast.
+
+2015-01-22  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: fixed a bug of store command response.
+
+2015-01-20  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* rims.gemspec: explicit dependency for test-unit is defined.
+	changed for ruby-2.2.0.
+
+2015-01-10  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/daemon.rb: signal(2) interruption robust event loop for
+	daemon process.
+
+2015-01-04  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/server.rb: unsuitable named server
+	configuration parameters and command line options are renamed to
+	suitable names.
+
+2015-01-02  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/daemon.rb: daemon process is
+	implemented and daemon process start/stop/status tool is defined.
+
+2014-12-26  Joe Yates <joe.g.yates@gmail.com>
+
+	* lib/rims/mail_store.rb, lib/rims/protocol.rb: Implement the UIDPLUS extension
+
+	* test/test_protocol_decoder.rb, test/test_protocol_fetch.rb:
+	Ensure Time objects have the correct timezone
+
+2014-12-21  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/server.rb: server process privilege separated from root user.
+
+2014-12-10  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/server.rb: stdout logging.
+
+2014-12-01  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb, lib/rims/cmd.rb, lib/rims/protocol.rb:
+	post-mail mechanism is defined. `post-mail user' and `post-mail
+	command' are defined for this mechanism. authenticated special
+	user is able to post message to any user.
+
+	* load_test/Rakefile: load test of post-mail command.
+
+2014-11-19  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* load_test/Rakefile: load test of imap-append command.
+
+2014-08-21  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/server.rb: path location described at config.yml is changed.
+	on loading config.yml, base_dir is a relative path from a parent
+	directory of config.yml file. log file path is a relative path
+	from a base_dir.
+
+2014-08-18  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/server.rb: stop server message.
+
+	* lib/rims/protocol.rb: I/O string debug log utility function.
+
+2014-08-12  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb, lib/rims/server.rb: user list entry for
+	multi-user account is defined at server configuration file. some
+	maintenance commands of multi-user mailbox is defined.
+
+2014-07-30  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/mail_store.rb, lib/rims/protocol.rb,
+	lib/rims/server.rb, lib/rims/version.rb:
+	multi-user mailbox. layout of parent directory of mailbox
+	key-value store is changed from single user layout.
+
+2014-07-11  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb, lib/rims/cmd.rb, lib/rims/server.rb:
+	reformed server configuration API.
+
+2014-07-09  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: logging message for user data recovery.
+
+	* lib/rims/cmd.rb: new `--auth-type' option is defiend to choose a
+	method of IMAP user authentication at imap-append command utility.
+
+2014-07-03  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/auth.rb, lib/rims/protocol.rb, lib/rims/server.rb,
+	test/test_auth.rb, test/test_protocol_auth.rb, test/test_protocol_decoder.rb:
+	implemented user authentication mechanism and added IMAP authenticate command.
+	capable authentication types are `plain' and `cram-md5'.
+
+2014-06-08  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* RIMS version 0.0.4 is released.
+
+2014-06-06  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb, test/test_protocol_search.rb,
+	test/test_protocol_decoder.rb: charset parameter can be used on
+	search command.
+
+2014-06-05  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/test.rb, test/test_protocol_decoder.rb,
+	test/test_protocol_fetch.rb, test/test_protocol_search.rb: refactored unit test.
+
+2014-05-21  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/test.rb, test/test_rfc822.rb, test/test_mail_store.rb,
+	test/test_protocol.rb, test/test_protocol_fetch.rb,
+	test/test_protocol_search.rb: refactored unit test.
+
+2014-05-08  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/rfc822.rb, lib/rims/protocol.rb, lib/rims/cmd.rb, rims.gemspec:
+	mail parser is replaced from mail gem to RIMS::RFC822 parser.
+	mail gem is not need and deleted from gemspec.
+
+2014-04-15  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* RIMS version 0.0.3 is released.
+
+2014-04-10  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb: version command is defined.
+
+2014-04-09  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb: added mbox-dirty-flag command. this command
+	show/enable/disable dirty flag of mailbox to force recovery.
+
+	* lib/rims/db.rb, lib/rims/mail_store.rb, lib/rims/protocol.rb:
+	dirty flag check and data recovery process are added to storage
+	backend of mail store.
+
+2014-03-20  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cksum_kvs.rb, lib/rims/kvs.rb, lib/rims/server.rb, lib/rims/cmd.rb:
+	checksum key-value store is defined. server mailbox data is
+	verified with checksum at default.
+
+	* lib/rims/cmd.rb: added entry size dump option to debug-dump-kvs
+	command.
+
+2014-03-15  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/kvs.rb, lib/rims/gdbm_kvs.rb, lib/rims/db.rb, lib/rims/mail_store.rb:
+	destroy API is defined at key-value store and mailbox DB file is
+	removed on mailbox deletion.
+
+	* lib/rims/kvs.rb: key-value store. fixed a bug of abstract method.
+	origin of bug is commit of 4f4ce383b8df541a60ba7d62e7626d3e34b29888.
+	bug file was `kv.rb'. the file was renamed to `kvs.rb'. basic
+	method name was changed. but its call name in abstract method was
+	not changed.
+
+	* lib/rims/server.rb: mail store path of server is changed because
+	of incompatibility between new DB and old DB.
+
+2014-03-14  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/db.rb, lib/rims/mail_store.rb, lib/rims/protocol.rb:
+	backend storage of mail store is replaced to new DB.
+
+2014-03-06  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* rename key-value store filename (kv.rb -> kvs.rb, gdbm_kv.rb ->
+	gdbm_kvs.rb).
+
+	* lib/rims/gdbm_kv.rb, lib/rims/cmd.rb: read-only GDBM DB open at
+	debug-dump-kvs command.
+
+	* lib/rims/cmd.rb: add assertion check of command name following
+	contract naming rule.
+
+2014-03-05  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* RIMS version 0.0.2 is released.
+
+	* lib/rims/protocol.rb, lib/rims/mail_store.rb: add fine grain
+	lock for one user multiple connection.
+
+2014-03-04  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/cmd.rb: add debug-dump-kvs command.
+
+2014-03-01  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/server.rb, lib/rims/cmd.rb: add server log rotation.
+
+2014-02-27  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* lib/rims/protocol.rb: fast error recovery on connection fatal
+	error (ex. Errno::EPIPE).
+
+2014-02-24  TOKI Yoshinori  <toki@freedom.ne.jp>
+
+	* RIMS version 0.0.1 is released.
+

data/Gemfile

@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rims.gemspec
+gemspec
+
+# Local Variables:
+# mode: Ruby
+# indent-tabs-mode: nil
+# End:

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013-2014 TOKI Yoshinori
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,566 @@
+RIMS
+====
+
+RIMS is Ruby IMap Server.
+This gem provides a complete IMAP server by itself.  The IMAP
+server can run as a daemon, mailboxes are provided and messages
+can be delivered to them.
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'rims'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rims
+
+Simple Usage
+------------
+
+Type following to show usage.
+
+    $ bundle exec rims help
+    usage: rims command options
+    
+    commands:
+        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
+
+Tutorial
+--------
+
+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 is `192.168.56.101`, username is `foo`,
+and password is `bar`.
+
+### First step
+
+Let's try to start RIMS. Type following on your console. And some
+messages are shown at console.
+
+    $ bundle exec rims server -u foo -w bar
+    I, [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:1430
+    I, [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: 24475
+    I, [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 is `foo`.
+* IMAP server is `192.168.56.101`. This may be replaced to your server
+  hostname or IP address.
+* IMAP port number is `1430`. This is default of RIMS.
+* IMAP authentication password is `bar`.
+
+If setup is success, empty mailbox named INBOX is shown at new mail
+account of your e-mail client.
+
+Last, type Ctrl+C on your console to stop server.
+
+### Configuration file
+
+Password at command line parameter is insecure because password is
+peeped from another user using `ps aux`. Username and password should
+be written at configuration file.
+
+RIMS configuration file format is YAML. Type following in file of
+`config.yml` and save.
+
+```yaml
+user_list:
+  - { user: foo, pass: bar }
+```
+
+And start RIMS with `-f config.yml` option.
+
+    $ bundle exec rims server -f config.yml
+    I, [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:1430
+    I, [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: 6106
+    I, [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 mail
+account of your e-mail client.
+
+Last, type Ctrl+C on your console to stop server.
+
+### Mail delivery to mailbox
+
+In this section, the way that you deliver mail to mailbox on RIMS is
+described. Prepare a sample mail text file that is picked from your
+e-mail client. The sample mail file is named `mail.txt` on description
+of this section.
+
+Simple way is that you use IMAP APPEND command. `rims` tool has IMAP
+APPEND command. Type following on your console.
+
+    $ bundle exec rims imap-append -v -n 192.168.56.101 -o 1430 -u foo -w bar mail.txt
+    store flags: ()
+    server greeting: OK RIMS vX.Y.Z IMAP4rev1 service ready.
+    server capability: IMAP4REV1 UIDPLUS AUTH=PLAIN AUTH=CRAM-MD5
+    login: OK LOGIN completed
+    append: OK  APPEND completed
+
+The option of `-v` is verbose mode. If you don't need display
+information, 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 mail
+server as well as RIMS. The disadvantage of IMAP APPEND is that it
+requires 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 following
+in configuration file. And start RIMS.
+
+```yaml
+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.txt
+    store flags: ()
+    server greeting: OK RIMS vX.Y.Z IMAP4rev1 service ready.
+    server capability: IMAP4REV1 UIDPLUS AUTH=PLAIN AUTH=CRAM-MD5
+    login: OK LOGIN completed
+    append: OK  APPEND completed
+
+The option of `-v` is verbose mode. If you don't need display
+information, no verbose option exists. If mail delivery is success,
+you will see that message appears in INBOX on your e-mail client.
+
+### IMAP well known port and server process privilege
+
+Default port number of RIMS is 1430. IMAP protocol well known port
+number is 143. If RIMS opens server socket with 143 port, it needs to
+be root user process at unix. But RIMS doesn't need to be root user
+process 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 root
+   user to another.
+4. RIMS starts IMAP server with another's process privilege.
+
+For example, port number is `imap2` (it is service name of well known
+port of 143), process user privilege is `toki` (uid 1000), and process
+group privilege is `toki` (gid 1000). Type following in configuration
+file.
+
+```yaml
+user_list:
+  - { user: foo, pass: bar }
+  - { user: "#postman", pass: "#postman" }
+imap_port: imap2
+process_privilege_user: toki
+process_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:imap2
+    I, [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: 9381
+    I, [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)
+
+### Daemon
+
+If RIMS server is started from console terminal, RIMS server process
+is terminated on closing its console terminal.  At unix, server
+process has to be started as daemon process for the server to keep
+running its service.
+
+RIMS server can start as daemon process. Type following on your
+console.
+
+    $ 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 is
+returned immediately. But daemon process is running at background.
+To see background daemon process, type following on your console.
+
+    $ ps -elf | grep rims
+    5 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.yml
+    5 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't
+display messages and errors at console. You should see log files to
+verify 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/syslog
+    Feb  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. Type
+following on your console.
+
+    $ tail -f imap.log
+    I, [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:imap2
+    I, [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: 3194
+    I, [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. Defined
+operations are start, stop, restart and status. Start operation is
+already 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.yml
+    daemon is running.
+
+    $ sudo bundle exec rims daemon status -f config.yml
+    daemon is stopped.
+
+Server Configuration
+--------------------
+
+Server options on start may be described at config.yml file.
+Config.yml is a YAML format file and its contents are explained
+at later.
+
+To start server with config.yml file, type following.
+
+    $ bundle exec rims server -f a_server_directory/config.yml
+
+### Config.yml Parameters
+
+<dl>
+  <dt>base_dir</dt>
+  <dd>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.</dd>
+
+  <dt>log_stdout</dt>
+  <dd>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.</dd>
+
+  <dt>log_file</dt>
+  <dd>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.</dd>
+
+  <dt>log_level</dt>
+  <dd>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.</dd>
+
+  <dt>log_shift_age</dt>
+  <dd>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.</dd>
+
+  <dt>log_shift_size</dt>
+  <dd>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.</dd>
+
+  <dt>key_value_store_type</dt>
+  <dd>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.</dd>
+
+  <dt>use_key_value_store_checksum</dt>
+  <dd>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.</dd>
+
+  <dt>hostname</dt>
+  <dd>This parameter describes a hostname of server. Default is the
+  name displayed by hostname(1) command.</dd>
+
+  <dt>username</dt>
+  <dd>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.</dd>
+
+  <dt>password</dt>
+  <dd>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.</dd>
+
+  <dt>user_list</dt>
+  <dd>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.</dd>
+
+  <dt>imap_host</dt>
+  <dd>This parameter describes hostname or IP address of a server
+  socket to listen(2) and accept(2). Default is 0.0.0.0.</dd>
+
+  <dt>imap_port</dt>
+  <dd>This parameter describes IP port number or service name of a
+  server socket to listen(2) and accept(2). Default is 1430.</dd>
+
+  <dt>mail_delivery_user</dt>
+  <dd>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".</dd>
+
+  <dt>process_privilege_user</dt>
+  <dd>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.</dd>
+
+  <dt>process_privilege_group</dt>
+  <dd>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.</dd>
+</dl>
+
+Mailbox Data
+------------
+
+Mailbox data exists under the base directory. Next picture is a
+overview 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 first
+inside of the base directory.  When mailbox data structure will be
+changed in future, MAILBOX\_DATA\_STRUCTURE\_VERSION directory will be
+changed too.  Now latest version is "mailbox.2".
+
+There are user directories under the MAILBOX\_DATA\_STRUCTURE\_VERSION
+directory.  A user is identified by unique user ID.  Unique user ID is
+a SHA256 HEX digest of a username.  For example, type following to
+display a "foo" user's unique user ID.
+
+    $ bundle exec rims unique-user-id foo
+    2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae 
+
+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 user
+directory under the bucket directory.  Shortcut tool to search a two
+level 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 foo
+    a_base_directory/mailbox.2/2c/26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae
+
+There are three types of files under the user directory.  Three types
+are message, meta and mailbox.  Each file is key-value store.  Only
+one type of key-value store is available now, it is GDBM.  A GDBM
+key-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
+
+Message key-value store file preserves all messages of a user.  Per
+one user, only one file exists about this file type.  Contents of
+message key-value store is simple.  A key is a message ID, and a value
+is message text.  A message ID is a unique number of a message in RIMS
+internal.  For example, type following to see overview of contents at
+a 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
+
+Meta key-value store file preserves all meta data of message and
+folders.  Per one user, only one file exists about this file type.
+Contents of meta key-value store is complex, and only outline of
+content is described here.
+
+<dl>
+  <dt>dirty</dt>
+  <dd>Dirty flag. If enabled, this flag exists. If disabled, this flag
+  doesn't exists. This flag will be enabled on updating mailbox
+  data.</dd>
+
+  <dt>cnum</dt>
+  <dd>A change number of mailbox data. If mailbox data is modified,
+  this number is increased.</dd>
+
+  <dt>msg_id</dt>
+  <dd>The next number of message ID. Message ID is unique number of
+  message in RIMS internal.</dd>
+
+  <dt>uidvalidity</dt>
+  <dd>The next number of uidvalidity. Uidvalidity is unique number of
+  mailbox in IMAP.</dd>
+
+  <dt>mbox_set</dt>
+  <dd>Mailbox set of a user.</dd>
+
+  <dt>mbox_id2name-#</dt>
+  <dd>Mapping from mailbox ID to mailbox name.</dd>
+
+  <dt>mbox_name2id-#</dt>
+  <dd>Mapping from mailbox name to mailbox ID.</dd>
+
+  <dt>mbox_id2uid-#</dt>
+  <dd>The next uid at a mailbox. Uid is unique number of message at a
+  mailbox in IMAP.</dd>
+
+  <dt>mbox_id2msgnum-#</dt>
+  <dd>Number of messages at a mailbox.</dd>
+
+  <dt>mbox_id2flagnum-#-#</dt>
+  <dd>Number of flags at a mailbox.</dd>
+
+  <dt>msg_id2date-#</dt>
+  <dd>Mapping from message ID to internal date of a message. Internal
+  date is a message attribute in IMAP.</dd>
+
+  <dt>msg_id2flag-#</dt>
+  <dd>Set of flags at a message.</dd>
+
+  <dt>msg_id2mbox-#</dt>
+  <dd>Mapping from message ID to mailbox's uid.</dd>
+</dl>
+
+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
+
+Mailbox key-value store file preserves key-value pairs of uid and
+message ID.  Per one user, plural files exist about this type of file
+because plural mailboxes are allowed at one user.  Mailbox key-value
+store filenames are "mailbox\_1", "mailbox\_2", ...  And 1,2,... are
+mailbox ID.  Contents of mailbox key-value store is simple.  A key is
+a uid, and a value is message ID.  A uid is a unique number of a
+message in a mailbox in IMAP.  A message ID is a unique number of a
+message in RIMS internal.  For example, type following to see overview
+of 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"
+
+Contributing
+------------
+
+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