Adds Windows security documentation (opensearch-project#1821)

* Adds Windows security documentation Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated tech reveiw feedback Signed-off-by: Fanit Kolchina <[email protected]> * Included powershell and removed call Signed-off-by: Fanit Kolchina <[email protected]> * Changed to backslashes Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated doc review feedback Signed-off-by: Fanit Kolchina <[email protected]> * Incorporated editorial feedback Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]>
partlov · Nov 8, 2022 · 12715e3 · 12715e3
1 parent 4d6a275
commit 12715e3
Show file tree

Hide file tree

Showing 4 changed files with 35 additions and 9 deletions.
diff --git a/_security-plugin/configuration/index.md b/_security-plugin/configuration/index.md
@@ -10,14 +10,14 @@ redirect_from:
 
 # Security configuration
 
-The plugin includes demo certificates so that you can get up and running quickly, but before using OpenSearch in a production environment, you must configure it manually:
+The plugin includes demo certificates so that you can get up and running quickly. To use OpenSearch in a production environment, you must configure it manually:
 
 1. [Replace the demo certificates]({{site.url}}{{site.baseurl}}/opensearch/install/docker#configuring-basic-security-settings).
-1. [Reconfigure opensearch.yml to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls).
-1. [Reconfigure config.yml to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database).
+1. [Reconfigure `opensearch.yml` to use your certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls).
+1. [Reconfigure `config.yml` to use your authentication backend]({{site.url}}{{site.baseurl}}/security-plugin/configuration/configuration/) (if you don't plan to use the internal user database).
 1. [Modify the configuration YAML files]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml).
-1. If you plan to use the internal user database, [set a password policy in opensearch.yml]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#opensearchyml).
-1. [Apply changes using securityadmin.sh]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin).
+1. If you plan to use the internal user database, [set a password policy in `opensearch.yml`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/yaml/#opensearchyml).
+1. [Apply changes using the `securityadmin` script]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin).
 1. Start OpenSearch.
 1. [Add users, roles, role mappings, and tenants]({{site.url}}{{site.baseurl}}/security-plugin/access-control/index/).
 

diff --git a/_security-plugin/configuration/security-admin.md b/_security-plugin/configuration/security-admin.md
@@ -1,11 +1,14 @@
 ---
 layout: default
-title: Apply changes with securityadmin.sh
+title: Apply changes with the securityadmin script
 parent: Configuration
 nav_order: 20
 ---
 
-# Apply changes using securityadmin.sh
+# Apply changes with the securityadmin script
+
+On **Windows**, use **securityadmin.bat** in place of **securityadmin.sh**. For more information, see [Windows usage](#windows-usage).
+{: .note}
 
 The security plugin stores its configuration---including users, roles, and permissions---in an index on the OpenSearch cluster (`.opendistro_security`). Storing these settings in an index lets you change settings without restarting the cluster and eliminates the need to edit configuration files on every single node.
 
@@ -299,3 +302,26 @@ Name | Description
 `-era` | Enable replica auto-expand.
 `-dra` | Disable replica auto-expand.
 `-us` | Update the replica settings.
+
+## Windows usage
+
+On Windows, the equivalent of `securityadmin.sh` is the `securityadmin.bat` script located in the `\path\to\opensearch-{{site.opensearch_version}}\plugins\opensearch-security\tools\` directory.
+
+When running the example commands in the preceding sections, use the **command prompt** or **Powershell**. Open the command prompt by entering `cmd` or Powershell by entering `powershell` in the search box next to **Start** on the taskbar. 
+
+For example, to print all available command line options, run the script with no arguments:
+
+```bat
+.\plugins\opensearch-security\tools\securityadmin.bat
+```
+
+When entering a multiline command, use the caret (`^`) character to escape the next character in the command line.
+
+For example, to load your initial configuration (all YAML files), use the following command:
+
+```bat
+.\securityadmin.bat -cd ..\..\..\config\opensearch-security\ -icl -nhnv ^
+  -cacert ..\..\..\config\root-ca.pem ^
+  -cert ..\..\..\config\kirk.pem ^
+  -key ..\..\..\config\kirk-key.pem
+```
diff --git a/_security-plugin/configuration/tls.md b/_security-plugin/configuration/tls.md
@@ -91,7 +91,7 @@ If your node certificates have an Object ID (OID) identifier in the SAN section,
 
 ## Configure admin certificates
 
-Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the the security plugin configuration using `plugins/opensearch-security/tools/securityadmin.sh` or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s):
+Admin certificates are regular client certificates that have elevated rights to perform administrative tasks. You need an admin certificate to change the security plugin configuration using [`plugins/opensearch-security/tools/securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) or the REST API. Admin certificates are configured in `opensearch.yml` by stating their DN(s):
 
 ```yml
 plugins.security.authcz.admin_dn:

diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md
@@ -7,7 +7,7 @@ nav_order: 4
 
 # YAML files
 
-Before running `securityadmin.sh` to load the settings into the `.opendistro_security` index, configure the YAML files in `config/opensearch-security`. You might want to back up these files so that you can reuse them on other clusters.
+Before running [`securityadmin.sh`]({{site.url}}{{site.baseurl}}/security-plugin/configuration/security-admin/) to load the settings into the `.opendistro_security` index, configure the YAML files in `config/opensearch-security`. You might want to back up these files so that you can reuse them on other clusters.
 
 The best use of these YAML files is to configure [reserved and hidden resources]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api#reserved-and-hidden-resources), such as the `admin` and `kibanaserver` users. You might find it easier to create other users, roles, mappings, action groups, and tenants using OpenSearch Dashboards or the REST API.