You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2021/08/06 01:36:31 UTC
[james-site] branch asf-site updated: More how tos
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/james-site.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 8c08aad More how tos
8c08aad is described below
commit 8c08aad32d3377dc735423417e81980a1f55c2d9
Author: Benoit Tellier <bt...@linagora.com>
AuthorDate: Fri Aug 6 08:36:09 2021 +0700
More how tos
---
content/feed.xml | 4 +-
.../{index.html => custom-james-assembly.html} | 219 +++++++++++++++------
.../{index.html => custom-smtp-commands.html} | 213 ++++++++++++++------
.../howTo/{index.html => custom-smtp-hooks.html} | 213 ++++++++++++++------
.../{index.html => custom-webadmin-routes.html} | 143 ++++++++------
content/howTo/index.html | 31 ++-
6 files changed, 592 insertions(+), 231 deletions(-)
diff --git a/content/feed.xml b/content/feed.xml
index 9054c09..72296fe 100644
--- a/content/feed.xml
+++ b/content/feed.xml
@@ -24,8 +24,8 @@
</description>
<link>http://james.apache.org/</link>
<atom:link href="http://james.apache.org/feed.xml" rel="self" type="application/rss+xml"/>
- <pubDate>Fri, 30 Jul 2021 08:14:13 +0700</pubDate>
- <lastBuildDate>Fri, 30 Jul 2021 08:14:13 +0700</lastBuildDate>
+ <pubDate>Fri, 06 Aug 2021 08:34:33 +0700</pubDate>
+ <lastBuildDate>Fri, 06 Aug 2021 08:34:33 +0700</lastBuildDate>
<generator>Jekyll v4.2.0</generator>
<item>
diff --git a/content/howTo/index.html b/content/howTo/custom-james-assembly.html
similarity index 54%
copy from content/howTo/index.html
copy to content/howTo/custom-james-assembly.html
index e9fd591..1f5f4c6 100644
--- a/content/howTo/index.html
+++ b/content/howTo/custom-james-assembly.html
@@ -107,68 +107,173 @@
-->
<!-- Main -->
- <div id="main">
+<div id="main">
<!-- Introduction -->
- <section id="intro" class="main special">
+ <section id="intro" class="main special">
<div class="">
- <div class="content">
- <header class="major">
- <h2>James how to's...</h2>
- </header>
- <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
- This section explains in detail how to achieve these cool features in a straightforward way.</p>
-
- <a href="imap-server.html"
- data-lightbox="james-schema"
- data-title="Setting up an IMAP server"
- alt="Setting up an IMAP server"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="spf.html"
- data-lightbox="james-schema"
- data-title="Configuring SPF"
- alt="Configuring SPF"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="deleted-messages-vault.html"
- data-lightbox="james-schema"
- data-title="Deleted Messages Vault"
- alt="Deleted Messages Vault"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <header class="major">
- <h2>Customize James</h2>
- </header>
- <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
- <a href="mail-processing.html"
- data-lightbox="james-schema"
- data-title="Customized mail processing"
- alt="Customized mail processing"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="custom-listeners.html"
- data-lightbox="james-schema"
- data-title="Configure Custom Listeners"
- alt="Configure Custom Listeners"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <br/>
- <br/>
-
- </div>
- </div>
- </section>
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Write Custom James server assembly</b></h1>
+ </header>
+ <p>
+ Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-james-assembly">GitHub</a>.
+ </p>
+
+ <p>
+ The current project demonstrates how to write a custom assembly in order to write your
+ own tailor-made server.
+ </p>
+
+ <ul>This enables:
+ <li>Arbitrary composition of technologies (example JPA mailbox with Cassandra user management)</li>
+ <li>Write any additional components</li>
+ <li>Drop any unneeded component</li>
+ <li>You have control on the dependencies and can reduce the classpath size</li>
+ </ul>
+
+ <header class="major">
+ <h2><b>Example: Write an IMAP+SMTP only memory server</b></h2>
+ </header>
+
+ <p>
+ In order to do this select the modules you wished to assemble
+ <a href="https://github.com/apache/james-project/tree/master/server/container/guice">in the Guice building blocks</a>.
+ We encourage you to have a fine grain control of your dependencies but for the sake of simplicity
+ this example will reuse the dependencies of an existing James application:
+ </p>
+
+ <pre><code><dependency>
+ <groupId>${james.groupId}</groupId>
+ <artifactId>james-server-memory-app</artifactId>
+ <version>${project.version}</version>
+</dependency></code></pre>
+
+ <p>Once done assemble the guice modules together in a class implementing <code>JamesServerMain</code>:</p>
+
+ <pre><code>public class CustomJamesServerMain implements JamesServerMain {
+ public static final Module PROTOCOLS = Modules.combine(
+ new IMAPServerModule(),
+ new ProtocolHandlerModule(),
+ new MailRepositoryTaskSerializationModule(),
+ new SMTPServerModule());
+
+ public static final Module CUSTOM_SERVER_MODULE = Modules.combine(
+ new MailetProcessingModule(),
+ new MailboxModule(),
+ new MemoryDataModule(),
+ new MemoryEventStoreModule(),
+ new MemoryMailboxModule(),
+ new MemoryMailQueueModule(),
+ new TaskManagerModule(),
+ new RawPostDequeueDecoratorModule(),
+ binder -> binder.bind(MailetContainerModule.DefaultProcessorsConfigurationSupplier.class)
+ .toInstance(BaseHierarchicalConfiguration::new));
+
+ public static final Module CUSTOM_SERVER_AGGREGATE_MODULE = Modules.combine(
+ CUSTOM_SERVER_MODULE,
+ PROTOCOLS);
+
+ public static void main(String[] args) throws Exception {
+ Configuration configuration = Configuration.builder()
+ .useWorkingDirectoryEnvProperty()
+ .build();
+
+ JamesServerMain.main(GuiceJamesServer.forConfiguration(configuration)
+ .combineWith(CUSTOM_SERVER_AGGREGATE_MODULE));
+ }
+ }</code></pre>
+
+ <p>You need to write a minimal main method launching your guice module composition.</p>
+
+ <p>We do provide in this example <a href="https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin">JIB</a>
+ to package this custom James assembly into docker:</p>
- </div>
+ <pre><code><plugin>
+ <groupId>com.google.cloud.tools</groupId>
+ <artifactId>jib-maven-plugin</artifactId>
+ <version>2.7.1</version>
+ <configuration>
+ <from>
+ <image>adoptopenjdk:11-jdk-hotspot</image>
+ </from>
+ <to>
+ <image>apache/james</image>
+ <tags>
+ <tag>custom-latest</tag>
+ </tags>
+ </to>
+ <container>
+ <mainClass>org.apache.james.examples.CustomJamesServerMain</mainClass>
+ <ports>
+ <port>25</port> <!-- JMAP -->
+ <port>143</port> <!-- IMAP -->
+ </ports>
+ <appRoot>/root</appRoot>
+ <jvmFlags>
+ <jvmFlag>-Dlogback.configurationFile=/root/conf/logback.xml</jvmFlag>
+ <jvmFlag>-Dworking.directory=/root/</jvmFlag>
+ </jvmFlags>
+ <creationTime>USE_CURRENT_TIMESTAMP</creationTime>
+ </container>
+ <extraDirectories>
+ <paths>
+ <path>
+ <from>sample-configuration</from>
+ <into>/root/conf</into>
+ </path>
+ </paths>
+ </extraDirectories>
+ </configuration>
+ <executions>
+ <execution>
+ <goals>
+ <goal>buildTar</goal>
+ </goals>
+ <phase>package</phase>
+ </execution>
+ </executions>
+</plugin>}</code></pre>
+ <p>We provide a minimal <a href="https://github.com/apache/james-project/tree/master/examples/custom-james-assembly/sample-configuration">sample configuration</a>.
+ </p>
+
+ <p>You can compile this example project:</p>
+
+ <pre><code>mvn clean install</code></pre>
+
+ <p>Create a keystore (default password being <code>james72laBalle</code>):</p>
+
+ <pre><code>keytool -genkey -alias james -keyalg RSA -keystore keystore</code></pre>
+
+ <p>Import the build result:</p>
+
+ <pre><code>$ docker load -i target/jib-image.tar</code></pre>
+
+ <p>Then launch your custom server with docker:</p>
+
+ <pre><code>docker run \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ -p 143:143 \
+ -ti \
+ apache/james:custom-latest
+ </code></pre>
+
+ <p>You will see that your custom James server starts smoothly:</p>
+
+ <pre><code>...
+09:40:25.884 [INFO ] o.a.j.GuiceJamesServer - JAMES server started</code></pre>
+ </div>
+ <footer class="major">
+ <ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ </ul>
+ </footer>
+ </div>
+ </section>
+
+</div>
<!--
diff --git a/content/howTo/index.html b/content/howTo/custom-smtp-commands.html
similarity index 58%
copy from content/howTo/index.html
copy to content/howTo/custom-smtp-commands.html
index e9fd591..2d4dcbc 100644
--- a/content/howTo/index.html
+++ b/content/howTo/custom-smtp-commands.html
@@ -107,68 +107,167 @@
-->
<!-- Main -->
- <div id="main">
+<div id="main">
<!-- Introduction -->
- <section id="intro" class="main special">
+ <section id="intro" class="main special">
<div class="">
- <div class="content">
- <header class="major">
- <h2>James how to's...</h2>
- </header>
- <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
- This section explains in detail how to achieve these cool features in a straightforward way.</p>
-
- <a href="imap-server.html"
- data-lightbox="james-schema"
- data-title="Setting up an IMAP server"
- alt="Setting up an IMAP server"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="spf.html"
- data-lightbox="james-schema"
- data-title="Configuring SPF"
- alt="Configuring SPF"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="deleted-messages-vault.html"
- data-lightbox="james-schema"
- data-title="Deleted Messages Vault"
- alt="Deleted Messages Vault"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <header class="major">
- <h2>Customize James</h2>
- </header>
- <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
- <a href="mail-processing.html"
- data-lightbox="james-schema"
- data-title="Customized mail processing"
- alt="Customized mail processing"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="custom-listeners.html"
- data-lightbox="james-schema"
- data-title="Configure Custom Listeners"
- alt="Configure Custom Listeners"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <br/>
- <br/>
-
- </div>
- </div>
- </section>
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Configure Custom SMTP commands</b></h1>
+ </header>
+
+ <p>
+ The current project demonstrates how to write custom commands for Apache James SMTP server.
+ </p>
+
+ <p>
+ Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-smtp-commands">GitHub</a>.
+ </p>
+
+ <p>
+ Start by importing the dependencies:
+ </p>
+
+ <pre><code><dependency>
+ <groupId>org.apache.james</groupId>
+ <artifactId>james-server-protocols-smtp</artifactId>
+</dependency>
+ </code></pre>
+
+ <p>You can write your commands by extending the <code>CommandHandler<SMTPSession></code> class. For instance:</p>
+
+ <pre><code>/**
+ * Copy of NoopCmdHandler
+ */
+public class MyNoopCmdHandler implements CommandHandler<SMTPSession> {
+ private static final Collection<String> COMMANDS = ImmutableSet.of("MYNOOP");
+
+ private static final Response NOOP = new SMTPResponse(SMTPRetCode.MAIL_OK,
+ DSNStatus.getStatus(DSNStatus.SUCCESS, DSNStatus.UNDEFINED_STATUS) + " OK")
+ .immutable();
+
+ @Override
+ public Response onCommand(SMTPSession session, Request request) {
+ return NOOP;
+ }
+
+ @Override
+ public Collection<String> getImplCommands() {
+ return COMMANDS;
+ }
+}</code></pre>
+
+ <p>You then need to list the exposed SMTP commands with a <code>HandlersPackage</code>. For instance:</p>
+
+ <pre><code>/**
+ * This class copies CoreCmdHandlerLoader adding support for MYNOOP command
+ */
+public class MyCmdHandlerLoader implements HandlersPackage {
+
+ private final List<String> commands = new LinkedList<>();
+
+ public MyCmdHandlerLoader() {
+ Stream.of(
+ JamesWelcomeMessageHandler.class,
+ CommandDispatcher.class,
+ AuthCmdHandler.class,
+ JamesDataCmdHandler.class,
+ EhloCmdHandler.class,
+ ExpnCmdHandler.class,
+ HeloCmdHandler.class,
+ HelpCmdHandler.class,
+ JamesMailCmdHandler.class,
+ NoopCmdHandler.class,
+ QuitCmdHandler.class,
+ JamesRcptCmdHandler.class,
+ RsetCmdHandler.class,
+ VrfyCmdHandler.class,
+ MailSizeEsmtpExtension.class,
+ UsersRepositoryAuthHook.class,
+ AuthRequiredToRelayRcptHook.class,
+ SenderAuthIdentifyVerificationRcptHook.class,
+ PostmasterAbuseRcptHook.class,
+ ReceivedDataLineFilter.class,
+ DataLineJamesMessageHookHandler.class,
+ StartTlsCmdHandler.class,
+ AddDefaultAttributesMessageHook.class,
+ SendMailHandler.class,
+ UnknownCmdHandler.class,
+ CommandHandlerResultLogger.class,
+ HookResultLogger.class,
+ // Support MYNOOP
+ MyNoopCmdHandler.class)
+ .map(Class::getName)
+ .forEachOrdered(commands::add);
+ }
- </div>
+ @Override
+ public List<String> getHandlers() {
+ return commands;
+ }
+}</code></pre>
+ <p>You can compile this example project:</p>
+
+ <pre><code>mvn clean install</code></pre>
+
+ <p>Write a configuration file telling James to use your <code>HandlerPackage</code>:</p>
+
+ <pre><code><smtpservers>
+ <smtpserver enabled="true">
+ <jmxName>smtpserver-global</jmxName>
+ <bind>0.0.0.0:25</bind>
+ <connectionBacklog>200</connectionBacklog>
+ <tls socketTLS="false" startTLS="false">
+ <keystore>file://conf/keystore</keystore>
+ <secret>james72laBalle</secret>
+ <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider>
+ <algorithm>SunX509</algorithm>
+ </tls>
+ <!-- ... -->
+ <handlerchain coreHandlersPackage="org.apache.james.examples.MyCmdHandlerLoader">
+ <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
+ </handlerchain>
+ </smtpserver>
+</smtpservers></code></pre>
+
+ <p>Create a keystore (default password being <code>james72laBalle</code>):</p>
+
+ <pre><code>keytool -genkey -alias james -keyalg RSA -keystore keystore</code></pre>
+
+ <p>Then start a James server with your JAR and the configuration:</p>
+
+ <pre><code>docker run -d \
+ -v $PWD/smtpserver.xml:/root/conf/smtpserver.xml \
+ -v $PWD/exts:/root/extensions-jars \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ apache/james:memory-latest
+ </code></pre>
+
+ <p>You can play with <code>telnet</code> utility with the resulting server and use the <code>MYNOOP</code> command:</p>
+
+ <pre><code>$ $ telnet 127.0.0.1 25
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+220 Apache JAMES awesome SMTP Server
+MYNOOP
+250 2.0.0 OK
+quit
+221 2.0.0 1f0274082fc6 Service closing transmission channel
+Connection closed by foreign host.</code></pre>
+ </div>
+ <footer class="major">
+ <ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ </ul>
+ </footer>
+ </div>
+ </section>
+
+</div>
<!--
diff --git a/content/howTo/index.html b/content/howTo/custom-smtp-hooks.html
similarity index 55%
copy from content/howTo/index.html
copy to content/howTo/custom-smtp-hooks.html
index e9fd591..b370ee1 100644
--- a/content/howTo/index.html
+++ b/content/howTo/custom-smtp-hooks.html
@@ -107,68 +107,167 @@
-->
<!-- Main -->
- <div id="main">
+<div id="main">
<!-- Introduction -->
- <section id="intro" class="main special">
+ <section id="intro" class="main special">
<div class="">
- <div class="content">
- <header class="major">
- <h2>James how to's...</h2>
- </header>
- <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
- This section explains in detail how to achieve these cool features in a straightforward way.</p>
-
- <a href="imap-server.html"
- data-lightbox="james-schema"
- data-title="Setting up an IMAP server"
- alt="Setting up an IMAP server"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="spf.html"
- data-lightbox="james-schema"
- data-title="Configuring SPF"
- alt="Configuring SPF"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="deleted-messages-vault.html"
- data-lightbox="james-schema"
- data-title="Deleted Messages Vault"
- alt="Deleted Messages Vault"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <header class="major">
- <h2>Customize James</h2>
- </header>
- <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
- <a href="mail-processing.html"
- data-lightbox="james-schema"
- data-title="Customized mail processing"
- alt="Customized mail processing"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="custom-listeners.html"
- data-lightbox="james-schema"
- data-title="Configure Custom Listeners"
- alt="Configure Custom Listeners"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <br/>
- <br/>
-
- </div>
- </div>
- </section>
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Configure Custom SMTP hooks</b></h1>
+ </header>
+
+ <p>
+ The current project demonstrates how to write custom behaviors for Apache James SMTP server
+ by the means of SMTP hooks.
+ </p>
+
+ <p>
+ SMTP hooks allow integrating third party systems with the SMTP stack and writing additional SMTP extensions, for
+ instance.
+ </p>
+
+ <p>
+ Start by importing the dependencies:
+ </p>
+
+ <pre><code><dependency>
+ <groupId>org.apache.james.protocols</groupId>
+ <artifactId>protocols-smtp/artifactId>
+</dependency>
+ </code></pre>
+
+ <ul>Allows writing the following hooks:
+ <li><b>AuthHook</b>: hook in the AUTH Command</li>
+ <li><b>HeloHook</b>: hook in the HELO Command</li>
+ <li><b>MailHook</b>: hook in the MAIL Command</li>
+ <li><b>MailParametersHook</b>: hook in the MAIL Command parameters</li>
+ <li><b>RcptHook</b>: hook in the RCPT Command</li>
+ <li><b>MessageHook</b>: hook in the DATA Command</li>
+ <li><b>QuitHook</b>: hook in the QUIT Command</li>
+ <li><b>UnknownHook</b>: hook for unknown commands</li>
+ </ul>
+
+ <pre><code><dependency>
+ <groupId>org.apache.james</groupId>
+ <artifactId>james-server-protocols-smtp</artifactId>
+</dependency>
+ </code></pre>
+
+ <p>James comes bundled with <a href="http://james.apache.org/server/dev-provided-smtp-hooks.html">provided SMTP hooks for common features</a>.
+ We encourage you to review them before starting writing your own hooks.</p>
+
+ <ul>Allows writing the following hooks:
+ <li><b>JamesMessageHook</b>: DATA command. Allows access to the message content.</li>
+ </ul>
+
+ <header class="major">
+ <h2><b>Writing your own hooks</b></h2>
+ </header>
+
+ <p>
+ Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-smtp-hooks">GitHub</a>.
+ </p>
+
+ <p>
+ In this example we implement a single RCPT hook:
+ </p>
+
+ <pre><code>public class LoggingRcptHook implements RcptHook {
+ @Override
+ public HookResult doRcpt(SMTPSession session, MaybeSender sender, MailAddress rcpt, Map<String, String> parameters) {
+ System.out.println("RCPT TO " + rcpt + "with parameters " + parameters);
+
+ // Continue the SMTP transaction
+ return HookResult.DECLINED;
+ }
+}
+ </code></pre>
+
+ <p>You can compile this example project:</p>
- </div>
+ <pre><code>mvn clean install</code></pre>
+ <p>Then embed your extension into a James server. First configure your hook:</p>
+
+ <pre><code><?xml version="1.0"?>
+<smtpservers>
+ <smtpserver enabled="true">
+ <jmxName>smtpserver-global</jmxName>
+ <bind>0.0.0.0:25</bind>
+ <connectionBacklog>200</connectionBacklog>
+ <tls socketTLS="false" startTLS="false">
+ <keystore>file://conf/keystore</keystore>
+ <secret>james72laBalle</secret>
+ <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider>
+ <algorithm>SunX509</algorithm>
+ </tls>
+ <!-- ... -->
+ <handlerchain>
+ <handler class="org.apache.james.smtpserver.fastfail.ValidRcptHandler"/>
+ <handler class="org.apache.james.smtpserver.CoreCmdHandlerLoader"/>
+ <handler class="org.apache.james.examples.LoggingRcptHook"/>
+ </handlerchain>
+ </smtpserver>
+</smtpservers>
+ </code></pre>
+
+ <p>Create a keystore (default password being <code>james72laBalle</code>):</p>
+
+ <pre><code>keytool -genkey -alias james -keyalg RSA -keystore keystore</code></pre>
+
+ <p>Then start a James server with your JAR and the configuration:</p>
+
+ <pre><code>docker run -d \
+ -v $PWD/smtpserver.xml:/root/conf/smtpserver.xml \
+ -v $PWD/exts:/root/extensions-jars \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ apache/james:memory-latest
+ </code></pre>
+
+ <p>You can play with <code>telnet</code> utility with the resulting server:</p>
+
+ <pre><code>$ telnet 127.0.0.1 25
+Trying 127.0.0.1...
+Connected to 127.0.0.1.
+Escape character is '^]'.
+220 Apache JAMES awesome SMTP Server
+EHLO toto.com
+250-177b73020637 Hello toto.com [172.17.0.1])
+250-PIPELINING
+250-ENHANCEDSTATUSCODES
+250 8BITMIME
+RCPT TO: <b@c.com>
+503 5.5.0 Need MAIL before RCPT
+MAIL FROM: <b@c.com>
+250 2.1.0 Sender <b@c.com> OK
+RCPT TO: <c@d.com>
+550 5.7.1 Requested action not taken: relaying denied
+quit
+ </code></pre>
+
+ <p>
+ Now looking at the logs we can verify that our RCPT have well been executed:
+ </p>
+
+ <pre><code>06:49:15.734 [INFO ] o.a.j.GuiceJamesServer - JAMES server started
+06:49:30.275 [INFO ] o.a.j.p.n.BasicChannelUpstreamHandler - Connection established from 172.17.0.1
+06:50:18.892 [INFO ] o.a.j.i.n.ImapChannelUpstreamHandler - Connection established from 172.17.0.1
+06:50:19.152 [INFO ] o.a.j.i.n.ImapChannelUpstreamHandler - Connection closed for 172.17.0.1
+RCPT TO c@d.comwith parameters {TO:=, <c@d.com>=}</code></pre>
+
+ <p>Note that hooks can also be written for the LMTP protocol.</p>
+ </div>
+ <footer class="major">
+ <ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ </ul>
+ </footer>
+ </div>
+ </section>
+
+</div>
<!--
diff --git a/content/howTo/index.html b/content/howTo/custom-webadmin-routes.html
similarity index 70%
copy from content/howTo/index.html
copy to content/howTo/custom-webadmin-routes.html
index e9fd591..45f704b 100644
--- a/content/howTo/index.html
+++ b/content/howTo/custom-webadmin-routes.html
@@ -107,68 +107,97 @@
-->
<!-- Main -->
- <div id="main">
+<div id="main">
<!-- Introduction -->
- <section id="intro" class="main special">
+ <section id="intro" class="main special">
<div class="">
- <div class="content">
- <header class="major">
- <h2>James how to's...</h2>
- </header>
- <p class="align-left">James can be used for a wide variety of cases. Here is a little list of what you can use it for.<br/>
- This section explains in detail how to achieve these cool features in a straightforward way.</p>
-
- <a href="imap-server.html"
- data-lightbox="james-schema"
- data-title="Setting up an IMAP server"
- alt="Setting up an IMAP server"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Setting up an IMAP server<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="spf.html"
- data-lightbox="james-schema"
- data-title="Configuring SPF"
- alt="Configuring SPF"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configuring SPF <span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="deleted-messages-vault.html"
- data-lightbox="james-schema"
- data-title="Deleted Messages Vault"
- alt="Deleted Messages Vault"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Deleted Messages Vault<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <header class="major">
- <h2>Customize James</h2>
- </header>
- <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
- <a href="mail-processing.html"
- data-lightbox="james-schema"
- data-title="Customized mail processing"
- alt="Customized mail processing"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Customized mail processing<span class="fa fa-long-arrow-right"></span>
- </a>
- <a href="custom-listeners.html"
- data-lightbox="james-schema"
- data-title="Configure Custom Listeners"
- alt="Configure Custom Listeners"
- class="james-schema" >
- <span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
- </a>
-
- <br/>
- <br/>
-
- </div>
- </div>
- </section>
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Configure Custom WebAdmin routes</b></h1>
+ </header>
+
+ <p>
+ The current project demonstrates how to write custom webadmin routes for Apache James. This enables writing new
+ administrative features exposed over a REST API. This can allow you to write some additional features, make James
+ interact with third party systems, do advance reporting...
+ </p>
+
+ <p>
+ Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-webadmin-routes">GitHub</a>.
+ </p>
+
+ <p>
+ Start by importing the dependencies:
+ </p>
+
+ <pre><code><dependency>
+ <groupId>org.apache.james</groupId>
+ <artifactId>james-server-webadmin-core</artifactId>
+</dependency>
+ </code></pre>
+
+ <p>You can then write your first route using the <a href="https://sparkjava.com/">Spark Java</a> framework:</p>
+
+ <pre><code>public class RouteA implements Routes {
+ @Override
+ public String getBasePath() {
+ return "/hello/a";
+ }
+
+ @Override
+ public void define(Service service) {
+ service.get(getBasePath(), (req, res) -> "RouteA\n");
+ }
+}</code></pre>
+
+ <ul>Knowing that:
+ <li>entending <b>Routes</b>: will ensure that authentication is requested if configured.</li>
+ <li>entending <b>PublicRoutes</b>: will not request authentication.</li>
+ </ul>
+
+ <p>You can compile this example project:</p>
+
+ <pre><code>mvn clean install</code></pre>
- </div>
+ <p>Then embed your route into a James server. First configure your route into <code>webadmin.properties</code>:</p>
+ <pre><code>enabled=true
+port=8000
+host=localhost
+
+# List of fully qualified class names that should be exposed over webadmin
+# in addition to your product default routes. Routes needs to be located
+# within the classpath or in the ./extensions-jars folder.
+extensions.routes=org.apache.james.examples.RouteA</code></pre>
+
+ <p>Create a keystore (default password being <code>james72laBalle</code>):</p>
+
+ <pre><code>keytool -genkey -alias james -keyalg RSA -keystore keystore</code></pre>
+
+ <p>Then start a James server with your JAR and the configuration:</p>
+
+ <pre><code>docker run -d \
+ -v $PWD/webadmin.properties:/root/conf/webadmin.properties \
+ -v $PWD/exts:/root/extensions-jars \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ apache/james:memory-latest</code></pre>
+
+ <p>You can play with <code>curl</code> utility with the resulting server:</p>
+
+ <pre><code>$ curl -XGET http://172.17.0.2:8000/hello/a
+RouteA</code></pre>
+ </div>
+ <footer class="major">
+ <ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ </ul>
+ </footer>
+ </div>
+ </section>
+
+</div>
<!--
diff --git a/content/howTo/index.html b/content/howTo/index.html
index e9fd591..bc470e1 100644
--- a/content/howTo/index.html
+++ b/content/howTo/index.html
@@ -144,7 +144,7 @@
<header class="major">
<h2>Customize James</h2>
</header>
- <p class="align-left">This section will show you how to modify James to use it in your purpose</p>
+ <p class="align-left">This section will show you how to modify James to use it in your purpose, and embed your own code.</p>
<a href="mail-processing.html"
data-lightbox="james-schema"
data-title="Customized mail processing"
@@ -159,6 +159,35 @@
class="james-schema" >
<span class="fa fa-sitemap"></span>Configure Custom Listeners<span class="fa fa-long-arrow-right"></span>
</a>
+ <a href="custom-smtp-hooks.html"
+ data-lightbox="james-schema"
+ data-title="Configure Custom SMTP hooks"
+ alt="Configure Custom SMTP hooks"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configure Custom SMTP hooks<span class="fa fa-long-arrow-right"></span>
+ </a>
+ <br/>
+ <a href="custom-smtp-commands.html"
+ data-lightbox="james-schema"
+ data-title="Configure Custom SMTP commands"
+ alt="Configure Custom SMTP commands"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configure Custom SMTP commands<span class="fa fa-long-arrow-right"></span>
+ </a>
+ <a href="custom-webadmin-routes.html"
+ data-lightbox="james-schema"
+ data-title="Configure Custom WebAdmin routes"
+ alt="Configure Custom WebAdmin routes"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configure Custom WebAdmin routes<span class="fa fa-long-arrow-right"></span>
+ </a>
+ <a href="custom-james-assembly.html"
+ data-lightbox="james-schema"
+ data-title="Write Custom James server assembly"
+ alt="Write Custom James server assembly"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Write Custom James server assembly<span class="fa fa-long-arrow-right"></span>
+ </a>
<br/>
<br/>
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org