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:18 UTC
[03/21] james-project git commit: JAMES-1789 Webadmin documentation
should be exposed on the website
JAMES-1789 Webadmin documentation should be exposed on the website
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo
Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/27118d17
Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/27118d17
Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/27118d17
Branch: refs/heads/master
Commit: 27118d171fd11b1a44f3f9ef529db58ab41f5522
Parents: e3ed1ec
Author: benwa <bt...@linagora.com>
Authored: Thu Jun 8 20:25:04 2017 +0700
Committer: benwa <bt...@linagora.com>
Committed: Wed Jun 14 15:01:19 2017 +0700
----------------------------------------------------------------------
src/site/markdown/server/manage-webadmin.md | 334 +++++++++++++++++++++++
src/site/site.xml | 1 +
2 files changed, 335 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/james-project/blob/27118d17/src/site/markdown/server/manage-webadmin.md
----------------------------------------------------------------------
diff --git a/src/site/markdown/server/manage-webadmin.md b/src/site/markdown/server/manage-webadmin.md
new file mode 100644
index 0000000..04d8d07
--- /dev/null
+++ b/src/site/markdown/server/manage-webadmin.md
@@ -0,0 +1,334 @@
+Web administration for JAMES
+============================
+
+The web administration supports for now the CRUD operations on the domains,the users, their mailboxes and their quotas, as described in the following sections.
+
+**WARNING**: This API allow authentication only via the use of JWT. If not configured with JWT, an administrator should ensure an attacker can not use this API.
+
+Please also note **webadmin** is only enabled with **Guice**. You can not use it when using James with **Spring**, as the required injections are not implemented.
+
+## Administrating domains
+
+### Create a domain
+
+```
+curl -XPUT http://ip:port/domains/domainToBeCreated
+```
+
+Resource name domainToBeCreated:
+
+ - can not be null or empty
+ - can not contain '@'
+ - can not be more than 255 characters
+ - can not contain '/'
+
+Response codes:
+
+ - 204: The domain was successfully added
+ - 400: The domain name is invalid
+ - 500: Internal error while adding the domain
+
+### Delete a domain
+
+```
+curl -XDELETE http://ip:port/domains/domainToBeDeleted
+```
+
+Response codes:
+
+ - 204: The domain was successfully removed
+ - 500: Internal error while removing the domain
+
+### Test if a domain exists
+
+```
+curl -XGET http://ip:port/domains/domainName
+```
+
+Response codes:
+
+ - 204: The domain exists
+ - 404: The domain does not exist
+ - 500: Internal error while accessing the domains
+
+### Get the list of domains
+
+```
+curl -XGET http://ip:port/domains
+```
+
+Possible response:
+
+```
+{"domains":["domain1", "domain2"]}
+```
+
+Response codes:
+
+ - 200: The domain list was successfully retrieved
+ - 500: Internal error while accessing the domains
+
+## Administrating users
+
+### Create a user
+
+```
+curl -XPUT http://ip:port/users/usernameToBeUsed -d '{"password":"passwordToBeUsed"}'
+```
+
+Resource name usernameToBeUsed:
+
+ - can not be null or empty
+ - can not be more than 255 characters
+ - can not contain '/'
+
+Response codes:
+
+ - 204: The user was successfully created
+ - 400: The user name or the payload is invalid
+ - 409: Conflict: A concurrent modification make that query to fail
+ - 500: Internal error while adding the user
+
+Note: if the user is already, its password will be updated.
+
+### Updating a user password
+
+Same than Create, but a user need to exist.
+
+If the user do not exist, then it will be created.
+
+### Deleting a user
+
+```
+curl -XDELETE http://ip:port/users/userToBeDeleted
+```
+
+Response codes:
+
+ - 204: The user was successfully deleted
+ - 500: Internal error while deleting the user
+
+### Retrieving the user list
+
+```
+curl -XGET http://ip:port/users
+```
+
+The answer looks like:
+
+```
+[{"username":"username@domain-jmapauthentication.tld"},{"username":"username@domain.tld"}]
+```
+
+Response codes:
+
+ - 200: The user name list was successfully retrieved
+ - 500: Internal error while retrieving the users
+
+## Administrating user mailboxes
+
+### Creating a mailbox
+
+```
+curl -XPUT http://ip:port/users/usernameToBeUsed/mailboxes/mailboxNameToBeCreated
+```
+
+Resource name usernameToBeUsed should be an existing user
+Resource name mailboxNameToBeCreated should not be empty, nor contain # & % * characters.
+
+Response codes:
+
+ - 204: The mailbox now exists on the server
+ - 400: Invalid mailbox name
+ - 404: The user name does not exist
+ - 500: Internal error
+
+ To create nested mailboxes, for instance a work mailbox inside the INBOX mailbox, people should use the . separator. The sample query is:
+
+```
+curl -XDELETE http://ip:port/users/usernameToBeUsed/mailboxes/INBOX.work
+```
+
+### Deleting a mailbox and its children
+
+```
+curl -XDELETE http://ip:port/users/usernameToBeUsed/mailboxes/mailboxNameToBeCreated
+```
+
+Resource name usernameToBeUsed should be an existing user
+Resource name mailboxNameToBeCreated should not be empty
+
+Response codes:
+
+ - 204: The mailbox now does not exist on the server
+ - 400: Invalid mailbox name
+ - 404: The user name does not exist
+ - 500: Internal error
+
+### Testing existence of a mailbox
+
+```
+curl -XGET http://ip:port/users/usernameToBeUsed/mailboxes/mailboxNameToBeCreated
+```
+
+Resource name usernameToBeUsed should be an existing user
+Resource name mailboxNameToBeCreated should not be empty
+
+Response codes:
+
+ - 204: The mailbox exists
+ - 400: Invalid mailbox name
+ - 404: The user name does not exist, the mailbox does not exist
+ - 500: Internal error
+
+### Listing user mailboxes
+
+```
+curl -XGET http://ip:port/users/usernameToBeUsed/mailboxes
+```
+
+The answer looks like:
+
+```
+[{"mailboxName":"INBOX"},{"mailboxName":"outbox"}]
+```
+
+Resource name usernameToBeUsed should be an existing user
+
+Response codes:
+
+ - 200: The mailboxes list was successfully retrieved
+ - 404: The user name does not exist
+ - 500: Internal error
+
+### Deleting user mailboxes
+
+```
+curl -XDELETE http://ip:port/users/usernameToBeUsed/mailboxes
+```
+
+Resource name usernameToBeUsed should be an existing user
+
+Response codes:
+
+ - 204: The user do not have mailboxes anymore
+ - 404: The user name does not exist
+ - 500: Internal error
+
+## Administrating quotas
+
+A quota with a value of -1 means unlimited
+
+### Reading per quotaroot mail count limitation
+
+```
+curl -XGET http://ip:port/quota/count
+```
+
+The answer looks like:
+
+```
+100000
+```
+
+Response codes:
+ - 200: Nothing special
+ - 500: Internal error
+
+### Updating per quotaroot mail count limitation
+
+```
+curl -XPUT http://ip:port/quota/count -d '1024000000'
+```
+
+Response codes:
+
+ - 204: Value updated
+ - 400: The body is not a positive integer
+ - 500: Internal error
+
+### Removing per quotaroot mail count limitation
+
+It removes the limitation, and the quota becomes UNILIMITED.
+
+```
+curl -XDELETE http://ip:port/quota/count
+```
+
+Response codes:
+
+ - 204: Value updated to UNLIMITED
+ - 500: Internal error
+
+### Reading per quotaroot size limitation
+
+```
+curl -XGET http://ip:port/quota/size
+```
+
+The answer looks like:
+
+```
+100000
+```
+
+It represent the allowed Byte count of the mailboxes belonging to this quotaroot.
+
+Response codes:
+
+ - 200: Nothing special
+ - 500: Internal error
+
+### Updating per quotaroot size limitation
+
+```
+curl -XPUT http://ip:port/quota/size -d '1024000000'
+```
+
+Response codes:
+
+ - 204: Value updated
+ - 400: The body is not a positive integer
+ - 500: Internal error
+
+### Removing per quotaroot size limitation
+
+It removes the limitation, and the quota becomes UNILIMITED.
+
+```
+curl -XDELETE http://ip:port/quota/size
+```
+
+Response codes:
+
+ - 204: Value updated to UNLIMITED
+ - 500: Internal error
+
+### Managing count and size at the same time
+
+```
+curl -XGET http://ip:port/quota/
+```
+
+Will return:
+
+```
+{"count":52,"size":42}
+```
+
+Response codes:
+
+ - 200: Success
+ - 500: Internal error
+
+You can also write the value the same way:
+
+```
+curl -XPUT http://ip:port/quota/ -d '{"count":52,"size":42}'
+```
+
+Response codes:
+
+ - 204: Success
+ - 400: Invalid JSON, or numbers are less than -1.
+ - 500: Internal error
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/james-project/blob/27118d17/src/site/site.xml
----------------------------------------------------------------------
diff --git a/src/site/site.xml b/src/site/site.xml
index 2d823ca..ba4d2bb 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -141,6 +141,7 @@
<item name="Users" href="/server/manage-users.html" />
<item name="Recipient Rewrite" href="/server/manage-recipientrewrite.html" />
<item name="Metrics" href="/server/metrics.html" />
+ <item name="Metrics" href="/server/manage-webadmin.html" />
</item>
<item name="5. Monitor" href="/server/monitor.html" collapse="true" >
<item name="Logging" href="/server/monitor-logging.html" />
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org