| <?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 – Manage James via the Command Line</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="collapsed"> |
| <a href="../server/install.html" title="3. Install James">3. Install James</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/config.html" title="4. Configure James">4. Configure James</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/manage.html" title="5. Manage">5. Manage</a> |
| <ul> |
| <li class="none"> |
| <strong>Command line</strong> |
| </li> |
| <li class="none"> |
| <a href="../server/metrics.html" title="Metrics">Metrics</a> |
| </li> |
| <li class="none"> |
| <a href="../server/manage-webadmin.html" title="WebAdmin">WebAdmin</a> |
| </li> |
| <li class="none"> |
| <a href="../server/manage-guice-distributed-james.html" title="Distributed James">Distributed James</a> |
| </li> |
| </ul> |
| </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"> |
| <h1>Manage James via the Command Line</h1> |
| <p>With any wiring, James is packed with a command line client.</p> |
| <p>To use it enter, for Spring distrubution:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>./bin/james-cli.sh -h 127.0.0.1 -p 9999 COMMAND |
| </pre></div></div> |
| |
| <p>And for Guice distributions:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>java -jar /root/james-cli.jar -h 127.0.0.1 -p 9999 COMMAND |
| </pre></div></div> |
| |
| <p>Guice in docker embeds a script helper:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>docker exec -ti james james-cli COMMAND |
| </pre></div></div> |
| |
| <p>The following document will explain you which are the available options for <b>COMMAND</b>.</p> |
| <p>Note: the command line before <b>COMMAND</b> will be documente as <i>{cli}</i>.</p><section> |
| <h2><a name="Navigation_menu"></a>Navigation menu</h2> |
| <ul> |
| |
| <li><a href="#Manage_Domains">Manage Domains</a></li> |
| <li><a href="#Managing_users">Managing users</a></li> |
| <li><a href="#Managing_mailboxes">Managing mailboxes</a></li> |
| <li><a href="#Adding_a_message_in_a_mailbox">Adding a message in a mailbox</a></li> |
| <li><a href="#Managing_mappings">Managing mappings</a></li> |
| <li><a href="#Manage_quotas">Manage quotas</a></li> |
| <li><a href="#Re-indexing">Re-indexing</a></li> |
| <li><a href="#Sieve_scripts_quota">Sieve scripts quota</a></li> |
| <li><a href="#Switching_of_mailbox_implementation">Switching of mailbox implementation</a></li> |
| </ul></section><section> |
| <h2><a name="Manage_Domains"></a>Manage Domains</h2> |
| <p>Domains represent the domain names handled by your server.</p> |
| <p>You can add a domain:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} AddDomain domain.tld |
| </pre></div></div> |
| |
| <p>You can remove a domain:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} RemoveDomain domain.tld |
| </pre></div></div> |
| |
| <p>(Note: associated users are not removed automatically)</p> |
| <p>Check if a domain is handled:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ContainsDomain domain.tld |
| </pre></div></div> |
| |
| <p>And list your domains:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ListDomains |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Managing_users"></a>Managing users</h2> |
| <p>Note: the following commands are explained with virtual hosting turned on.</p> |
| <p>Users are accounts on the mail server. James can maintain mailboxes for them.</p> |
| <p>You can add a user:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} AddUser user@domain.tld password |
| </pre></div></div> |
| |
| <p>Note: the domain used should have been previously created.</p> |
| <p>You can delete a user:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} RemoveUser user@domain.tld |
| </pre></div></div> |
| |
| <p>(Note: associated mailboxes are not removed automatically)</p> |
| <p>And change a user password:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} SetPassword user@domain.tld password |
| </pre></div></div> |
| |
| <p>Note: All these write operations can not be performed on LDAP backend, as the implementation is read-only.</p> |
| <p>Finally, you can list users:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ListUsers |
| </pre></div></div> |
| <section> |
| <h3><a name="Virtual_hosting"></a>Virtual hosting</h3> |
| <p>James supports virtualhosting.</p> |
| <ul> |
| |
| <li>If set to true in the configuration, then the username is the full mail address.</li> |
| </ul> |
| <p>The domains then become a part of the user.</p> |
| <p><i><a class="externalLink" href="mailto:usera@domaina.com">usera@domaina.com</a> and</i> <i><a class="externalLink" href="mailto:usera@domainb.com">usera@domainb.com</a></i> on a mail server with <i>domaina.com</i> and <i>domainb.com</i> configured are mail addresses that belongs to different users.</p> |
| <ul> |
| |
| <li>If set to false in the configurations, then the username is the mail address local part.</li> |
| </ul> |
| <p>It means that a user is automatically created for all the domains configured on your server.</p> |
| <p><i><a class="externalLink" href="mailto:usera@domaina.com">usera@domaina.com</a> and</i> <i><a class="externalLink" href="mailto:usera@domainb.com">usera@domainb.com</a></i> on a mail server with <i>domaina.com</i> and <i>domainb.com</i> configured are mail addresses that belongs to the same users.</p> |
| <p>Here are some sample commands for managing users when virtual hosting is turned off:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} AddUser user password |
| {cli} RemoveUser user |
| {cli} SetPassword user password |
| </pre></div></div> |
| </section></section><section> |
| <h2><a name="Managing_mailboxes"></a>Managing mailboxes</h2> |
| <p>An administrator can perform some basic operation on user mailboxes.</p> |
| <p>Note on mailbox formatting: mailboxes are composed of three parts.</p> |
| <ul> |
| |
| <li>The namespace, indicating what kind of mailbox it is. (Shared or not?). The value for users mailboxes is #private . Note that for now no other values are supported as James do not support shared mailboxes.</li> |
| <li>The username as stated above, depending on the virtual hosting value.</li> |
| <li>And finally mailbox name. Be aware that ‘.’ serves as mailbox hierarchy delimiter.</li> |
| </ul> |
| <p>An administrator can delete all of the mailboxes of a user, which is not done automatically when removing a user (to avoid data loss):</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} DeleteUserMailboxes user@domain.tld |
| </pre></div></div> |
| |
| <p>He can delete a specific mailbox:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} DeleteMailbox #private user@domain.tld INBOX.toBeDeleted |
| </pre></div></div> |
| |
| <p>He can list the mailboxes of a specific user:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ListUserMailboxes user@domain.tld |
| </pre></div></div> |
| |
| <p>And finally can create a specific mailbox:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} CreateMailbox #private user@domain.tld INBOX.newFolder |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Adding_a_message_in_a_mailbox"></a>Adding a message in a mailbox</h2> |
| <p>The administrator can use the CLI to add a message in a mailbox. this can be done using:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ImportEml #private user@domain.tld INBOX.newFolder /full/path/to/file.eml |
| </pre></div></div> |
| |
| <p>This command will add a message having the content specified in file.eml (that needs to be at the EML format). It will get added in the INBOX.subFolder mailbox belonging to user <a class="externalLink" href="mailto:user@domain.tld">user@domain.tld</a>.</p></section><section> |
| <h2><a name="Managing_mappings"></a>Managing mappings</h2> |
| <p>A mapping is a recipient rewritting rule. There is several kind of rewritting rules:</p> |
| <ul> |
| |
| <li>address mapping: rewrite a given mail address into an other one.</li> |
| <li>regex mapping.</li> |
| </ul> |
| <p>You can manage address mapping like (redirects email from <a class="externalLink" href="mailto:fromUser@fromDomain.tld">fromUser@fromDomain.tld</a> to <a class="externalLink" href="mailto:redirected@domain.new">redirected@domain.new</a>, then deletes the mapping):</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} AddAddressMapping fromUser fromDomain.tld redirected@domain.new |
| {cli} RemoveAddressMapping fromUser fromDomain.tld redirected@domain.new |
| </pre></div></div> |
| |
| <p>You can manage regex mapping like this:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} AddRegexMapping redirected domain.new .*@domain.tld |
| {cli} RemoveRegexMapping redirected domain.new .*@domain.tld |
| </pre></div></div> |
| |
| <p>You can view mapping for a mail address:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ListUserDomainMappings user domain.tld |
| </pre></div></div> |
| |
| <p>And all mappings defined on the server:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ListMappings |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Manage_quotas"></a>Manage quotas</h2> |
| <p>Quotas are limitations on a group of mailboxes. They can limit the <b>size</b> or the <b>messages count</b> in a group of mailboxes.</p> |
| <p>James groups by defaults mailboxes by user (but it can be overridden), and labels each group with a quotaroot.</p> |
| <p>To get the quotaroot a given mailbox belongs to:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetQuotaroot #private user@domain.tld INBOX |
| </pre></div></div> |
| |
| <p>Then you can get the specific quotaroot limitations.</p> |
| <p>For the number of messages:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetMessageCountQuota quotaroot |
| </pre></div></div> |
| |
| <p>And for the storage space available:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetStorageQuota quotaroot |
| </pre></div></div> |
| |
| <p>You see the maximum allowed for these values:</p> |
| <p>For the number of messages:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetMaxMessageCountQuota quotaroot |
| </pre></div></div> |
| |
| <p>And for the storage space available:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetMaxStorageQuota quotaroot |
| </pre></div></div> |
| |
| <p>You can also specify maximum for these values.</p> |
| <p>For the number of messages:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} SetMaxMessageCountQuota quotaroot value |
| </pre></div></div> |
| |
| <p>And for the storage space available:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} SetMaxStorageQuota quotaroot value |
| </pre></div></div> |
| |
| <p>With value being an integer. Please note the use of units for storage (K, M, G). For instance:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} SetMaxStorageQuota someone@apache.org 4G |
| </pre></div></div> |
| |
| <p>Moreover, James allows to specify global maximum values, at the server level. Note: syntax is similar to what was exposed previously.</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} SetGlobalMaxMessageCountQuota value |
| {cli} GetGlobalMaxMessageCountQuota |
| {cli} SetGlobalMaxStorageQuota value |
| {cli} GetGlobalMaxStorageQuota |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Re-indexing"></a>Re-indexing</h2> |
| <p>James allow you to index your emails in a search engine, for making search faster. Both ElasticSearch and Lucene are supported.</p> |
| <p>For some reasons, you might want to re-index your mails (inconsistencies across datastore, migrations).</p> |
| <p>To re-index all mails of all mailboxes of all users, type:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} ReindexAll |
| </pre></div></div> |
| |
| <p>And for a precise mailbox:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} Reindex #private user@domain.tld INBOX |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Sieve_scripts_quota"></a>Sieve scripts quota</h2> |
| <p>James implements Sieve (RFC-5228). Your users can then writte scripts and upload them to the server. Thus they can define the desired behavior upon email reception. James defines a Sieve mailet for this, and stores Sieve scripts. You can update them via the ManageSieve protocol, or via the ManageSieveMailet.</p> |
| <p>You can define quota for the total size of Sieve scripts, per user.</p> |
| <p>Syntax is similar to what was exposed for quotas. For defaults values:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetSieveQuota |
| {cli} SetSieveQuota value |
| {cli} RemoveSieveQuota |
| </pre></div></div> |
| |
| <p>And for specific user quotas:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} GetSieveUserQuota user@domain.tld |
| {cli} SetSieveQuota user@domain.tld value |
| {cli} RemoveSieveUserQuota user@domain.tld |
| </pre></div></div> |
| </section><section> |
| <h2><a name="Switching_of_mailbox_implementation"></a>Switching of mailbox implementation</h2> |
| <p>Migration is experimental for now. You would need to customize <b>Spring</b> configuration to add a new mailbox manager with a different bean name.</p> |
| <p>You can then copy data accross mailbox managers using:</p> |
| |
| <div class="source"> |
| <div class="source"> |
| <pre>{cli} CopyMailbox srcBean dstBean |
| </pre></div></div> |
| |
| <p>You will then need to reconfigure James to use the new mailbox manager.</p></section> |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">Copyright © 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> |
