This is an automated email from the ASF dual-hosted git repository. btellier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 170bf0dcc277210a159bddea90986cf5b14be26e Author: QuanTH <[email protected]> AuthorDate: Mon Oct 5 16:47:19 2020 +0700 JAMES-3400 Add README.md for James CLI based on webadmin endpoints. --- server/protocols/webadmin-cli/README.md | 126 ++++++++++++++++++++++++++++ src/adr/0042-james-cli-based-on-webadmin.md | 7 +- 2 files changed, 130 insertions(+), 3 deletions(-) diff --git a/server/protocols/webadmin-cli/README.md b/server/protocols/webadmin-cli/README.md new file mode 100644 index 0000000..3b4e5d0 --- /dev/null +++ b/server/protocols/webadmin-cli/README.md @@ -0,0 +1,126 @@ +# A WebAdmin based CLI for Apache James + +## Development + +Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface. It also aims at providing a more modern and intuitive interface. + +## Run the command line + +## Syntax + +General syntax to run the command line + +``` +$ james-cli [OPTION] ENTITY ACTION {ARGUMENT} +``` + +where + + OPTION: optional parameter when running the command line, + + ENTITY: represents the entity to perform action on, + + ACTION: name of the action to perform, + + ARGUMENT: arguments needed for the action. + +Example: +``` +$ james-cli --url http://127.0.0.1 --port 9999 domain list +``` + +The above command lists all domain names available on domain route at address http://127.0.0.1:9999. +It does not require any argument to execute. Options --url and --port are optional. Without them, the default value is http://127.0.0.0:8000. +As for other commands, arguments might be required after the sub-command (ACTION such as list, add and remove). + +## Navigation menu + +- [Manage Domains](#manage-domains) + - [Create a domain](#create-a-domain) + - [Delete a domain](#delete-a-domain) + - [Check if a domain exists](#check-if-a-domain-exists) + - [Get the list of domains](#get-the-list-of-domains) +- [Manage Users](#manage-users) + - [Create an user](#create-a-user) + - [Test an user existence](#test-a-user-existence) + - [Delete an user](#delete-a-user) + - [Get users list](#get-users-list) + - [Update an user password](#update-a-user-password) + +## Manage Domains + +### Create a domain +Add a domain to the domain list. +``` +james-cli domain create <domainToBeCreated> +``` +Resource name **domainToBeCreated**: + +- can not be null or empty +- can not contain ‘@’ +- can not be more than 255 characters +- can not contain ‘/’ + +### Delete a domain + +Remove a domain from the domain list. +``` +james-cli domain delete <domainToBeDeleted> +``` +Note: Deletion of an auto-detected domain, default domain or of an auto-detected ip is not supported. We encourage you instead to review your [domain list configuration](https://james.apache.org/server/config-domainlist.html). + +### Check if a domain exists +Check whether a domain exists on the domain list or not. +``` +james-cli domain exist <domainToBeChecked> +``` + +### Get the list of domains +Show all domains' name on the list. +``` +james-cli domain list +``` + + + +## Manage Users + +### Create an user + +Add an user to the user list. +``` +james-cli user create <username> <password> +``` +Resource name <username> representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) + +Note: if the user exists already, its password will be updated. + +### Test an user existence + +Check whether an user exists on the user list or not. +``` +james-cli user exist <username> +``` +Resource name <username> representing valid users, hence it should match the criteria at [User Repositories documentation](https://james.apache.org/server/config-users.html) + +### Delete an user + +Remove an user from the user list. +``` +james-cli user delete <username> +``` + +### Get users list + +Show all users' name on the list. + +``` +james-cli user list +``` + +### Update an user password +Same as Create, but an user need to exist. + +If the user do not exist, then it will be created. + + diff --git a/src/adr/0042-james-cli-based-on-webadmin.md b/src/adr/0042-james-cli-based-on-webadmin.md index d7d0061..52b1c9d 100644 --- a/src/adr/0042-james-cli-based-on-webadmin.md +++ b/src/adr/0042-james-cli-based-on-webadmin.md @@ -43,7 +43,7 @@ We decided to write a new CLI client, running on top of the JVM, communicating w * We decided to adopt a more modern, modular CLI syntax: ``` -$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT} +$ james-cli [OPTION] ENTITY ACTION {ARGUMENT} ``` where @@ -59,7 +59,7 @@ where Add a domain to the domain list. ``` -$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated +$ james-cli --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated ``` In above command-line @@ -80,4 +80,5 @@ It aims at providing a more modern and more secure CLI, also bringing compatibil ## References * [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628) * [Picocli 2.0: Do More With Less](https://dzone.com/articles/whats-new-in-picocli-20) -* [Picocli Homepage](https://picocli.info/) \ No newline at end of file +* [Picocli Homepage](https://picocli.info/) +* [Native Image Maven Plugin](https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/) \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
