Adds disclaimer about Maven coords URL formation and details about lo…

…cal zip files (#1054) (#1080) * Added guidance about zip syntax differences between local and remote files Signed-off-by: JeffH-AWS <[email protected]> * Added disclaimer about Maven Signed-off-by: JeffH-AWS <[email protected]> * Added disclaimer about protocols Signed-off-by: JeffH-AWS <[email protected]> * Caught a small typo and fixed it Signed-off-by: JeffH-AWS <[email protected]> Signed-off-by: JeffH-AWS <[email protected]> (cherry picked from commit dfa4776) Co-authored-by: Jeff Huss <[email protected]>
opensearch-project · Sep 1, 2022 · 8a306d5 · 8a306d5
1 parent f4c9877
commit 8a306d5
Showing 1 changed file with 29 additions and 2 deletions.
diff --git a/_opensearch/install/plugins.md b/_opensearch/install/plugins.md
@@ -80,15 +80,16 @@ $ sudo ./opensearch-plugin install analysis-icu
 
 ### Install a plugin from a zip file:
 
+Remote zip files can be installed by replacing `<zip-file>` with the URL of the hosted file. The tool only supports downloading over HTTP/HTTPS protocols. For local zip files, replace `<zip-file>` with `file:` followed by the absolute or relative path to the plugin zip file as in the second example below.
+
 #### Usage:
 ```bash
-# zip-file can be a local path to the zip file, or
-# a URL for a zip file hosted on a network.
 bin/opensearch-plugin install <zip-file>
 ```
 
 #### Example:
 ```bash
+# Zip file is hosted on a remote server - in this case, Maven central repository.
 $ sudo ./opensearch-plugin install https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
 -> Installing https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
 -> Downloading https://repo1.maven.org/maven2/org/opensearch/plugin/opensearch-anomaly-detection/2.2.0.0/opensearch-anomaly-detection-2.2.0.0.zip
@@ -109,12 +110,38 @@ $ sudo ./opensearch-plugin install https://repo1.maven.org/maven2/org/opensearch
 See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
 for descriptions of what these permissions allow and the associated risks.
 
+Continue with installation? [y/N]y
+-> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection
+
+# Zip file in a local directory.
+$ sudo ./opensearch-plugin install file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
+-> Installing file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
+-> Downloading file:/home/user/opensearch-anomaly-detection-2.2.0.0.zip
+[=================================================] 100%   
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+@     WARNING: plugin requires additional permissions     @
+@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
+* java.lang.RuntimePermission accessClassInPackage.sun.misc
+* java.lang.RuntimePermission accessDeclaredMembers
+* java.lang.RuntimePermission getClassLoader
+* java.lang.RuntimePermission setContextClassLoader
+* java.lang.reflect.ReflectPermission suppressAccessChecks
+* java.net.SocketPermission * connect,resolve
+* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] registerMBean
+* javax.management.MBeanPermission org.apache.commons.pool2.impl.GenericObjectPool#-[org.apache.commons.pool2:name=pool,type=GenericObjectPool] unregisterMBean
+* javax.management.MBeanServerPermission createMBeanServer
+* javax.management.MBeanTrustPermission register
+See http://docs.oracle.com/javase/8/docs/technotes/guides/security/permissions.html
+for descriptions of what these permissions allow and the associated risks.
+
 Continue with installation? [y/N]y
 -> Installed opensearch-anomaly-detection with folder name opensearch-anomaly-detection
 ```
 
 ### Install a plugin using Maven coordinates:
 
+The `opensearch-plugin install` tool also accepts Maven coordinates for available artifacts and versions hosted on [Maven Central](https://search.maven.org/search?q=org.opensearch.plugin). `opensearch-plugin` will parse the Maven coordinates you provide and construct a URL. As a result, the host must be able to connect directly to [Maven Central](https://search.maven.org/search?q=org.opensearch.plugin). The plugin installation will fail if you pass coordinates to a proxy or local repository.
+
 #### Usage:
 ```bash
 bin/opensearch-plugin install <groupId>:<artifactId>:<version>