This is an automated email from the ASF dual-hosted git repository. chibenwa pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 11fca4f5f758785349c9525cf9e3e1e7e5460391 Author: Benoit TELLIER <[email protected]> AuthorDate: Sun Aug 23 23:54:42 2026 +0700 [DOC] Remove the concept section --- docs/antora.yml | 1 - docs/modules/ROOT/pages/index.adoc | 4 - docs/modules/concepts/nav.adoc | 19 --- docs/modules/concepts/pages/configuration.adoc | 34 ---- docs/modules/concepts/pages/glossary.adoc | 62 ------- docs/modules/concepts/pages/index.adoc | 64 ------- docs/modules/concepts/pages/mail/index.adoc | 15 -- docs/modules/concepts/pages/messages/imf.adoc | 84 ---------- docs/modules/concepts/pages/messages/index.adoc | 14 -- docs/modules/concepts/pages/messages/mime.adoc | 93 ----------- .../modules/concepts/pages/operation/webadmin.adoc | 12 -- docs/modules/concepts/pages/processing/index.adoc | 5 - docs/modules/concepts/pages/protocols/esmtp.adoc | 48 ------ docs/modules/concepts/pages/protocols/imap.adoc | 184 --------------------- docs/modules/concepts/pages/protocols/index.adoc | 17 -- docs/modules/concepts/pages/protocols/jmap.adoc | 29 ---- docs/modules/concepts/pages/protocols/lmtp.adoc | 32 ---- docs/modules/concepts/pages/protocols/pop.adoc | 130 --------------- docs/modules/concepts/pages/protocols/smtp.adoc | 132 --------------- docs/modules/concepts/pages/storage/index.adoc | 40 ----- docs/modules/concepts/pages/storage/mailbox.adoc | 139 ---------------- docs/modules/concepts/pages/storage/users.adoc | 63 ------- docs/modules/concepts/pages/user/index.adoc | 96 ----------- docs/modules/servers/nav.adoc | 1 - docs/modules/servers/pages/basic/concepts.adoc | 14 -- docs/modules/servers/pages/basic/index.adoc | 4 +- docs/modules/servers/pages/index.adoc | 6 +- 27 files changed, 5 insertions(+), 1337 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index 027e85cec5..7e2f1b9fdc 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -3,6 +3,5 @@ title: Apache James Server version: '3.10.0' prerelease: SNAPSHOT nav: -- modules/concepts/nav.adoc - modules/servers/nav.adoc - modules/development/nav.adoc diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 9cbcd103e9..5a8766ebe4 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -8,10 +8,6 @@ James runs on the JVM and is highly customizable. This Reference Book is divided into the following Parts: -* xref:james-project:concepts:index.adoc[James Core Concepts] -** These are the core concepts that describe what James is all about. - Start here if you want to learn more about what James can do - and how it is designed. * xref:james-project:servers:index.adoc[James Servers] ** We provide a few out-of-the-box servers that you can choose from depending on your needs. Start here if you just diff --git a/docs/modules/concepts/nav.adoc b/docs/modules/concepts/nav.adoc deleted file mode 100644 index 997a351b49..0000000000 --- a/docs/modules/concepts/nav.adoc +++ /dev/null @@ -1,19 +0,0 @@ -* xref:index.adoc[] -** xref:user/index.adoc[] -** xref:mail/index.adoc[] -*** xref:messages/index.adoc[] -**** xref:messages/imf.adoc[] -**** xref:messages/mime.adoc[] -** xref:protocols/index.adoc[] -*** xref:protocols/smtp.adoc[] -*** xref:protocols/pop.adoc[] -*** xref:protocols/imap.adoc[] -*** xref:protocols/jmap.adoc[] -*** xref:protocols/esmtp.adoc[] -*** xref:protocols/lmtp.adoc[] -** xref:storage/index.adoc[] -*** xref:storage/mailbox.adoc[] -*** xref:storage/users.adoc[] -** xref:processing/index.adoc[] -** xref:configuration.adoc[] -** xref:glossary.adoc[] diff --git a/docs/modules/concepts/pages/configuration.adoc b/docs/modules/concepts/pages/configuration.adoc deleted file mode 100644 index 3ca6ff1587..0000000000 --- a/docs/modules/concepts/pages/configuration.adoc +++ /dev/null @@ -1,34 +0,0 @@ -= Configuration - -== Overview - -An important aspect to understand about James is the idea of "configuration". -Sometimes "configuration" means different things to different people, so we -wanted to ensure that what we mean by the concept is clear and precise, -because in order operate a James server, you will necessarily need to -configure it. - -A "*Configuration*" is a https://martinfowler.com/bliki/ValueObject.html[value object] -that communicates to a James server how the xref:user/index.adoc#_operator[Operator] wishes the -server to behave. It is very similar to an interface, but yet it is not quite an interface -(which is why we call it something different). - -An "interface" provides a means for an Operator to interact with a server as part of the -normal course of ongoing operations. Interfacing with the system essentially means either -reading the server's current state, or updating the server's current state. A typical example -would be adding a new mailbox via the xref:concepts:operation/webadmin.adoc#_useradmin_api[Useradmin API]. Each time the Operator -interacts with the system via an interface, although the *state* of the system may change, -the *behavior* of the system is not expected to change. - -By contrast, "configuration" of a system (also a noun, but yet not the same as the -"Configuration" we mention above) is more like a switching mechanism that instructs the server -how to behave given some kind of interaction via an interface. For example, if a James server -is configured to allow multiple domains, then if an Operator adds "[email protected]" and -"[email protected]", the server will happily accept the command. If only a single domain is -permitted via configuration, then only one of those mailboxes will be allowed. In other words, -given the same interaction by the Operator, given different configurations the behavior of -the system is different. - -Some systems call these "settings", so as a user of a system you would "configure your settings". - - diff --git a/docs/modules/concepts/pages/glossary.adoc b/docs/modules/concepts/pages/glossary.adoc deleted file mode 100644 index bd25369c6e..0000000000 --- a/docs/modules/concepts/pages/glossary.adoc +++ /dev/null @@ -1,62 +0,0 @@ -= Glossary - -[[email_client]] -Email Client:: -Any software application that acts as a POP Client or an IMAP Client. - -xref:messages/imf.adoc[IMF]:: -*Internet Message Format* (IMF) is the base specification that defines the -syntax of an email message. - -[[email_server]] -Email Server (or Mail Server):: -Any host that contains a software application that acts as a POP Server, an -IMAP Server, or an MTA. - -IMAP:: - -IMAP Client:: -One of the main actors in an email system that implements the IMAP protocol. The client -acts as a slave, in that it mirrors the state of the IMAP Server. - -IMAP Server:: -One of the main actors in an email system that implements the IMAP protocol. The server -acts as the master, in that it dictates the state that will be seen on each of the -IMAP Clients. - -JMAP:: - -xref:messages/mime.adoc[MIME]:: -*Multipurpose Internet Mail Extension* (MIME) is a specification that extends -IMF, defining most of the "advanced" features of email. - -[[mta]] -MTA:: -A *Mail Transfer Agent* (MTA) is a host that is capable of providing a mail -transport service compliant with the SMTP protocol. - -MUA:: -A *Mail User Agent* (MUA) is either an agent that hands over a message to an initial -MTA on the originating side of a transmission, or receives the message from the -final MTA on the terminating side of a transmission. It is in some respects similar to -an MTA, but is local in scope and does not necessarily follow a known specification. - -xref:protocols/smtp.adoc[SMTP]:: -*Simple Mail Transfer Protocol* (SMTP) is a protocol that specifies how to transmit -a valid email message from one MTA to another. - -[[open_relay]] -Open Relay:: - -POP:: - -POP Client:: -One of the main actors in an email system that implements the POP protocol. The client -is on the host that is closest to the user from a logical perspective, and is the host -to which messages are delivered from the POP Server. - -POP Server:: -One of the main actors in an email system that implements the POP protocol. The server -is part of the host that is logically farthest from the user. It is the host on which -the messages are initially delivered, and where they temporarily await collection by -the POP Client. diff --git a/docs/modules/concepts/pages/index.adoc b/docs/modules/concepts/pages/index.adoc deleted file mode 100644 index d2100d52f6..0000000000 --- a/docs/modules/concepts/pages/index.adoc +++ /dev/null @@ -1,64 +0,0 @@ -= Apache James Core Concepts -:navtitle: Concepts - -The core domain of Apache James is intimately related to email communications. -Therefore this section is divided into topics that deal with the various -aspect of email systems. - - * <<emails>> - * <<protocols>> - * <<mailbox>> - * <<processing>> - -[#emails] -== Email Messages - -Electronic Mail (often written as "e-mail" or "email") is a means of -exchanging messages over a data network. In our context, it is obvious -that we mean "electronic mail" and not "postal mail", so we usually just -write "mail". - -xref:mail/index.adoc[Email messages] are based on a few specifications -that are not easy to digest, so we make an effort to provide a simplified -model. - - - - -[#protocols] -== Transmission Protocols - -Emails are only useful because people can communicate with each other. -To allow for this, obviously there must be a means of transmitting messages -from one user to another. A number of different protocols have emerged to -handle the various different requirements of using email in a practical -manner. The most common xref:protocols/index.adoc[transmission protocols] -are SMTP, POP, and IMAP. More recently JMAP is an interesting protocol -that merits attention. - - - - - -[#mailbox] -== Mailbox and Email Storage - -Email would not be very useful if, like in https://www.youtube.com/watch?v=0TiqXFssKMY[Mission Impossible], -a message would self-destruct immediately after being read. -For those of us who are not secret agents, we generally prefer to keep -a record of those messages that we receive. For this reason we need a means -of xref:storage/index.adoc[storing messages]. - - - - - -[#processing] -== Email Processing - -There are many ways to peel a potato. James has its own particular -xref:processing/index.adoc[model for processing mail], -based mostly on the concept of a "Mailet". The idea of Mailet-based -processing was heavily inspired by the https://en.wikipedia.org/wiki/Java_servlet[Servlet] -concept. - diff --git a/docs/modules/concepts/pages/mail/index.adoc b/docs/modules/concepts/pages/mail/index.adoc deleted file mode 100644 index e227e21129..0000000000 --- a/docs/modules/concepts/pages/mail/index.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= All About Emails -:navtitle: Emails - -The https://en.wikipedia.org/wiki/History_of_email[history of email] has resulted -in a convoluted patchwork of standards and practices, which can be very difficult -to understand and decipher. Fortunately, James has your back. - -We have built up our own view of emails that allows us to process messages in a -consistent and comprehensible way. - -To help you understand how James approaches emails, we have divided this section -up into the following parts: - - * xref:messages/index.adoc[] - * xref:protocols/index.adoc[] diff --git a/docs/modules/concepts/pages/messages/imf.adoc b/docs/modules/concepts/pages/messages/imf.adoc deleted file mode 100644 index baf4d5f561..0000000000 --- a/docs/modules/concepts/pages/messages/imf.adoc +++ /dev/null @@ -1,84 +0,0 @@ -= Internet Message Format -:navtitle: IMF - -== Overview - -What people casually call "email" actually refers more specifically to a -text message written in a specified format called -https://en.wikipedia.org/wiki/Email["Internet Message Format"] or "IMF". -After the first IMF specification was published in 1982 there was no looking back. -Email took the world by storm. Today it is arguably the most prevalent means of -communicating with a distant party. - -IMF is very basic, and is limited to only specifying a syntax for text messages. -For the transmission of images, audio, or other types of data we need to make - -use of the xref:concepts:messages/mime.adoc[MIME] specification. -Although IMF forms the base standard upon which -email is based, email today is rarely used without MIME. We therefore consider -for practical purposes that an email message is essentially the equivalent of -a MIME message. - - - -== Specifications - -The specifications for Internet Message Format (IMF) form the basis of what we commonly -call "email". - -=== RFC822 - -https://tools.ietf.org/html/rfc822[RFC822] ("Standard for the Format of ARPA Internet Text Messages") -was the original standard that defined the format of an email. It was obsoleted by -<<RFC2822>>. The definition of an email under this standard was an attempt to take the lessons -learned from the ARPANET and extend the use of text messaging to a broader context. - -Electronic mail messages are defined as having contents and an envelope. The contents -consist of header fields and, optionally, a body. The body is nothing more than -a (potentially empty) sequence of lines of text. - -Although this sounds like an extremely simple concept, to get two completely separate systems -to agree and understand each other is a surprisingly complex problem that most people -today take for granted. Most of <<RFC822>> deals with the nitty-gritty of formatting and parsing -this type of text message. - -This specification deals with the headers, additionally relating them to the sending and -forwarding of messages. The body content is dealt with in xref:concepts:messages/mime.adoc#_rfc2045[RFC2045] - - - -=== RFC2822 - -https://tools.ietf.org/html/rfc2822[RFC2822] ("Internet Message Format") -obsoletes <<RFC822>>, and was obsoleted by <<RFC5322>>. - -The standard builds on RFC822, but limits its scope to only the sytax of the -message, and obsoletes much of what was defined by RFC822. The envelope was -split into a separate specification, xref:concepts:protocols/smtp.adoc#_rfc2821[RFC2821]. - - - - -=== RFC5322 - -https://tools.ietf.org/html/rfc5322[RFC5322] ("Internet Message Format") -was published in 2008. -It obsoletes <<RFC2822>> and is currently the specification still actually in use. - -It builds on RFC2822, updating it to the then-current context and obsoleting -outdated parts of RFC2822. - - - - -== James Model - -While the general description of IMF is not sufficient for building a complex -system like James, the technical specifications are unfortunately -very messy and overly-complex due to their history and the context in which -they were developed. - -Since modern-day messaging almost always requires MIME, and since the -separation between IMF and MIME is not really useful from a usage perspective, -James considers an "email" to be both IMF- an MIME-compliant. For all intents -and purposes, James does not consider the concept of IMF in its domain model. diff --git a/docs/modules/concepts/pages/messages/index.adoc b/docs/modules/concepts/pages/messages/index.adoc deleted file mode 100644 index 9c723d415d..0000000000 --- a/docs/modules/concepts/pages/messages/index.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= Email Messages -:navtitle: Messages - -An email message is essentially a simple text message that is communicated -from one party to another. It is no miracle that two unknown parties are -able to communicate; rather we can thank a set of standards that -allow any two unrelated systems to process an email even if the system owners -do not know each other. - -The two most important standards upon which today's emails are based -are: - - * xref:messages/imf.adoc[Internet Mail Format] (IMF) - * xref:messages/mime.adoc[Multipurpose Internet Mail Extensions] (MIME) diff --git a/docs/modules/concepts/pages/messages/mime.adoc b/docs/modules/concepts/pages/messages/mime.adoc deleted file mode 100644 index 9c97f21f46..0000000000 --- a/docs/modules/concepts/pages/messages/mime.adoc +++ /dev/null @@ -1,93 +0,0 @@ -= Multipurpose Internet Mail Extensions -:navtitle: MIME - -== Overview - -The base format of an email message is xref:messages/imf.adoc[Internet Message Format"], -but most contemporary messages use a format called -https://en.wikipedia.org/wiki/MIME["Multipurpose Internet Mail Extensions"]. -MIME specifies how to extend a valid IMF message, dealing with character encodings, -various file formats, and many other odds and ends that make email what it is today. - -A user of email rarely has to be concerned with the MIME specifications. Usually the -communications system should take care of all the nitty gritty, and even then MIME -processing is usually at a very low level. For this reason, the blissfully simple -conception of a simple "email" is usually just fine from the perspective of a user -and even in most cases for a developer. - - - - -== Specifications - -Multipurpose Internet Mail Extensions, or just MIME, functions much like an extension -to IMF in order to: - - * Add different character sets for internationalization - * Allow for processing of media types other than plain text - -[#_rfc2045] -=== RFC2045 - -https://tools.ietf.org/html/rfc2045[RFC2045] ("Multipurpose Internet Mail Extensions -Part One: Format of Internet Message Bodies") -describes the message body format of an email. It is part of a serious of MIME -specifications including <<RFC2046>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>. -This particular document in the series specifies the various headers that -are used to describe the structure of a MIME message. - - - -=== RFC2046 - -https://tools.ietf.org/html/rfc2046[RFC2046] ("Multipurpose Internet Mail Extensions -Part Two: Media Types") describes the various MIME media types, such as -plain text, images, videos, etc. It is part of the serious of MIME specifications -that includes <<RFC2045>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>. - - - - -=== RFC2047 - -https://tools.ietf.org/html/rfc2047[RFC2047] ("MIME Part Three: -Message Header Extensions for Non-ASCII Text") describes, as the -title indicates, header extensions for non-ASCII text. It is part -of the series of MIME specifications that includes -<<RFC2045>>, <<RFC2046>>, <<RFC2048>>, and <<RFC2049>>. - - - - -=== RFC2048 - -https://tools.ietf.org/html/rfc2048[RFC2048] ("Multipurpose Internet Mail Extensions -Part Four: Registration Procedures") describes the procedure for registering a MIME -type. It is not directly relevant to James, but is part of the MIME series that includes -<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>. - -This specification was obsoleted by https://tools.ietf.org/html/rfc4288[RFC4288] -(which itself was obsoleted by https://tools.ietf.org/html/rfc6838[RFC6838]) and -https://tools.ietf.org/html/rfc4289[RFC4289]. - - - -=== RFC2049 - -https://tools.ietf.org/html/rfc2049[RFC2049] ("Multipurpose Internet Mail Extensions -Part Five: Conformance Criteria and Examples") mainly describes what portions of MIME -must be supported by a conformant MIME implementation. It is part of the series that includes -<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>. - - - -== James Model - -While a general, non-technical description of MIME is useful for most users -and developers, it is not sufficient for building a complex system like James. Meanwhile, -the technical specifications are unfortunately very messy and overly-complex due to -their history and the context in which they were developed. To make dealing with -emails possible and practical, James has defined its own version of what it means -to be an email. - -(TODO need a reference, please!) diff --git a/docs/modules/concepts/pages/operation/webadmin.adoc b/docs/modules/concepts/pages/operation/webadmin.adoc deleted file mode 100644 index 6d84bbf6bc..0000000000 --- a/docs/modules/concepts/pages/operation/webadmin.adoc +++ /dev/null @@ -1,12 +0,0 @@ -= Webadmin api -:navtitle: Web administration API - -The web administration supports for now the CRUD operations on the domains, the users, their mailboxes and their quotas, -managing mail repositories, performing database or storage migrations, and much more. - -This section provides an overview of the most common resources. You can refer to each xref:servers:index.adoc[servers] specific documentation for detailed actionable examples. - -[#_useradmin_api] -== Useradmin API - -(TODO include a general description of the main web admin APIs, ) diff --git a/docs/modules/concepts/pages/processing/index.adoc b/docs/modules/concepts/pages/processing/index.adoc deleted file mode 100644 index 61a0223f2b..0000000000 --- a/docs/modules/concepts/pages/processing/index.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= Mail Processing Domain Model -:navtitle: Processing - -(TODO) - diff --git a/docs/modules/concepts/pages/protocols/esmtp.adoc b/docs/modules/concepts/pages/protocols/esmtp.adoc deleted file mode 100644 index 893f92c36e..0000000000 --- a/docs/modules/concepts/pages/protocols/esmtp.adoc +++ /dev/null @@ -1,48 +0,0 @@ -= SMTP Service Extensions (ESMTP) -:navtitle: ESMTP - -== Overview - -https://en.wikipedia.org/wiki/Extended_SMTP[SMTP Service Extensions], written as "ESMTP" -and characterized in the literature as "Extended SMTP" (and sometimes "Enhanced SMTP") -is a framework for extending SMTP. Extensions are expected to be registered with -IANA and negotiated between the client and server. - -Whereas SMTP mandates that a session begins with the "HELO" command, ESMTP requires -the "EHLO" (extended hello) command. Note that nowadays even "standard" SMTP uses -EHLO as its initial greeting, and only falls back to HELO, so in a sense every -SMTP server has effectively become an ESMTP server. - -The ESMTP specification itself no longer actually exists independently of SMTP. -We mention it here mostly for completion, historical purposes, and as a reference -to a concept that is still very much in use, albeit now as a concept internal to -SMTP. - - -== Specifications - -=== RFC1425 - -https://tools.ietf.org/html/rfc1425[RFC1425] ("SMTP Service Extensions") is the originally -published ESMTP specification. It was obsoleted by <<RFC1651>>. - - -=== RFC1651 - -https://tools.ietf.org/html/rfc1651[RFC1651] ("SMTP Service Extensions") obsoletes <<RFC1425>> -and was itself obsoleted by <<RFC1869>>. - - -=== RFC1869 - -https://tools.ietf.org/html/rfc1869[RFC1869] ("SMTP Service Extensions") obsoletes <<RFC1651>>, and -is essentially the final specification in which ESMTP was defined separately from SMTP. When this -spec was obsoleted by xref:protocols/smtp.adoc#_rfc2821[RFC2821], it was incorporated into the -SMTP specification. - - -== Related Concepts - - * *xref:protocols/smtp.adoc[SMTP]*, because ESMTP defines an extension framework for SMTP - * *xref:protocols/lmtp.adoc[LMTP]*, as LMTP is defined by the ESMTP framework - diff --git a/docs/modules/concepts/pages/protocols/imap.adoc b/docs/modules/concepts/pages/protocols/imap.adoc deleted file mode 100644 index 9d8251f27c..0000000000 --- a/docs/modules/concepts/pages/protocols/imap.adoc +++ /dev/null @@ -1,184 +0,0 @@ -= Internet Message Access Protocol (IMAP) -:navtitle: IMAP - -== Overview - -https://en.wikipedia.org/wiki/Internet_Message_Access_Protocol[Internet Message Access Protocol], -or IMAP, is a protocol used by email clients to retrieve -xref:messages/index.adoc[email messages] from a xref:glossary.adoc#email_server[mail server]. -One could say that it is effectively in competition with xref:protocols/pop.adoc[POP] -because it accomplishes a function similar in nature, and most clients will force you -to choose one or the other. -These days, the natural choice of protocol tends to be IMAP rather than POP. - -The main difference between IMAP and POP is that messages are kept on the server, which -keeps a kind of master reference. Instead of transferring the message to the client, -only an image, or copy of the message is kept locally. When the client synchronises with -the state of the server, it will tend to mimic that state. So if a new message is stored -in a mailbox, it will appear on the client, or if a message is deleted from the server, -it will also be deleted from the client. - -The user can control the state of server from the client by adding, deleting, or moving -messages between folders. The user can also add folders from the client, the state of which -will be stored on the server. - - -== Specifications - -=== IMAP - -Apparently, no official specification exists for the original IMAP. -It became a specification with the publication of <<IMAP2>> - - -=== IMAP2 - -==== RFC1064 - -https://tools.ietf.org/html/rfc1064[RFC1064] ("Interactive Mail Access Protocol - Version 2") -was the original IMAP2 specification, published in 1988. The specification was obsoleted -by <<RFC1176>>. - -==== RFC1176 - -https://tools.ietf.org/html/rfc1176[RFC1176] ("Interactive Mail Access Protocol - Version 2") -provides various, somewhat minor updates to <<RFC1064>>. This specification was superseded by -the first IMAP3 specification, <<RFC1203>>. - -=== IMAP3 - -==== RFC1203 - -https://tools.ietf.org/html/rfc1203[RFC1203] ("Interactive Mail Access Protocol - Version 3") -obsoletes <<RFC1064>>, and presumably also <<RFC1176>>. -It appears to be the only version of IMAP3 that was published. Apparently, IMAP3 is a rare -version, and was never really adopted by the marketplace. - - -=== IMAP4 - -==== RFC1730 -https://tools.ietf.org/html/rfc1730[RFC1730] ("Interactive Message Access Protocol - Version 4") -was the first version of IMAP4, published in 1994. Note that the "M" in the name was changed -from "Mail" to "Message". -It was obsoleted two years later by <<RFC2060>>. - - -==== RFC2060 - -https://tools.ietf.org/html/rfc2060[RFC2060] ("Interactive Message Access Protocol - Version 4rev1") -was the first revision of the original IMAP4 specification. It was obsoleted by <<RFC3501>>. - - -==== RFC3501 - -https://tools.ietf.org/html/rfc3501[RFC3501] ("Interactive Message Access Protocol - Version 4rev1") -is the current IMAP4 standard in use. Though the name is confusing, is was the second revision since -the publication of the original IMAP4 specification. This version was published in 2003. Likely, -there has not been a need to update this specification as instead updates are published as extensions. -Extensions to IMAP have been published as recently as in 2018. - -==== Extensions to RFC3501 - -For brevity, we simply reference a number of extensions to RFC3501: - - * https://tools.ietf.org/html/rfc4466[RFC4466] ("Collected Extensions to IMAP4 ABNF") - * https://tools.ietf.org/html/rfc4469[RFC4469] ("Internet Message Access Protocol (IMAP) CATENATE Extension") - * https://tools.ietf.org/html/rfc4551[RFC4551] ("IMAP Extension for Conditional STORE Operation or Quick Flag Changes Resynchronization") - * https://tools.ietf.org/html/rfc5032[RFC5032] ("WITHIN Search Extension to the IMAP Protocol") - * https://tools.ietf.org/html/rfc5182[RFC5182] ("IMAP Extension for Referencing the Last SEARCH Result") - * https://tools.ietf.org/html/rfc5738[RFC5738] ("IMAP Support for UTF-8") - * https://tools.ietf.org/html/rfc6186[RFC6186] ("Use of SRV Records for Locating Email Submission/Access Services") - * https://tools.ietf.org/html/rfc6858[RFC6858] ("Simplified POP and IMAP Downgrading for Internationalized Email") - * https://tools.ietf.org/html/rfc7817[RFC7817] ("Updated Transport Layer Security (TLS) Server Identity Check Procedure for Email-Related Protocols") - * https://tools.ietf.org/html/rfc8314[RFC8314] ("Cleartext Considered Obsolete: Use of Transport Layer Security (TLS) for Email Submission and Access") - * https://tools.ietf.org/html/rfc8437[RFC8437] ("IMAP UNAUTHENTICATE Extension for Connection Reuse") - * https://tools.ietf.org/html/rfc8474[RFC8474] ("IMAP Extension for Object Identifiers") - - - -== Related Concepts - -IMAP is related to... - - * *xref:protocols/pop.adoc[POP]* as a "competing" protocol - * *xref:glossary.adoc#email_client[Email clients]*, as the client will provide the functionality of - an IMAP Client and connect to the IMAP Server - * *xref:protocols/smtp.adoc[SMTP]*, in that messages will normally be - delivered to the IMAP Server via SMTP. - - - -== Try It! - -You can connect manually to James using the IMAP protocol by opening a -openssl session. - -Requirements: - - * Run the long demo (without stopping) - * openssl s_client - -Approximate duration: 5 minutes - -==== -Note: extra lines are inserted below to help show you what you need to type. -==== - -[source,telnet] ----- -$ openssl s_client -connect 127.0.0.1:993 -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. -* OK JAMES IMAP4rev1 Server Server faef5a990fbb is ready. - -01 login [email protected] 1234 <1> - -01 OK LOGIN completed. - -l list "" "*" <2> - -* LIST (\HasNoChildren) "." "INBOX" -l OK LIST completed. - -s select INBOX <3> - -* FLAGS (\Answered \Deleted \Draft \Flagged \Seen) -* 1 EXISTS -* 1 RECENT -* OK [UIDVALIDITY 749313882] UIDs valid -* OK [UNSEEN 1] MailboxMessage 2 is first unseen -* OK [PERMANENTFLAGS (\Answered \Deleted \Draft \Flagged \Seen \*)] Limited -* OK [HIGHESTMODSEQ 5] Highest -* OK [UIDNEXT 2] Predicted next UID -s OK [READ-WRITE] SELECT completed. - -f FETCH 1:* (FLAGS BODY.PEEK[HEADER.FIELDS (SUBJECT)]) <4> - -* 1 FETCH (FLAGS (\Seen) BODY[HEADER.FIELDS (SUBJECT)] {75} -Subject: Test Message - -) -f OK FETCH completed. - -d store 1 +FLAGS (\Deleted) <5> - -* 1 FETCH (FLAGS (\Deleted \Seen)) -d OK STORE completed. - -e expunge <6> - -* 1 EXPUNGE -e OK EXPUNGE completed. - -l logout <7> ----- -<1> Login as user `[email protected]` -<2> List the contents of the Mailbox -<3> Select `INBOX` as the current folder -<4> Fetch the contents of the INBOX folder, showing only the subject -<5> Mark the message for deletion -<6> Expunge the INBOX by deleting mails marked for deletion -<7> Exit the session - diff --git a/docs/modules/concepts/pages/protocols/index.adoc b/docs/modules/concepts/pages/protocols/index.adoc deleted file mode 100644 index 26910837a5..0000000000 --- a/docs/modules/concepts/pages/protocols/index.adoc +++ /dev/null @@ -1,17 +0,0 @@ -= Transmission Protocols -:navtitle: Protocols - -The true value of email is that any one party can communicate with any -other party located virtually anywhere. All they need are a common understanding -of a xref:messages/index.adoc[message format], and a means of -transmitting the message. - -Transmitting email messages between parties requires a mutually-known protocol. -It turns out that there are several standard protocols used for the -transmission of email messages, each with a different purpose: - - ** xref:protocols/smtp.adoc[Simple Mail Transfer] - ** xref:protocols/pop.adoc[Post Office] - ** xref:protocols/imap.adoc[Internet Message Access] - ** xref:protocols/jmap.adoc[JSON Meta Application] - ** xref:protocols/lmtp.adoc[Local Mail Transfer] diff --git a/docs/modules/concepts/pages/protocols/jmap.adoc b/docs/modules/concepts/pages/protocols/jmap.adoc deleted file mode 100644 index a64d3a2f31..0000000000 --- a/docs/modules/concepts/pages/protocols/jmap.adoc +++ /dev/null @@ -1,29 +0,0 @@ -= JSON Meta Application Protocol (JMAP) -:navtitle: JMAP - -== Overview - -https://jmap.io/[JSON Meta Application Protocol] ("JMAP") -is - -From <<RFC8620>>: - - The JSON Meta Application Protocol (JMAP) is used for synchronising - data, such as mail, calendars, or contacts, between a client and a - server. It is optimised for mobile and web environments and aims to - provide a consistent interface to different data types. - - This specification is for the generic mechanism of data - synchronisation. Further specifications define the data models for - different data types that may be synchronised via JMAP. - - -== Specifications - -=== RFC8620 - -https://tools.ietf.org/html/rfc8620[RFC8620] ("The JSON Meta Application Protocol (JMAP)") - -== Related Concepts - - diff --git a/docs/modules/concepts/pages/protocols/lmtp.adoc b/docs/modules/concepts/pages/protocols/lmtp.adoc deleted file mode 100644 index 493b49e916..0000000000 --- a/docs/modules/concepts/pages/protocols/lmtp.adoc +++ /dev/null @@ -1,32 +0,0 @@ -= Local Mail Transfer Protocol (LMTP) -:navtitle: LMTP - -== Overview - -https://en.wikipedia.org/wiki/Local_Mail_Transfer_Protocol[Local Mail Transfer Protocol] ("LMTP") -is - -From <<RFC2033>>: - - Although LMTP is an alternative protocol to ESMTP, it uses (with a - few changes) the syntax and semantics of ESMTP. This design permits - LMTP to utilize the extensions defined for ESMTP. LMTP should be - used only by specific prior arrangement and configuration, and it - MUST NOT be used on TCP port 25. - - -== Specifications - -=== RFC2033 - -https://tools.ietf.org/html/rfc2033[RFC2033] ("Local Mail Transfer Protocol") was published -in 1996, and defines a simplified protocol for local mail delivery mainly inspired by -xref:protocols/esmtp.adoc[ESMTP]. It is the first, last, and only specification of its kind. - - -== Related Concepts - -LMTP relates to: - - * *xref:protocols/esmtp.adoc[ESMTP]*, as it is a derivative thereof - diff --git a/docs/modules/concepts/pages/protocols/pop.adoc b/docs/modules/concepts/pages/protocols/pop.adoc deleted file mode 100644 index 61fec57b4c..0000000000 --- a/docs/modules/concepts/pages/protocols/pop.adoc +++ /dev/null @@ -1,130 +0,0 @@ -= Post Office Protocol (POP) -:navtitle: POP - -== Overview - -The https://en.wikipedia.org/wiki/Post_Office_Protocol[Post Office Protocol], -or POP, is described in the original specification -as being "a simple method for workstations to dynamically access mail from -a xref:storage/index.adoc[mailbox server]" (though interestingly "mailbox server" -is never actually defined in this specification nor in later specifications. 🤔) - -POP was proposed as the first non-xref:protocols/smtp.adoc[SMTP] protocol aimed -at users for the purpose of retrieving emails stored remotely for local consumption. -POP was developed in pre-spam days, so was inherently a non-secure protocol. -It has been updated several times to address several issues, including lack of -security, so that POP3 is now the current specification. - -As the name suggests, the protocol is modeled after a post office. The analogy being: - - * The various SMTP servers along the transmission chain are like post offices - * The user's mail server is the local post office that will dispatch the mail to the recipient - * The postman is, ummm, well no analogy is perfect 😬 - * The mail gets dropped into the user's mailbox (though just to make the analogy even - muddier there is an option to leave a copy on the server) - -Analogies aside, the protocol worked quite well for most users, and is still widely -in use today. - -POP requires essentially two pieces, the POP Client and the POP Server. How the -message gets initially delivered to the POP Server and how a message is managed -once delivered to the POP Client is out of scope of the POP protocol. - - -== Specifications - -=== POP - -POP has been around since the early days of email. The original specification -<<RFC918>> was published in 1984. - - -==== RFC918 - -https://tools.ietf.org/html/rfc918[RFC918] ("Post Office Protocol") was the original -specification published in 1984. The RFC "suggests a simple method for workstations -to dynamically access mail from a mailbox server." -Like xref:protocols/smtp.adoc[SMTP] that came before it, POP is a session-based -protocol with a handful of defined commands. -This RFC was obsoleted shortly after its publication by <<RFC937>>. - - - - -=== POP2 - -==== RFC937 - -https://tools.ietf.org/html/rfc937[RFC937] ("Post Office Protocol - Version 2") or more -commonly "POP2" was a revision of the original <<RFC918>> specification. POP2 specifies -connection over port 109, and clarifies that "it is important for the mailbox to be on -an 'always up' machine and that a workstation may be frequently powered down, or -otherwise unavailable as an SMTP server." In other words, as the Internet continued to -evolve, this specification was an attempt to evolve with it. - -POP2 was replaced by POP3, which was first published as <<RFC1081>>. - - - -=== POP3 - -==== RFC1081 - -https://tools.ietf.org/html/rfc1081[RFC1081] ("Post Office Protocol - Version 3") -was the first published version of POP3, -made available in 1988. It adds additional functionality for managing mail, and -perhaps most importantly, it adds an authentication mechanism. This version was -obsoleted by <<RFC1225>>. - - -==== RFC1225 - -https://tools.ietf.org/html/rfc1225[RFC1225] ("Post Office Protocol - Version 3") -obsoleted <<RFC1081>>. It is described as being a "republication" of <<RFC1081>>, -and does not appear to add anything significant. It was obsoleted by -<<RFC1460>>. - - -==== RFC1460 - -https://tools.ietf.org/html/rfc1460[RFC1460] ("Post Office Protocol - Version 3") -provided some relatively minor updates to <<RFC1225>>, and was itself obsoleted -about one year later by <<RFC1725>>. - - -==== RFC1725 - -https://tools.ietf.org/html/rfc1725[RFC1725] ("Post Office Protocol - Version 3") -was again a relatively minor update of <<RFC1460>>, and was itself obsoleted -about two years later by <<RFC1939>>. - - -==== RFC1939 - -https://tools.ietf.org/html/rfc1939[RFC1939] ("Post Office Protocol - Version 3") -is the most recent specification of POP3, and is the version in use today. - -This specification seems to imply that POP3 is used for "simple" transactions, -and for more "advanced" transactions xref:protocols/imap.adoc[IMAP] is available. - - - -=== POP4 - -Although there was development on the http://www.pop4.org/[POP4] specification, -development appears to have stalled for several years, making POP3 the -still-current protocol. - - - -== Related Concepts - -POP relates to... - - * *xref:protocols/imap.adoc[IMAP]* as a "competing" protocol - * *xref:glossary.adoc#email_client[Email clients]*, in that the client acts as a POP Client - * *xref:storage/index.adoc[Storage]* in that messages are stored temporarily on - a ???? while awaiting transfer to the client - * *xref:protocols/smtp.adoc[SMTP]*, in that messages will normally be - delivered to the IMAP Server via SMTP. - diff --git a/docs/modules/concepts/pages/protocols/smtp.adoc b/docs/modules/concepts/pages/protocols/smtp.adoc deleted file mode 100644 index 311ae2ba39..0000000000 --- a/docs/modules/concepts/pages/protocols/smtp.adoc +++ /dev/null @@ -1,132 +0,0 @@ -= Simple Mail Transfer Protocol (SMTP) -:navtitle: SMTP - -== Overview - -When the original specification for Simple Mail Transfer Protocol, or SMTP, -was published almost 40 years ago together with -xref:messages/imf.adoc[IMF], email as we know it today was born. - - - -== Specifications - -=== RFC821 - -https://tools.ietf.org/html/rfc821[RFC821] ("Simple Mail Transfer Protocol") -was the original SMTP specification published in 1982. -It was obsoleted by <<RFC2821>> in 2001. - -[#_rfc2821] -=== RFC2821 - -https://tools.ietf.org/html/rfc2821[RFC2821] ("Simple Mail Transfer Protocol") replaced -<<RFC821>>. It was itself replaced by <<RFC5321>> in 2008. - -=== RFC5321 - -https://tools.ietf.org/html/rfc5321[RFC5321] is the currently used standard for -"Simple Mail Transfer Protocol", or "SMTP". Published in 2008, it is "a specification of the basic -protocol for Internet electronic mail transport". If you are interested in all -the gory details, we recommend that you read this document. - -This specification has many dependencies with xref:messages/imf.adoc[IMF], -xref:messages/mime.adoc[MIME], and other technical concepts, which can quickly -become utterly confusing. -Here, we provide a very short and simplified description of those portions of the -specification that we felt were interesting enough to repeat here. - -As the spec mentions, "SMTP transports a mail object", a mail object being described -as an object that contains both an envelope and content. An SMTP client connects -to a server and communicates via a session. Both client and server provide a -mail transport service, and are therefore act as "Mail Transfer Agents", or -"MTAs". A mail originates and terminates with a "Mail User Agent" ("MUA"). -On the originating side, a MUA may, for instance, collect mail to be transmitted -by a user and hand it off to an MTA. On the terminating side, an MTA would -hand a mail off to an MUA. - -"SMTP sessions are stateful, with both parties carefully maintaining a -common view of the current state." The session is initiated by the client, -which establishes a two-way channel to an SMTP server. The session must either -close successful (or with a failure message), else delivery is considered to -have failed. - - - -== Related Concepts - -SMTP relates to: - - * *xref:messages/index.adoc[Email messages]*, in that the SMTP protocol exists to transfer - messages from one host to another - * *xref:glossary.adoc#mta[MTA]*, in that the very nature of SMTP is about specifying how a message - gets transferred from one MTA to another - - - -== Try It! - -You can try speaking SMTP with your demo server by connecting to it using telnet. It would not work on a real world server as it would requires encrypted traffic. See "using openssl to talk to your server" - -Requirements: - - * Run the long demo (without stopping) - * Telnet - -Approximate duration: 5 minutes - -==== -Note: extra lines are inserted below to help show you what you need to type. -==== - -[source,telnet] ----- -$ telnet 127.0.0.1 25 <1> - -Trying 127.0.0.1... -Connected to localhost. -Escape character is '^]'. -220 JAMES Linagora's SMTP awesome Server - -ehlo test <2> - -250-9a2fe463e592 Hello test [172.17.0.1]) -250-PIPELINING -250-ENHANCEDSTATUSCODES -250 8BITMIME - -mail from: <[email protected]> <3> - -250 2.1.0 Sender <[email protected]> OK - -rcpt to: <[email protected]> <4> - -250 2.1.5 Recipient <[email protected]> OK - -data <5> - -354 Ok Send data ending with <CRLF>.<CRLF> - -Subject: Test Message <5> -<6> -This is just a test. <7> -. <8> - -250 2.6.0 Message received - -quit <9> ----- -<1> Connect to the James server using the SMTP protocol via telnet. -<2> Initiate the SMTP session. -<3> Indicate that you want to send a mail from [email protected]. -<4> Indicate that the mail should be sent to [email protected]. -<5> Enter the subject. -<6> Enter a blank line. -<7> Enter some text. You can enter multiples lines if you like. -<8> When you have completed the message, enter a line with only a "." and no other text. -<9> End the session. - -If you set up Thunderbird to connect to the server, you can confirm that the mail -has indeed arrived in the mailbox of [email protected]. - -Pretty cool! Good thing we have James so we don't have to always send emails manually. diff --git a/docs/modules/concepts/pages/storage/index.adoc b/docs/modules/concepts/pages/storage/index.adoc deleted file mode 100644 index f6fcb56340..0000000000 --- a/docs/modules/concepts/pages/storage/index.adoc +++ /dev/null @@ -1,40 +0,0 @@ -= Storage -:navtitle: Storage - -== Overview - -Email is useful because any one person can send a message to any other person, -anywhere in the world. The heart of email is the ability to transfer some message -based on a commonly-understood message format between two different systems that -may have been developed entirely independently of each other. The concept is relatively -simple, but the fact that email is so ubiquitous is simply a miracle. - -However, there is more to email than just the transfer of messages. - -For starters, I want people I know to be able to send me a mail even when -I happen to be out mountain climbing. I want to be able to receive the message -when I'm not available, then review it afterward when I am back at my desk. -For this reason, email is by design asynchronous. Time can pass between the moment -a mail is sent and the moment it is read. -In the meantime, it needs to be stored somewhere. - - -Additionally, although it is possible to read a message, then discard it, never to be seen again, -it is more common for people to archive a message. Some people even get creative and -use their email for various other purposes, such as a kind of poor man's information archive. -Many corporations use email for business purposes, which requires administration of -users within the organization. -Even individuals with a self-hosted email server want to ensure that their system does -not get abused as an xref:concepts:glossary.adoc#open_relay[open relay]. - -All of these types of concerns requires that the system maintain some kind of state, -whether that be the messages themselves, information about the system's users, -and even in some cases user credentials. Keeping state requires a storage system. -The system of storage must work intimately with the various -xref:protocols/index.adoc[protocols]. - -In this section, we describe the two principle types of storage that James manages: - - * xref:storage/mailbox.adoc[Mailboxes] for email storage, and -// "Repository" should be "Directory". See JAMES-3360. - * xref:storage/users.adoc[User Repository] for data about Mailbox users. diff --git a/docs/modules/concepts/pages/storage/mailbox.adoc b/docs/modules/concepts/pages/storage/mailbox.adoc deleted file mode 100644 index 473806e106..0000000000 --- a/docs/modules/concepts/pages/storage/mailbox.adoc +++ /dev/null @@ -1,139 +0,0 @@ -= Mailboxes -:navtitle: Mailboxes - -== Overview - -To (over)use the analogy once again of a postal system, we think of a mailbox -as a place where a letter is placed to await pickup by its recipient. Although -current methods have evolved considerably, the original idea used for the development -of email was exactly that. The concept <<RFC196,has been around officially>> since -at least 1971. The image of a mailbox is so prevalent that, although current -systems have evolved to do so much more than just hold messages for processing, -the industry continues to apply the concept. - -The more general term is "Email Storage". It is necessary to store email for -many reasons: - - * As a mailbox system — part of a queue to await processing - * As a persistence mechanism — a place where you can go back and predictably - locate a message that you may want to refer to again in the future - * As an archive — a place where you may want to store "deleted" emails so that - you can potentially retrieve them if you wish to change your mind later - * As a temporary step in a process — perhaps you have a "todo" folder where - you temporarily store an email that you intend to process soon - -There are numerous ways to store emails, just as there are numerous reasons for -storing them: - - * A <<Specifications,standardized>> "mailbox" format - * A relational database - * A custom file-based mechanism - * Etc. - -This section briefly describes how email storage is a core concept in an -email system. - - - -== Specifications - -=== Electronic Mail Box - -==== RFC196 - -The concept of an "electronic mail box" was -https://tools.ietf.org/html/rfc196[initially specified] way back in 1971. -It is amusing to read the retro concepts in the initial description of this -document: - - The purpose of this protocol is to provide at each site a - standard mechanism to receive sequential files for immediate or - deferred printing or other uses. The files for deferred printing - would probably be stored on intermediate disk files [...]. - It is also assumed that there would be a program at the sending - site [...]. This program could probably be accessed as a subcommand - of the Telnet program. - -This specification was obsoleted by <<RFC221>>. - - -==== RFC221 - -https://tools.ietf.org/html/rfc221[RFC221] ("A Mail Box Protocol, Version-2") was -published in 1971. It added the possibility of using FTP in addition to the -"Data Transfer Protocol" used in <<RFC196>>. This version was obsoleted by -<<RFC278>>. - - - -==== RFC278 - -https://tools.ietf.org/html/rfc278[RFC278] ("Revision of the Mail Box Protocol") -was published in 1971. It provided a number of updates to <<RFC221>>. - - - -=== Maildir - -https://en.wikipedia.org/wiki/Maildir[Maildir] is a file-based storage format invented -by https://en.wikipedia.org/wiki/Daniel_J._Bernstein[Dan Bernstein]. -A major design objective was apparently to delegate file locking to the operating system. - - - -=== Mbox - -The https://en.wikipedia.org/wiki/Mbox[mbox] email storage format was formally defined -by https://tools.ietf.org/html/rfc4155[RFC4155]. It is a formalization of a _de facto_ -format used by UNIX-like operating systems. - - - -=== MIX - -The https://en.wikipedia.org/wiki/MIX_(email)[MIX] email storage format was developed by -https://en.wikipedia.org/wiki/Mark_Crispin[Mark Crispin], the original author of the -xref:protocols/imap.adoc[IMAP specification]. Its -https://www.mail-archive.com/[email protected]/msg00540.html[design goals] were: - -* greater robustness against corruption caused by hardware or - software failures. Many failures are "self-healing". -* far fewer risky random-access I/O operations; a single false - pointer calculation in other formats will corrupt the mailbox. -* greater ease to repair damaged mailboxes. -* (much) greater performance. -* extensibility for new IMAP capabilities such as annotations, - conditional store, or more aggressing caching. - - -=== RFC5322 - -https://tools.ietf.org/html/rfc5322[RFC5322] weighs in on how to describe a "mailbox": - - A mailbox receives mail. It is a 'conceptual entity' that does not necessarily - pertain to file storage. It further exemplifies that some sites may choose to - print mail on a printer and deliver the output to the addressee's desk, much - like a traditional fax transmission. - - -== Indexing - -// "Repository" should be "Directory". See JAMES-3360. -Once a system grows over time it will likely contain many messages -stored in its xref:storage/mailbox.adoc[Mailboxes]. -Searching for the right email becomes increasingly difficult. At some point -it becomes useful to use an https://en.wikipedia.org/wiki/Search_engine_indexing[indexing] - - -== Related Concepts - -Email Storage is related to... - - * *xref:protocols/pop.adoc[POP]*, as the POP protocol mandates interaction - with a user's "mailbox" - * *xref:protocols/imap.adoc[IMAP]*, as the IMAP protocol is all about storing - messages on an IMAP Server - * *xref:glossary.adoc#email_client[Email clients]*, as the client will store mail locally, usually in the form - of a "mailbox" - * *xref:protocols/smtp.adoc[SMTP]* as the protocol is related to transmitting - messages from one mailbox to another diff --git a/docs/modules/concepts/pages/storage/users.adoc b/docs/modules/concepts/pages/storage/users.adoc deleted file mode 100644 index ab7937dc72..0000000000 --- a/docs/modules/concepts/pages/storage/users.adoc +++ /dev/null @@ -1,63 +0,0 @@ -= User Repository -:navtitle: Users - -== Overview - -Whereas xref:storage/mailbox.adoc[mailboxes] are clearly a core component of -any email system, user management is a lighter shade of gray. - -// "Repository" should be "Directory". See JAMES-3360. -On the one hand, mailboxes ought to match up with actual -xref:user/index.adoc#_user[Users], so there is -a clear relationship between mailbox management and user management. -Because of this relationship, it is not at all strange to include a user respository -within an email system. - -However, on the other hand email is only one of many applications that require -user management. It is therefore also completely reasonable to use some kind of -centralized user directory, and ensure that mailboxes somehow synchronize with -this external system. - -The former case is much simpler to manage, but requires duplicate and therefore -unproductive work. The latter case can become quite complex from a technological -perspective (and all the risks that are associated with it), but reduces the -amount of unproductive work. - -== Common Operations - -// "Repository" should be "Directory". See JAMES-3360. -Because the user repository is used in the context of managing mailboxes, there -are some operations that are relatively common to any email system. - -=== Domain Management - -A mailbox belongs to a https://en.wikipedia.org/wiki/Domain_name[domain]. For a mail -system that can process multiple domains, the system will usually have operations to: - -* List available domains -* Add a domain -* Remove a domain -* Update a user's password - - -=== User Management - -A User has at least one mail box, and will usually have a canonical mailbox -that matches the user's identity in the system. -For each domain that is managed by the system, it is common to be able to: - -* List all users for the domain -* Add a user -* Remove user - - -=== Other Common Operations - -* Add or remove email https://en.wikipedia.org/wiki/Email_alias[aliases] -for a given user -* Add or remove email https://en.wikipedia.org/wiki/Email_forwarding[forwards] -for a given user -* Add or remove a user to a "group" mail address -* Filter messages using https://james.apache.org/jsieve/[Sieve] -* Rewrite mail addresses -* Configure an https://en.wikipedia.org/wiki/Autoresponder[autoresponder] diff --git a/docs/modules/concepts/pages/user/index.adoc b/docs/modules/concepts/pages/user/index.adoc deleted file mode 100644 index 26521682f5..0000000000 --- a/docs/modules/concepts/pages/user/index.adoc +++ /dev/null @@ -1,96 +0,0 @@ -= James User Model -:navtitle: User Model - - -For clarity, we have defined various roles for actors who interact -with xref:servers:index.adoc[James servers] in one way or another. -The deliverables we make available are produced with these roles in mind. -Note that any given person may play more than one role, even at the same -time. - - * <<User>> - * <<Operator>> - * <<Integrator>> - * <<Developer>> - * <<Contributor>> - * <<Committer>> - * <<PMC Member>> - -== User - -A **User** simply uses email without any notion of what server is providing the service. - -More precisely, in typical cases a User will have an email client for reading and writing email. The -xref:glossary.adoc[email client] will connect to the James server via -xref:protocols/smtp.adoc[SMTP], -xref:protocols/pop.adoc[POP], or -xref:protocols/imap.adoc[IMAP]. -The User will have no indication anywhere that the server is a James server. - - -[#_operator] -== Operator - -An **Operator** installs and runs James for the benefit of Users. - -The Operator does not compile any Java code, and does not require any software -development environment. - -Apache James offers Operators a range of servers for various use cases, including: - - * A xref:servers:basic/index.adoc[Basic Server] ideal for busy Operators who - are interested in an easy-to-use self-hosting solution, but who may not have the - time to gain deep expertise - * A xref:servers:distributed/index.adoc[Distributed Server] well-suited for Operators with - advanced skills and resources who are not daunted by getting their hands dirty - with configurations or using built-in extensions - - - -== Integrator - -An **Integrator** has some expertise with Java or a JVM-based language. Based -on this expertise the Integrator can perform more advanced server configurations and may -develop extensions to customize the behavior of a xref:servers:index.adoc[James server]. - -An Integrator does **not** need to download the source code or compile James. - - - -== Developer - -A **Developer** uses the James codebase, executes a build using the provided -build system (Maven), may edit the source code and deploy the built artifacts. - - - -== Contributor - -A **Contributor** refers to anyone involved with the Apache James community by: - - * Filing an issue on the https://issues.apache.org/jira/secure/Dashboard.jspa[issue tracking system] - * Posting a question on the https://james.apache.org/mail.html[mailing list] - or on the https://gitter.im/apache/james-project[gitter channel] - * Submitting a https://github.com/apache/james-project/pulls[pull request] (PR) - * Fixes, refines and writes documentation - * Writes a tutorial or article about James - * Otherwise generally helps the James Community in any other way not listed here - - - -== Committer - -A **Committer** is granted special rights (according to -https://www.apache.org/dev/committers.html[Apache practices]) -to participate in the development of James by: - - * Accepting (being assigned) issues in the https://issues.apache.org/jira/secure/Dashboard.jspa[issue tracking system] - * Merging code into the https://github.com/apache/james-project[git repository] - * Being granted a voice when voting matters arise - - -== PMC Member - -A **PMC** (Project Management Committee) Member -is a Committer who is also a member of the PMC, as stipulated by -https://www.apache.org/dev/pmc.html[Apache rules]. diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 3acbcca2ad..58e95fe22c 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -5,7 +5,6 @@ ** xref:basic/index.adoc[] *** xref:basic/context.adoc[] *** xref:basic/objectives.adoc[] -*** xref:basic/concepts.adoc[] *** xref:basic/architecture.adoc[] *** xref:basic/configure/index.adoc[] *** xref:basic/help.adoc[] diff --git a/docs/modules/servers/pages/basic/concepts.adoc b/docs/modules/servers/pages/basic/concepts.adoc deleted file mode 100644 index e68c0c1290..0000000000 --- a/docs/modules/servers/pages/basic/concepts.adoc +++ /dev/null @@ -1,14 +0,0 @@ -= James Basic Server — Background Concepts -:navtitle: Concepts - -Before embarking on your adventure with the **James Basic Server**, we -highly recommend that you familiarize yourself with the following concepts: - -[TODO: provide links and ensure that articles exist for each of these topics] - - * xref:concepts:user/index.adoc[James User Model] - * xref:concepts:protocols/smtp.adoc[SMTP] - * xref:concepts:protocols/imap.adoc[IMAP] -// What link should go here?? - * Secured email communications - * xref:concepts:/storage/index.adoc[Email storage] diff --git a/docs/modules/servers/pages/basic/index.adoc b/docs/modules/servers/pages/basic/index.adoc index d12c0b1010..a252b2018d 100644 --- a/docs/modules/servers/pages/basic/index.adoc +++ b/docs/modules/servers/pages/basic/index.adoc @@ -1,9 +1,9 @@ = James Basic Mail Server :navtitle: Basic -The **James Basic Server** is intended for xref:concepts:user/index.adoc#Operator[Operators] +The **James Basic Server** is intended for Operators who are just getting initiated with operating their own -xref:concepts/???[Self-Hosted] mail server. +Self-Hosted mail server. The server is intended to be a mostly "out-of-the-box" solution. With a few small interactions necessary to configure the system, you should diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 7470f86e38..53b0178fc1 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -2,13 +2,13 @@ :navtitle: Servers James offers five types of ready-made Mail Servers. The servers are intended -for those with different needs, ranging from xref:concepts:user/index.adoc#Operators[Operators] +for those with different needs, ranging from Operators who are interested in setting up a server for the first time, to experienced teams of -xref:concepts:user/index.adoc#Developer[Developers] +Developers looking to deploy an advanced distributed system. Each of the servers has been tested and verified so you can deploy a production-grade -xref:concepts/insert-link[Mail Server] with confidence. +Mail Server with confidence. The available James Servers are: --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
