JAMES-1789 Consolidate management instructions
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/7c69293d Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/7c69293d Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/7c69293d Branch: refs/heads/master Commit: 7c69293d14354fcd0b6b547ae5d5f8b7988e9941 Parents: e727103 Author: benwa <[email protected]> Authored: Thu Jun 8 22:53:07 2017 +0700 Committer: benwa <[email protected]> Committed: Wed Jun 14 15:01:30 2017 +0700 ---------------------------------------------------------------------- src/site/site.xml | 3 - src/site/xdoc/server/manage-domains.xml | 67 ------ src/site/xdoc/server/manage-jmx.xml | 99 +++++++++ .../xdoc/server/manage-recipientrewrite.xml | 203 ------------------- src/site/xdoc/server/manage-users.xml | 66 ------ src/site/xdoc/server/manage.xml | 86 +------- 6 files changed, 106 insertions(+), 418 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/site.xml ---------------------------------------------------------------------- diff --git a/src/site/site.xml b/src/site/site.xml index e511b1a..aca55d8 100644 --- a/src/site/site.xml +++ b/src/site/site.xml @@ -137,9 +137,6 @@ <item name="Events" href="/server/config-events.html" /> </item> <item name="4. Manage" href="/server/manage.html" collapse="true" > - <item name="Domains" href="/server/manage-domains.html" /> - <item name="Users" href="/server/manage-users.html" /> - <item name="Recipient Rewrite" href="/server/manage-recipientrewrite.html" /> <item name="WebAdmin" href="/server/manage-webadmin.html" /> <item name="Command line" href="/server/manage-cli.html" /> <item name="Metrics" href="/server/metrics.html" /> http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/xdoc/server/manage-domains.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/manage-domains.xml b/src/site/xdoc/server/manage-domains.xml deleted file mode 100644 index 22a1dc5..0000000 --- a/src/site/xdoc/server/manage-domains.xml +++ /dev/null @@ -1,67 +0,0 @@ -<?xml version="1.0"?> -<!-- - 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. ---> -<document> - - <properties> - <title>Apache James Server 3 - Manage Domains</title> - </properties> - -<body> - - <section name="Manage Domains"> - - <p>Domain accounts are shared across services. A common Domain repository is shared across James - services. That is, once you've created a POP3 mail and set a password, that same - is available for authenticated SMTP and NNTP.</p> - - <p>If you have JPADomainList (default setup), you can add, delete and list the domains.</p> - - <p>If you have XMLDomainList for example, you can only list the available domains. To add a domain, - you must add it in the domainlist.xml file.</p> - - </section> - - <section name="Manage Domains via Cli"> - - <p>Invoke "james-cli.sh adddomain <mydomain.tls> <mydomain.tls> is the domain name - of the domain you wish to create.</p> - - <p>That's it. Your domains are now created and can be used by all James services.</p> - - </section> - - <section name="Manage Domains via JMX"> - - <p>Use and JMX client to access the DomainList management function.</p> - - <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> - - <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> - - <p>If you want a remote access, you can install a web application management tool such as jmanage. - You will get screens such as the following one.</p> - - <p><img src="images/jmx-management/jmx-domainlist.png"/></p> - - </section> - -</body> - -</document> http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/xdoc/server/manage-jmx.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/manage-jmx.xml b/src/site/xdoc/server/manage-jmx.xml new file mode 100644 index 0000000..65aab55 --- /dev/null +++ b/src/site/xdoc/server/manage-jmx.xml @@ -0,0 +1,99 @@ +<?xml version="1.0"?> +<!-- + 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. +--> +<document> + + <properties> + <title>Apache James Server 3 - Manage Domains</title> + </properties> + + <body> + + <section name="Manage via JMX"> + + <p>James can be managed via JMX.</p> + + <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> + + <p><code>service:jmx:rmi://localhost/jndi/rmi://localhost:999/jmxrmi </code></p> + + <p>Simply launch jconsole to access the exposed attributes and methods.</p> + + <p>If you want a remote access, change 'localhost' to your server hostname in the previous URL:</p> + + <p><code>service:jmx:rmi://localhost/jndi/rmi://localhost:999/jmxrmi </code></p> + + <p>To manage through a firewall, you will have to take care to random ports creation (read + <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html";>JMX agent</a> + , + <a href="http://olegz.wordpress.com/2009/03/23/jmx-connectivity-through-the-firewall";>JMX through firewall</a> + and + <a href="http://blogs.law.harvard.edu/hoanga/2006/07/07/getting-java-jmx-to-work-through-firewalls-properly";>Getting Java JMX to work through firewalls properly</a>. + </p> + + <p>You can install a web application management tool such as jmanage. + You will get screens such as the following one.</p> + + <p><img src="images/jmx-management/jmx-domainlist.png"/></p> + + </section> + + <section name="Manage Domains via JMX"> + + <p>Use a JMX client to access the DomainList management function.</p> + + <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> + + <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> + + <p>If you want a remote access, you can install a web application management tool such as jmanage. + You will get screens such as the following one.</p> + + <p><img src="images/jmx-management/jmx-domainlist.png"/></p> + + </section> + + <section name="Manage Users via JMX"> + + <p>Use and JMX client to access the Users management function.</p> + + <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> + + <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> + + <p>If you want a remote access, you can install a web application management tool such as jmanage. + You will get screens such as the following one.</p> + + <p><img src="images/jmx-management/jmx-user.png"/></p> + + </section> + + <section name="Manage Virtual Users via JMX"> + + <p>Use and JMX client to access the Virtual User management function.</p> + + <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> + + <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> + + </section> + + </body> + +</document> \ No newline at end of file http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/xdoc/server/manage-recipientrewrite.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/manage-recipientrewrite.xml b/src/site/xdoc/server/manage-recipientrewrite.xml deleted file mode 100644 index 08abc4d..0000000 --- a/src/site/xdoc/server/manage-recipientrewrite.xml +++ /dev/null @@ -1,203 +0,0 @@ -<?xml version="1.0"?> -<!-- - 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. ---> -<document> - - <properties> - <title>Apache James Server 3 - Manage Recipient Rewrite Table</title> - </properties> - -<body> - - <section name="Manage Recipient Rewrite"> - - <p>To rewrite recipients, you need to create some "mappings".</p> - - <p>You will rewrite any recipient to an existing or a non-existing server account.</p> - - <p>So read "mapping allows to rewrite a 'fromAny(Existing/NotExisting) user and/or domain' to a 'toAny(Existing/NotExisting)Account'".</p> - - <p>'An existing account' means an account defined in the Apache James Server.</p> - - <p>You can also use regular expressions and wildcards (*) for the 'fromAny'.</p> - - <p>The available methods exposed in the management interface are the following:</p> - - <source> - /** - * Add regex mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param regex - * the regex. - */ - void addRegexMapping(String user, String domain, String regex) throws Exception; - - /** - * Remove regex mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param regex - * the regex. - */ - void removeRegexMapping(String user, String domain, String regex) throws Exception; - - /*** - * Add address mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param address - * the address. - */ - void addAddressMapping(String user, String domain, String address) throws Exception; - - /** - * Remove address mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param address - */ - void removeAddressMapping(String user, String domain, String address) throws Exception; - - /** - * Add error mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param error - */ - void addErrorMapping(String user, String domain, String error) throws Exception; - - /** - * Remove error mapping - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param error - * @return true if successfully - */ - void removeErrorMapping(String user, String domain, String error) throws Exception; - - /** - * Add domain mapping - * - * @param domain - * the domain. Null if no domain should be used - * @param targetDomain - * the target domain for the mapping - * @return true if successfully - */ - void addDomainMapping(String domain, String targetDomain) throws Exception; - - /** - * Remove domain mapping - * - * @param domain - * the domain. Null if no domain should be used - * @param targetDomain - * the target domain for the mapping - * - * @return true if successfully - */ - void removeDomainMapping(String domain, String targetDomain) throws Exception; - - /** - * Return the explicit mapping stored for the given user and domain. Return - * null if no mapping was found - * - * @param user - * the username - * @param domain - * the domain - * @return the collection which holds the mappings. - */ - Collection<String> getUserDomainMappings(String user, String domain) throws Exception; - - /** - * Try to identify the right method based on the prefix of the mapping and - * add it. - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param mapping - * the mapping. - */ - void addMapping(String user, String domain, String mapping) throws Exception; - - /** - * Try to identify the right method based on the prefix of the mapping and - * remove it. - * - * @param user - * the username. Null if no username should be used - * @param domain - * the domain. Null if no domain should be used - * @param mapping - * the mapping. - */ - void removeMapping(String user, String domain, String mapping) throws Exception; - - /** - * Return a Map which holds all mappings. The key is the user@domain and the - * value is a Collection which holds all mappings - * - * @return Map which holds all mappings - */ - Map<String, Collection<String>> getAllMappings() throws Exception; - </source> - - </section> - - <section name="Manage Recipient Rewrite Table via Cli"> - - <p>Not available in this release.</p> - - </section> - - <section name="Manage Virtual Users via JMX"> - - <p>Use and JMX client to access the Virtual User management function.</p> - - <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> - - <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> - - </section> - -</body> - -</document> http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/xdoc/server/manage-users.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/manage-users.xml b/src/site/xdoc/server/manage-users.xml deleted file mode 100644 index 85b6d1f..0000000 --- a/src/site/xdoc/server/manage-users.xml +++ /dev/null @@ -1,66 +0,0 @@ -<?xml version="1.0"?> -<!-- - 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. ---> -<document> - - <properties> - <title>Apache James Server 3 - Manage Users</title> - </properties> - -<body> - - <section name="Manage Users"> - - <p>User accounts are shared across services. A common user repository is shared across James - services. That is, once you've created a POP3 mail account and set a password, that same - account is available for authenticated SMTP and NNTP.</p> - - </section> - - <section name="Manage Users via Cli"> - - <p>Invoke "james-cli.sh adduser <user> <password>" where <user> is the user name - and <password> 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 <user>@<domain> - (where <domain> is any of the values specified in the <servernames> block of XMLDomainList or - a domain defined via the <a href="manage-domains.html">domain management</a>).</p> - - <p>That's it. Your users are now created and can be used by all James services.</p> - - </section> - - <section name="Manage Users via JMX"> - - <p>Use and JMX client to access the Users management function.</p> - - <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> - - <p><code>service:jmx:rmi:///jndi/rmi://localhost:9999/jmxrmi</code></p> - - <p>If you want a remote access, you can install a web application management tool such as jmanage. - You will get screens such as the following one.</p> - - <p><img src="images/jmx-management/jmx-user.png"/></p> - - </section> - -</body> - -</document> http://git-wip-us.apache.org/repos/asf/james-project/blob/7c69293d/src/site/xdoc/server/manage.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/manage.xml b/src/site/xdoc/server/manage.xml index 8d5025c..5904174 100644 --- a/src/site/xdoc/server/manage.xml +++ b/src/site/xdoc/server/manage.xml @@ -26,8 +26,7 @@ <body> <section name="Manage James Server"> -<!-- ---> + <p>You need to make sure that your user/domain/mail repository configuration is correct before managing. If you change your user/domain/mail repository type (i.e. file to database) or the configuration of your user repository (i.e. the file or database URL) after you have added user/domain/mail, you may lose your user/domain/mail data. Please change these @@ -36,85 +35,14 @@ <p>After you've done this, restart James to ensure that any changes you've made in the configuration are incorporated into the running system.</p> - <p>You are now ready to manage <a href="manage-domains.html">Domains</a>, - <a href="manage-users.html">Users</a> and <a href="manage-recipientrewrite.html">Recipient Rewrite Table</a>.</p> - - <p>You can manage James via:</p> - - <ol> - <li><a href="#Manage_via_CLI">CLI (Client Line Interface)</a></li> - <li><a href="#Manage_via_JMX">JMX (Java Management Extension)</a></li> - </ol> - - <subsection name="Manage via CLI"> - - <p>Once James is up and listening, managing via the command line interface is simple.</p> - - <p>cd bin</p> - - <p>./james-cli.sh (or james-cli.bat on windows) ./james-cli.sh -h localhost -p 9999</p> - - <p>You will be shown with a list of commands.</p> + <p>You are now ready to manage Some internal James data-structure.</p> - <source> - usage: java org.apache.james.cli.ServerCmd --host <arg> <command> - -h,--host </arg> node hostname or ip address - -p,--port </arg> remote jmx agent port number - Available commands: - adduser </username> </password> - removeuser </username> - listusers - adddomain </domainname> - removedomain </domainname> - listdomains - containsdomain - </source> - - <p>Note the address and port defined in conf/jmx.properties (default is jmx.address=127.0.0.1 and jmx.port=9999)</p> - - </subsection> - - <subsection name="Manage via JMX"> - - <p>James can be managed via JMX.</p> - - <p>The managed objects are exposed from localhost only (for security reasons) on the following URL:</p> - - <p><code>service:jmx:rmi://localhost/jndi/rmi://localhost:999/jmxrmi </code></p> - - <p>Simply launch jconsole to access the exposed attributes and methods.</p> -<!-- - <div class="ui-widget"> - <div class="ui-state-error ui-corner-all" style="padding: 0 .7em;"> - <p><span class="ui-icon ui-icon-alert" style="float: left; margin-right: .3em;"></span> - <strong>JMX on Windows:</strong> - to let windows start with jmx username/password enabled, - you need to modify the security settings for the jmx files like descripted here: - <a href="http://download.oracle.com/javase/1.5.0/docs/guide/management/security-windows.html";> - http://download.oracle.com/javase/1.5.0/docs/guide/management/security-windows.html</a> - </p> - </div> - </div> ---> - <p>If you want a remote access, change 'localhost' to your server hostname in the previous URL:</p> - - <p><code>service:jmx:rmi://localhost/jndi/rmi://localhost:999/jmxrmi </code></p> - - <p>To manage through a firewall, you will have to take care to random ports creation (read - <a href="http://docs.oracle.com/javase/6/docs/technotes/guides/management/agent.html";>JMX agent</a> - , - <a href="http://olegz.wordpress.com/2009/03/23/jmx-connectivity-through-the-firewall";>JMX through firewall</a> - and - <a href="http://blogs.law.harvard.edu/hoanga/2006/07/07/getting-java-jmx-to-work-through-firewalls-properly";>Getting Java JMX to work through firewalls properly</a>. - </p> - - <p>You can install a web application management tool such as jmanage. - You will get screens such as the following one.</p> - - <p><img src="images/jmx-management/jmx-domainlist.png"/></p> + <ul>You can do this: + <li>Using <a href="manage-cli.html">The command line client</a></li> + <li>Using <a href="manage-webadmin.html">The web REST interface</a> (Guice only)</li> + <li>Using <a href="manage-jmx.html">The JMX interface</a> (Experimental)</li> + </ul> - </subsection> - </section> </body> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
