blob: 538d29ea00def93c72697214188403e08edcc3c5 [file] [log] [blame]
<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements. See the NOTICE file
distributed with this work for additional information
regarding copyright ownership. The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied. See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- Generated by Apache Maven Doxia at 2021-11-12 -->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Apache James Project &#x2013; Apache James Server 3 - Installation</title>
<style type="text/css" media="all">
@import url("../css/james.css");
@import url("../css/maven-base.css");
@import url("../css/maven-theme.css");
@import url("../css/site.css");
@import url("../js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css");
@import url("../js/jquery/css/print.css");
@import url("../js/fancybox/jquery.fancybox-1.3.4.css");
</style>
<script type="text/javascript" src="../js/jquery/js/jquery-1.4.2.min.js"></script>
<script type="text/javascript" src="../js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script>
<script type="text/javascript" src="../js/fancybox/jquery.fancybox-1.3.4.js"></script>
<link rel="stylesheet" href="../css/print.css" type="text/css" media="print" />
<meta name="Date-Revision-yyyymmdd" content="20211112" />
<meta http-equiv="Content-Language" content="en" />
<!-- Google Analytics -->
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-1384591-1']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body class="composite">
<div id="banner">
<a href="../index.html" id="bannerLeft" title="james-logo.png">
<img src="../images/logos/james-logo.png" alt="James Project" />
</a>
<a href="https://www.apache.org/index.html" id="bannerRight">
<img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" />
</a>
<div class="clear">
<hr/>
</div>
</div>
<div id="breadcrumbs">
<div class="xleft">
<span id="publishDate">Last Published: 2021-11-12</span>
</div>
<div class="xright"> <a href="../index.html" title="Home">Home</a>
|
<a href="../documentation.html" title="James">James</a>
|
<a href="../mime4j/index.html" title="Mime4J">Mime4J</a>
|
<a href="../jsieve/index.html" title="jSieve">jSieve</a>
|
<a href="../jspf/index.html" title="jSPF">jSPF</a>
|
<a href="../jdkim/index.html" title="jDKIM">jDKIM</a>
</div>
<div class="clear">
<hr/>
</div>
</div>
<div id="leftColumn">
<div id="navcolumn">
<h5>James components</h5>
<ul>
<li class="collapsed">
<a href="../documentation.html" title="About James">About James</a>
</li>
<li class="expanded">
<a href="../server/index.html" title="Server">Server</a>
<ul>
<li class="none">
<a href="../server/advantages.html" title="Advantages">Advantages</a>
</li>
<li class="none">
<a href="../server/objectives.html" title="Objectives">Objectives</a>
</li>
<li class="expanded">
<a href="../server/quick-start.html" title="User Manual">User Manual</a>
<ul>
<li class="collapsed">
<a href="../server/features.html" title="1. Features">1. Features</a>
</li>
<li class="none">
<a href="../server/packaging.html" title="2. Packaging">2. Packaging</a>
</li>
<li class="expanded">
<strong>3. Install James</strong>
<ul>
<li class="none">
<a href="../server/install/guice-cassandra-rabbitmq-s3.html" title="Cassandra-RabbitMQ-S3-guice">Cassandra-RabbitMQ-S3-guice</a>
</li>
<li class="none">
<a href="../server/install/guice-cassandra.html" title="Cassandra-guice">Cassandra-guice</a>
</li>
<li class="none">
<a href="../server/install/guice-jpa.html" title="JPA-guice">JPA-guice</a>
</li>
<li class="none">
<a href="../server/install/guice-jpa-smtp.html" title="JPA-SMTP-guice">JPA-SMTP-guice</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../server/config.html" title="4. Configure James">4. Configure James</a>
</li>
<li class="collapsed">
<a href="../server/manage.html" title="5. Manage">5. Manage</a>
</li>
<li class="collapsed">
<a href="../server/monitor.html" title="6. Monitor">6. Monitor</a>
</li>
<li class="collapsed">
<a href="../server/upgrade.html" title="7. Upgrade">7. Upgrade</a>
</li>
<li class="collapsed">
<a href="../server/dev.html" title="8. Developers Corner">8. Developers Corner</a>
</li>
</ul>
</li>
<li class="none">
<a href="../mail.html#James_Mailing_lists" title="Mailing Lists">Mailing Lists</a>
</li>
<li class="none">
<a href="../server/release-notes.html" title="Release Notes">Release Notes</a>
</li>
<li class="none">
<a href="../server/apidocs/index.html" title="Javadoc">Javadoc</a>
</li>
<li class="none">
<a href="https://issues.apache.org/jira/browse/JAMES" title="Issue Tracker">Issue Tracker</a>
</li>
<li class="none">
<a href="https://github.com/apache/james-project" title="Sources">Sources</a>
</li>
<li class="none">
<a href="../server/rfcs.html" title="RFCs">RFCs</a>
</li>
<li class="none">
<a href="../download.cgi#Apache_James_Server" title="Download releases">Download releases</a>
</li>
</ul>
</li>
<li class="collapsed">
<a href="../mailet/index.html" title="Mailets">Mailets</a>
</li>
<li class="collapsed">
<a href="../mailbox/index.html" title="Mailbox">Mailbox</a>
</li>
<li class="collapsed">
<a href="../protocols/index.html" title="Protocols">Protocols</a>
</li>
<li class="collapsed">
<a href="../mpt/index.html" title="MPT">MPT</a>
</li>
</ul>
<h5>Apache Software Foundation</h5>
<ul>
<li>
<strong>
<a title="ASF" href="http://www.apache.org/">ASF</a>
</strong>
</li>
<li>
<a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a>
</li>
<li>
<a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a>
</li>
<li>
<a title="License" href="http://www.apache.org/licenses/" >License</a>
</li>
<li>
<a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a>
</li>
<li>
<a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a>
</li>
<li>
<a title="Security" href="http://www.apache.org/security/">Security</a>
</li>
</ul>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" />
</a>
</div>
</div>
<div id="bodyColumn">
<div id="contentBox">
<section>
<h2><a name="Requirements"></a>Requirements</h2>
<section>
<h3><a name="Java_Virtual_Machine"></a>Java Virtual Machine</h3>
<p>James 3.6.0 requires a Java Runtime Environment. Java version 1.11 is required to run the
James application. The exact JREs available depends on the platform. In addition, the environment variable JAVA_HOME should be set to
the JRE home directory before running James.</p>
<p>James 3.6.0 has been successfully tested on OpenJDK 1.11</p>
</section>
<section>
<h3><a name="User_Privileges"></a>User Privileges</h3>
<p>On Linux/Unix platforms, root access will be required to run James (access to ports
below 1024 is generally restricted to the root user). As SMTP, POP3, and IMAP4
need to open server sockets on such ports in standard configurations,
James requires root access.</p>
<p>On Windows platforms, you also need to run James as Administrator privilege.</p>
</section>
<section>
<h3><a name="Libc6"></a>Libc6</h3>
<p>On Linux, to run the startup/shutdown script via the 'james' command, you also need libc6
(on Ubuntu for example: sudo apt-get install libc6-i386 libc6-dev-i386).</p>
</section>
<section>
<h3><a name="System_Resources"></a>System Resources</h3>
<p>Obviously James also requires sufficient disk space, processor power, and network bandwidth. But,
other than what's been discussed here, it has no additional special requirements.</p>
<p>James is configured to run with 512 MB RAM (-Xmx512M in the bat/sh) available, but may need more or
less depending on the load. With the default configuration, JVM can use until 512M (It does not mean it will do).
It really depends on your traffic, and also which mailbox you will use (you can save much memory
if you don't use the default embedded derby database but an external database of your choice).
Work is still done to minimize the needed memory.
</p>
</section>
</section>
<section>
<h2><a name="Build_instructions"></a>Build instructions</h2>
<p>Checkout code from the chosen version on <a class="externalLink" href="https://github.com/apache/james-project/tree/james-project-3.6.0">
GitHub</a>. Follow <a class="externalLink" href="https://github.com/apache/james-project/blob/james-project-3.6.0/README.adoc">README instructions</a> about compilation.</p>
<ul>Using these instructions, you can build the following images:
<li>Guice + JPA + Lucene</li>
<li>Guice + Cassandra + ElasticSearch</li>
<li>Guice + Cassandra + ElasticSearch + LDAP</li>
<li>Spring</li>
</ul>
<p>Alternatively, if you don't want your build to be handled via Docker, you can follow <a href="quick-start-cassandra.html">
Guice Cassandra quick-start</a> </p>
<p>Note that install instructions from command line are available for <a href="install/cassandra-guice.html">Cassandra-Guice</a>,
<a href="install/jpa-guice.html">JPA-Guice</a> and <a href="install/jpa-smtp-guice.html">JPA-SMTP-Guice</a>.
</p>
<p>A <a class="externalLink" href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/docker-compose.yml">
docker-compose</a> is available for Guice + Cassandra + ElasticSearch + RabbitMQ</p>
</section>
<section>
<h2><a name="Install_Step_by_Step"></a>Install Step by Step</h2>
This guide documents how to install a Spring flavoured JAMES server.
<section>
<h3><a name="Step_1:_Download_James"></a>Step 1: Download James</h3>
<p>Obtain the full James binary (or source) distribution from
the <a class="externalLink" href="http://james.apache.org/download.cgi">James
release mirrors</a>.</p>
<p>If you have downloaded a binary distribution, you do not need to build James.
Proceed directly to Step 2.</p>
<p>If you have downloaded a source package, process first to
the <a href="dev-build.html">build</a> and come back to Step 2.</p>
</section>
<section>
<h3><a name="Step_2:_Deploy_James"></a>Step 2: Deploy James</h3>
<p>Unpack the archive into your James installation directory.</p>
</section>
<section>
<h3><a name="Step_3:_Configure_James"></a>Step 3: Configure James</h3>
<p>After unpacking the binary, the next step is to adjust the initial configuration.
All configuration files are embedded in jars. We ship in the conf folder the configuration files that can be edited to match your needs.
</p>
<p>Additional system files reside under the./conf/META-INF folder.</p>
<p>The out of the box configuration makes certain assumptions and has some default
values that are unlikely to be appropriate for real-world servers.
There are a few issues that should be addressed immediately upon installation:</p>
<ul>
<li>Postmaster Address - Change according to your need - <a href="config-system.html">read more</a>.</li>
<li>Most UNIX systems require superuser privileges to open sockets below 1024,
which includes the IANA-standard SMTP (on port 25), POP3 (on port 110) and IMAP4 (on port 143).
These default ports can be changed in the conf file
(read for <a href="config-pop3.html">pop3</a>, <a href="config-smtp-lmtp.html">smtp</a>
and <a href="config-imap4.html">imap4</a>. Obviously, you
would then need to reconfigure your clients. This may not be an option if
you want to receive mail from external mail servers.</li>
</ul>
<p>In addition to adjusting these parameters, you may wish to consult the documentation for a discussion of
all other configurations. A list of such configurations, as well as the steps necessary to configure them, can
be found <a href="config.html">here</a>.</p>
</section>
<section>
<h3><a name="Step_4:_Start_James"></a>Step 4: Start James</h3>
<p>Go to the bin subdirectory of the installation directory and run $ ./james start.</p>
<p>Running $ ./james help help will provide the list of commands you can invoke. </p>
<p>Once started, you'll see in the log file (./logs/james-server.log) that
James is running. This means that Spring has loaded James and is now waiting for a request.</p>
</section>
<section>
<h3><a name="Step_5:_Create_Domains_and_Users"></a>Step 5: Create Domains and Users</h3>
<p>Finally, after launch, it will be necessary to create domain and user accounts
before the James server will be fully operational. Read instructions on creating
<a href="manage-domains.html">domains</a> and <a href="manage-users.html">user accounts</a>.</p>
<p>Since at the beginning James is empty, it will not have any domain (except the default one)nor local users
registered.</p>
<p>To register a local domain and user, cd bin and type james-cli.sh.
Follow the given instructions</p>
<p>Invoke &quot;james-cli.sh adddomain &lt;mydomain.tls&gt; &lt;mydomain.tls&gt; is the domain name
of the domain you wish to create.</p>
<p>Invoke &quot;james-cli.sh adduser &lt;user&gt; &lt;password&gt;&quot; where &lt;user&gt; is the user name
and &lt;password&gt; is the password of the account you wish to create.</p>
<p>Please note that the user name MUST be a complete email address of the form &lt;user&gt;@&lt;domain&gt;
(where &lt;domain&gt; is any of the values specified in the &lt;servernames&gt; block of XMLDomainList or
a domain defined via the <a href="manage-domains.html">domain management</a>).</p>
</section>
<section>
<h3><a name="Step_6:_Test_James"></a>Step 6: Test James</h3>
<p>Once you have some local users registered, try sending mail to one of them
with SMTP (port 25).</p>
<div class="source">
<pre>
$ telnet 127.0.0.1 25
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
220 172.16.1.131 SMTP Server (JAMES SMTP Server 3.0.0) ready Wed, 20 Jul 2017 17:31:33 +0100 (CET)
ehlo test
250-172.16.1.131 Hello test (aoscommunity.com [127.0.0.1])
250-PIPELINING
250-ENHANCEDSTATUSCODES
250 8BITMIME
mail from:&lt;YOUR_NAME@YOUR_DOMAIN&gt;
250 2.1.0 Sender &lt;YOUR_NAME@YOUR_DOMAIN&gt; OK
rcpt to:&lt;YOUR_NAME@YOUR_DOMAIN&gt;
250 2.1.5 Recipient &lt;YOUR_NAME@YOUR_DOMAIN&gt; OK
data
354 Ok Send data ending with &lt;CRLF&gt;.&lt;CRLF&gt;
subject: test
this is a test
.
250 2.6.0 Message received
quit
Connection closed by foreign host.
</pre></div>
<p>Try now to retrieve that mail using POP3 (port 110) or IMAP (port 993 with OpenSSL).</p>
<div class="source">
<pre>
$ openssl s_client -connect 127.0.0.1:993
CONNECTED(00000003)
Can't use SSL_get_servername
depth=0 C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
verify error:num=18:self signed certificate
verify return:1
depth=0 C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
verify error:num=10:certificate has expired
notAfter=Nov 24 07:32:55 2015 GMT
verify return:1
depth=0 C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
notAfter=Nov 24 07:32:55 2015 GMT
verify return:1
---
Certificate chain
0 s:C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
i:C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
---
Server certificate
-----BEGIN CERTIFICATE-----
MIIDeTCCAmGgAwIBAgIEXaLC/zANBgkqhkiG9w0BAQsFADBtMQswCQYDVQQGEwJG
UjEQMA4GA1UECBMHVW5rbm93bjEQMA4GA1UEBxMHUHV0ZWF1eDEOMAwGA1UEChMF
SmFtZXMxETAPBgNVBAsTCExpbmFnb3JhMRcwFQYDVQQDEw5CZW5vaXQgVGVsbGll
cjAeFw0xNTA4MjYwNzMyNTVaFw0xNTExMjQwNzMyNTVaMG0xCzAJBgNVBAYTAkZS
MRAwDgYDVQQIEwdVbmtub3duMRAwDgYDVQQHEwdQdXRlYXV4MQ4wDAYDVQQKEwVK
YW1lczERMA8GA1UECxMITGluYWdvcmExFzAVBgNVBAMTDkJlbm9pdCBUZWxsaWVy
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAhW0GWSgkK44XQpwLn8KX
q9kJ3zgDYllEX7W8p+3sBYMAP0JC+lzh42mX/8XHti0vkmv/vjk0paAsB9s5uYhv
/W94sdqjexi3L213+OD5Kcy+2tTgXN1ucF65d/dDeqGHAyBs1rm6LgyRwQ5ye8Cl
OtXbSkz5qujmnFDDzrDIgzefxFsTHHIBTsdyttq2Atqzgdg2LHaFbIntwr6lfl9v
puXr8p+CY6PfehX8mdmaJ7J/gfAll3zzdgeNUoAW0eDvcsphJ06elsDahieo0n/o
XVhy+TGWtAQRDZQDjeK2BX/vVSPAlGOW7hVTv7WycAolzKlXZyiJMnwTWJl6YoUP
vQIDAQABoyEwHzAdBgNVHQ4EFgQU7tDLswRlOJqoX4aVgrXRQbmOYbIwDQYJKoZI
hvcNAQELBQADggEBAGmzK2i2H5D6xITyN1iNQhXbABQ/3rz9K5dEvy0ZLgYOUqyw
1WD43Do/A3eZuEZbuuYAlbvDEUNgS7rJ5HCrwIKFbPHWmfRX2j59UX+R8fI6G9wB
qqcRYWpert347rGT/7MFLHk55LL6Tf//fwoWu6GWRj3wTvosVuunUiiC6zTS4MN9
moJp+IF03Q6JOPWu7/tfaKfXQHxG/hK492oV2vBG2r29UUJW6YO1S0DK+/cU0cCu
+jqbY1ZOIAk906onRUFoPGuypOm3vmbE6mo5o49rNtp+VmZagZ7GsjJ4KWJB1c6d
SFNIFlH2VlS8Lywr2tesClWO5tqtMswRsoA9GeU=
-----END CERTIFICATE-----
subject=C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
issuer=C = FR, ST = Unknown, L = Puteaux, O = James, OU = Linagora, CN = Benoit Tellier
---
No client certificate CA names sent
Peer signing digest: SHA256
Peer signature type: RSA-PSS
Server Temp Key: X25519, 253 bits
---
SSL handshake has read 1425 bytes and written 363 bytes
Verification error: certificate has expired
---
New, TLSv1.3, Cipher is TLS_AES_256_GCM_SHA384
Server public key is 2048 bit
Secure Renegotiation IS NOT supported
Compression: NONE
Expansion: NONE
No ALPN negotiated
Early data was not sent
Verify return code: 10 (certificate has expired)
---
---
Post-Handshake New Session Ticket arrived:
SSL-Session:
Protocol : TLSv1.3
Cipher : TLS_AES_256_GCM_SHA384
Session-ID: 92D136BF8C9E3E09C4FF7946A2AFDC8ED6E395A1729532D3544E58F688B787F9
Session-ID-ctx:
Resumption PSK: C4E09FF3045720EE910AEA5300D87FDE2200A56F218AC3F75748BE794F73F32790FC8DD35CA70869FBD075727779BA73
PSK identity: None
PSK identity hint: None
SRP username: None
TLS session ticket lifetime hint: 86400 (seconds)
TLS session ticket:
0000 - 03 d2 89 8a 32 48 28 a2-99 24 99 47 b2 05 e8 99 ....2H(..$.G....
0010 - 6b 9b a9 0b 59 95 dd 2c-fb ba 46 b9 94 ad 36 63 k...Y..,..F...6c
Start Time: 1630033038
Timeout : 7200 (sec)
Verify return code: 10 (certificate has expired)
Extended master secret: no
Max Early Data: 0
---
read R BLOCK
* OK JAMES IMAP4rev1 Server 2e73ecd482f4 is ready.
a login bob@domain.com 1234
a OK LOGIN completed.
1 logout
* BYE IMAP4rev1 Server logging out
1 OK LOGOUT completed.
closed
</pre></div>
<p>Trace out James actions in ./logs/james-server.log.</p>
<p>Actions that will be taken by James on incoming mail are configured in
the mailet pipe line (./conf/mailetcontainer.xml). Look at it if you want to
understand what's happening.</p>
</section>
</section>
</div>
</div>
<div class="clear">
<hr/>
</div>
<div id="footer">
<div class="xright">Copyright &#169; 2006-2021
<a href="https://www.apache.org/">The Apache Software Foundation</a>.
All Rights Reserved.
</div>
<div class="clear">
<hr/>
</div>
</div>
</body>
</html>