You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by GitBox <gi...@apache.org> on 2020/10/05 08:34:40 UTC
[GitHub] [james-project] quantranhong1999 opened a new pull request #251: JAMES-3400 ADR for James CLI based on webadmin endpoints
quantranhong1999 opened a new pull request #251:
URL: https://github.com/apache/james-project/pull/251
ADR for James CLI based on webadmin endpoints.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500899105
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
Can we replace `java -jar james_cli.jar` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain list
Review comment:
Can we replace `java -jar james_cli.jar` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
Review comment:
Remove this note
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+{cli} domain list
+```
+
+
+
+## Manage Users
+
+### Create an user
+
+Add an user to the user list.
+```
+{cli} user create <username> <password>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+{cli} domain list
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{cli} domain create <domainToBeCreated>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{cli} domain delete <domainToBeDeleted>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+{cli} domain list
+```
+
+
+
+## Manage Users
+
+### Create an user
+
+Add an user to the user list.
+```
+{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.
+```
+{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.
+```
+{cli} user delete <username>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+{cli} domain list
+```
+
+
+
+## Manage Users
+
+### Create an user
+
+Add an user to the user list.
+```
+{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.
+```
+{cli} user exist <username>
Review comment:
Can we replace `{cli}` by `james-cli` ?
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [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:
+```
+$ java -jar james_cli.jar --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).
+
+Note: the command line ```$ java -jar james_cli.jar``` will be shorten as {cli} from here.
+
+## 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.
+```
+{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.
+```
+{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.
+```
+{cli} domain exist <domainToBeChecked>
+```
+
+### Get the list of domains
+Show all domains' name on the list.
+```
+{cli} domain list
+```
+
+
+
+## Manage Users
+
+### Create an user
+
+Add an user to the user list.
+```
+{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.
+```
+{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.
+```
+{cli} user delete <username>
+```
+
+### Get users list
+
+Show all users' name on the list.
+
+```
+{cli} user list
Review comment:
Can we replace `{cli}` by `james-cli` ?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on pull request #251:
URL: https://github.com/apache/james-project/pull/251#issuecomment-704773612
> write a man page (asciidoc can generate it for you)
Picocli generates beautiful documentation for your application (HTML, PDF and Unix man pages)
Will be easy, let's add the mention!
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] quantranhong1999 commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
quantranhong1999 commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500904778
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
done it
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on pull request #251:
URL: https://github.com/apache/james-project/pull/251#issuecomment-703531762
Please can you add the ticket number as a prefix?
`JAMES-3400 the rest of the message`
You can do that with rebase + reword
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500898662
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,83 @@
+# 42. James CLI based on webadmin API
+
+Date: 2020-10-05
+
+## Status
+
+Accepted (lazy consensus).
+
+## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework written in Java that allows us to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: no need to the follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* Distribute this CLI as a GraalVM native image.
+
+* Write a man page.
+
+ * Picocli generates beautiful documentation for our CLI (HTML, PDF and Unix man pages).
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [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.
+
+#### Examples
+
+Add a domain to the domain list.
+```
+$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated
+```
+
+In above command-line
+
+ OPTION: --url http://127.0.0.1 --port 9999
+
+ ENTITY: domain
+
+ ACTION: create
+
+ ARGUMENT: domainNameToBeCreated
+
+
+## Consequences
+
+It aims at providing a more modern and more secure CLI, also bringing compatibility ability with old CLI.
+
+## 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/)
Review comment:
Can we add this reference? https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,83 @@
+# 42. James CLI based on webadmin API
+
+Date: 2020-10-05
+
+## Status
+
+Accepted (lazy consensus).
+
+## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework written in Java that allows us to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: no need to the follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* Distribute this CLI as a GraalVM native image.
+
+* Write a man page.
+
+ * Picocli generates beautiful documentation for our CLI (HTML, PDF and Unix man pages).
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [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.
+
+#### Examples
+
+Add a domain to the domain list.
+```
+$ java -jar james_cli.jar --url http://127.0.0.1 --port 9999 domain create domainNameToBeCreated
Review comment:
Here too, replace `java -jar james_cli.jar` by `james-cli`
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
Quan can you replace `java -jar james_cli.jar` by `james-cli` ?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500817673
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
What do you propose instead?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] Arsnael commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
Arsnael commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r499497161
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
Review comment:
Remove that extra space before `##`
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
Review comment:
```suggestion
* CLI: ***Picocli library***. Picocli is a one-file command line parsing framework written in Java that allows us to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: no need to follow the order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
```
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
Review comment:
Skip a line between the date and title, for readability
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on pull request #251:
URL: https://github.com/apache/james-project/pull/251#issuecomment-705336559
Merged
Quan, can you close this?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500821513
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
Review comment:
Agree with distributing this CLI as a GraalVM native image :+1:
Looks easily achievable https://www.graalvm.org/reference-manual/native-image/NativeImageMavenPlugin/
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500817496
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
Review comment:
IMO that's a promotion that could come later
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500818119
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
Review comment:
Later ADRs can superseed this and overide the original choice?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r501384630
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
Review comment:
It is related to webadmin, having it close to webadmin feels natural to me.
Putting something that is not (yet) the official cli in an official cli place might be confusing. I would defer that choice.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500821709
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
Ok, graalVM allows to avoid that
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] quantranhong1999 closed pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
quantranhong1999 closed pull request #251:
URL: https://github.com/apache/james-project/pull/251
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on pull request #251:
URL: https://github.com/apache/james-project/pull/251#issuecomment-705336559
Merged
Quan, can you close this?
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] quantranhong1999 closed pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
quantranhong1999 closed pull request #251:
URL: https://github.com/apache/james-project/pull/251
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] mbaechler commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
mbaechler commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r501331783
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
Review comment:
could you argue about putting it inside server/protocols? I can't find any rational for that.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] mbaechler commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
mbaechler commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r501332173
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
Review comment:
It's just too many details, as far as I know we never wrote an ADR about our libraries choices.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] mbaechler commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
mbaechler commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500807436
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
Review comment:
Do you intend to make it buildable with GraalVM native image in order to make the adoption easier and have decent start performance?
It's a matter of avoiding not-supported stuff but for a CLI it should be doable.
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
Review comment:
I think it's not wise to list libraries here as it's an implementation detail and it would require a new ADT to modify them is people find that the choices validated here don't work as expected.
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
+
+* We decided to adopt a more modern, modular CLI syntax:
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
oh no, please drop this `java -jar ...` thing
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
+
+* Where will we locate this cli code?
+
+ * server/protocols/webadmin-cli
Review comment:
This doesn't make sense to me: it's not part of the server, it's a standalone app.
What about `app/cli`?
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
Review comment:
good idea :+1:
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500897579
##########
File path: server/protocols/webadmin-cli/README.md
##########
@@ -0,0 +1,128 @@
+# 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
+
+```
+$ java -jar james_cli.jar [OPTION] ENTITY ACTION {ARGUMENT}
Review comment:
Replace `java -jar james_cli.jar` by `james-cli`
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org
[GitHub] [james-project] chibenwa commented on a change in pull request #251: [ADR] JAMES-3400 James CLI based on webadmin endpoints
Posted by GitBox <gi...@apache.org>.
chibenwa commented on a change in pull request #251:
URL: https://github.com/apache/james-project/pull/251#discussion_r500816896
##########
File path: src/adr/0042-james-cli-based-on-webadmin.md
##########
@@ -0,0 +1,75 @@
+# 42. James CLI based on webadmin API
+Date: 2020-10-05
+
+## Status
+Accepted (lazy consensus).
+
+ ## Context
+
+James servers offer a command-line interface in order to interact with the server. However, it relies on the JMX protocol, which is known to be insecure. The JMX server embedded in Apache James, also used by the command line client is exposed to a java de-serialization issue according to [NVD-CVE-2017-12628 Detail](https://nvd.nist.gov/vuln/detail/CVE-2017-12628), and thus can be used to execute arbitrary commands.
+
+Besides, the current CLI interface is also not optimal for users. It places actions in front of entities with contiguous syntax, making it harder for the user to remember the command (for example, which entity the GET action command can interact with). If we design to place the entity first and the outgoing actions can interact with that entity afterward, the user will easily imagine what he/she can do with each entity. This creates an intuitive interface that is easier to remember.
+
+Webadmin APIs use HTTP protocol, which is more secure than JMX protocol to interact with James servers.
+
+Webadmin command-line interface is an upcoming replacement for the outdated, security-vulnerable JMX command-line interface.
+
+## Decision
+
+We decided to write a new CLI client, running on top of the JVM, communicating with James via the webadmin protocol, using http.
+
+* What libraries will we use?
+
+ * http client: ***Feign library***. We used it as an http client in other parts of James so we continue to use it.
+
+ * CLI: ***Picocli library***. Picocli is a one-file command line parsing framework writed by Java that allows we to create command line applications with almost no code. It allows mixing Options with positional Parameters (Eg: don't have to follow order Options then Parameters), [automatic type conversion](https://picocli.info/#_strongly_typed_everything) of command line arguments to the type of the annotated field, provide Automatic Help and better Subcommand Support, easily handle Exceptions.
+
+* How will we limit breaking changes this new CLI will cause?
+
+ * Work on a wrapper to adapt the old CLI API.
Review comment:
credits to @rouazana :-)
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org