You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Pluto is a distributed IMAP server that implements a subset of the [IMAPv4 standard](https://tools.ietf.org/html/rfc3501). It makes use of [Conflict-free Replicated Data Types](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)to allow state to be kept on each worker node but still achieve system-wide convergence of user data. Pluto is written in Go.
5
+
Pluto is a distributed IMAP server that implements a subset of the [IMAPv4 standard](https://tools.ietf.org/html/rfc3501). It makes use of [Conflict-free Replicated Data Types](https://en.wikipedia.org/wiki/Conflict-free_replicated_data_type)defined by Shapiro et al. to replicate application state into traditionally stateless tiers (worker nodes) and still achieve system-wide convergence of user data. By this, pluto attempts to offer a solution towards the challenges arising from Brewer's [CAP theorem](https://en.wikipedia.org/wiki/CAP_theorem): in case of failures in the system, choose to stay available by accepting reduced consistency in form of the CRDT's [strong eventual consistency](https://en.wikipedia.org/wiki/Eventual_consistency#Strong_eventual_consistency). Pluto is written in Go and provided under copyleft license [GPLv3](https://github.com/numbleroot/pluto/blob/master/LICENSE).
6
6
7
7
8
8
## Status
9
9
10
-
**Work in progress:**This is the code base for my Bachelor Thesis. It is heavily work in progress and not ready yet.
10
+
**Use with caution and not in production:**this is a prototypical implementation of the system architecture and presented concepts discussed in my Bachelor Thesis.
11
11
12
12
13
13
## Installation
14
14
15
15
If you have a working [Go](https://golang.org/) setup, installation is as easy as:
16
16
17
17
```bash
18
-
$ go get github.com/numbleroot/pluto
18
+
$ go get -u github.com/numbleroot/pluto
19
19
```
20
20
21
21
22
-
## Setup
22
+
## Quick Start
23
23
24
-
### Quick Setup
24
+
You need to configure your pluto setup in a `config.toml` file. Please refer to the provided [config.toml.example](https://github.com/numbleroot/pluto/blob/master/config.toml.example) for an exemplary configuration that only needs adaptation to your requirements.
25
+
26
+
**Important:** Please make sure, not to include `|` (pipe character) in names for your distributor, worker and storage nodes as this character is used in marshalled messages sent on internal network.
25
27
26
28
If you know what happens in background, these are the steps to take in order to ready pluto for use:
27
29
28
30
```bash
29
31
$ cp config.toml.example config.toml # Use example file as basis for your config file
30
32
$ vim config.toml # Adjust config to your setup and needs
31
-
$ make prod # Executes clean, deps, pki and build target
33
+
$ make pki # Creates internally used system of certificates
34
+
$ make deps # Fetch all dependencies
35
+
$ make build # Compile pluto
32
36
$ scp pluto-and-private-bundle <other nodes># Distribute pluto binary to other network nodes
33
37
$ ./pluto -storage # On node 'storage'
34
38
$ ./pluto -worker worker-1 # On node 'worker-1'
@@ -39,21 +43,15 @@ If you know what happens in background, these are the steps to take in order to
39
43
40
44
Now you should be able to access your IMAP server from the Internet under configured IP.
41
45
42
-
These steps conceal the involved processes behind, if you are interested in them, read on.
43
46
44
-
### Detailed Setup
47
+
##User authentication
45
48
46
-
### Configuration
49
+
Currently, two schemes are available to authenticate users though provided `auth` package easily is extensible to fit specific authentication scenarios.
47
50
48
-
You need to configure your pluto setup in a `config.toml` file. Please refer to the provided [config.toml.example](https://github.com/numbleroot/pluto/blob/master/config.toml.example) for an exemplary configuration that only needs adaptation to your requirements.
49
-
50
-
**Important:** Please make sure, not to include `|` (pipe character) in names for your distributor, worker and storage nodes as this character is used in marshalled messages sent on internal network.
51
51
52
-
#### User authentication
52
+
###PostgreSQL
53
53
54
-
##### PostgreSQL
55
-
56
-
If you plan on using a PostgreSQL database for storing the user authorization information, you need to have a PostgreSQL running somewhere. If you need a new user that owns the database, you might use these commands on the PostgreSQL host:
54
+
If you plan on using a PostgreSQL database to provide an user information table, you need to have a PostgreSQL running somewhere. If you need a new user that owns the database, you might use these commands on the PostgreSQL host:
57
55
58
56
```bash
59
57
user@system $ sudo -i -u postgres
@@ -69,13 +67,43 @@ After that, you can create a new database `pluto` to hold the user information l
69
67
user@system $ createdb -U pluto pluto
70
68
```
71
69
72
-
##### File based (for testing purposes)
73
70
74
-
#### Certificates
71
+
### Plain text file
72
+
73
+
If you would like to easily test a configuration or you are developing locally, a plain text file holding user information might suffice. Simply put lines of user names and user passwords delimited by a reserved symbol (e.g. `;`) into a text file and configure your `config.toml` accordingly.
74
+
75
+
An authentication file called `local-dev-users.txt` might look like:
76
+
77
+
```
78
+
username1;secret1
79
+
username2;secret2
80
+
username3;secret3
81
+
...
82
+
```
83
+
84
+
In your `config.toml` you set the distributor node to authenticate users based on this file, for example:
85
+
86
+
```
87
+
[Distributor]
88
+
...
89
+
AuthAdapter = "AuthFile"
90
+
91
+
...
75
92
76
-
There are multiple certificates needed in order to operate a pluto setup. Fortunately, you only have to provide one certificate that is valid for normal use in e.g. webservers. The other required certificates are used for internal communications among pluto's nodes and will be generated by a simple Makefile command.
93
+
[Distributor.AuthFile]
94
+
File = "/path/to/your/setup/local-dev-users.txt"
95
+
Separator = ";"
96
+
...
97
+
```
77
98
78
-
So first, you need to provide a valid public TLS certificate that the distributor node can present to Internet-faced connections. It is recommended that you obtain a certificate signed by a Certificate Authority (CA) that is accepted by most clients by default, e.g. [Let's Encrypt](https://letsencrypt.org/). For testing though, you can use the provided `test-public` target with `make` to generate a self-signed certificate, i.e.:
99
+
**Warning:** Please dot not use this scheme in any places **real** user data is involved. **It is not considered secure.**
100
+
101
+
102
+
## Certificates
103
+
104
+
There are multiple certificates needed in order to operate a pluto setup. Fortunately, you only have to provide one certificate that is valid for normal use in e.g. webservers. The other required certificates are used for internal communication among pluto nodes and will be generated by a simple Makefile command.
105
+
106
+
So first, you need to provide a valid public TLS certificate that the distributor node can present to Internet-faced connections. It is recommended that you obtain a certificate signed by a Certificate Authority (CA) that is accepted by most clients per default, e.g. [Let's Encrypt](https://letsencrypt.org/). For testing though, you can use the provided `test-public` Makefile target and call it to generate a self-signed certificate:
79
107
80
108
```bash
81
109
$ make test-public
@@ -94,9 +122,9 @@ $ go clean
94
122
$ rm -f generate_cert.go
95
123
```
96
124
97
-
Please keep in mind that the certificate generated via this command really only is to be used for testing, never in production mode. It is self-signed for localhost addresses and only of 1024 bits key length which should not be used in production anymore today.
125
+
Please keep in mind that the certificate generated via this command really only is to be used for testing, never in production mode. It is self-signed for localhost addresses and only of 1024 bits key length which should not be used anywhere serious anymore.
98
126
99
-
The remaining required certificates, the mentioned internal ones, can simply be generated by running:
127
+
The remaining required certificates, mentioned internal ones, can simply be generated by running:
100
128
101
129
```bash
102
130
$ make pki
@@ -105,6 +133,8 @@ $ make pki
105
133
106
134
## Acknowledgments
107
135
136
+
I would like to thank my thesis supervisor [Tim Jungnickel](https://github.com/TimJuni) for coming up with this project's idea, providing feedback and ideas on current progress, and evaluation help. Furthermore, [Matthias Loibl](https://github.com/MetalMatze) routinely reviewed Go code I committed to pluto and thus helped to improve code quality and readibility. Thank you!
0 commit comments