You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2017/06/14 08:06:21 UTC
[06/21] james-project git commit: JAMES-1789 Consolidate management
instructions
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 <bt...@linagora.com>
Authored: Thu Jun 8 22:53:07 2017 +0700
Committer: benwa <bt...@linagora.com>
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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org