Adds Windows security documentation #1821

kolchfa-aws · 2022-11-05T21:27:03Z

Checklist

[ x] By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and subject to the Developers Certificate of Origin.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws · 2022-11-07T15:21:36Z

Could I have @peternied or anyone from @opensearch-project/security review this PR please?

cwperks

@kolchfa-aws Looks good! Can you update from securityadmin.sh to securityadmin.bat in the windows section? I will approve once the PR is updated.

cwperks · 2022-11-07T16:16:11Z

_security-plugin/configuration/security-admin.md

+
+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**. You can open the command prompt by entering `cmd` in the search box next to **Start** on the taskbar. 


Powershell should work as well

Powershell has a different method of calling .bat files. I didn't want to make it too complicated, so I assume the users who are familiar with Powershell can translate the commands easily. Any thoughts?

I wouldn't assume that. I imagine there are quite a number of people today who are learning how to interact with a terminal for the first time via Powershell.

Sure. I am referencing a thread here https://stackoverflow.com/questions/20645326/safest-way-to-run-bat-file-from-powershell-script. Which method of running the script from Powershell do you think I should include?

cwperks · 2022-11-07T16:16:40Z

_security-plugin/configuration/security-admin.md

+For example, to load your initial configuration (all YAML files), use the following command:
+
+```bat
+call ./securityadmin.sh -cd ../../../config/opensearch-security/ -icl -nhnv ^


Thank you, good catch! I will update.

cwperks · 2022-11-07T16:18:40Z

_security-plugin/configuration/security-admin.md

+
+When running the example commands in the preceding sections, use the **command prompt**. You can open the command prompt by entering `cmd` in the search box next to **Start** on the taskbar. 
+
+Note that on Windows you need the `call` command to call a batch script. 


Is call necessary? From what I am reading it looks like call was introduced to call batch scripts within a batch script.

Reference: https://stackoverflow.com/a/14732373

I tried without call and it didn't work: it said that .\ is not recognized as a command.

Interesting. Does it work without the .\? i.e. plugins/opensearch-security/tools/securityadmin.bat instead of call ./plugins/opensearch-security/tools/securityadmin.bat

The official documentation from MS seems to indicate that call does not have any effect outside of a script or batch file: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/call

Note

Call has no effect at the command prompt when it is used outside of a script or batch file.

I bring this up because if we can use the same set of commands on both cmd and Powershell then it simplifies the documentation.

I just tried without call on cmd on Windows Server 2016 Datacenter and it ran the script.

Running: .\plugins\opensearch-security\tools\install_demo_configuration.bat within the OpenSearch home directory.

@cwperks thank you for testing and confirming! It must be me then. I updated the docs.

Last thing to make sure the same command works on both cmd and powershell. In my testing it looks like cmd requires backslashes while powershell can work with either. I think we should make all of these windows commands use backslashes so that it works in both terminals.

Interesting. I'm on Windows 10, and both forward slashes and backslashes work in command prompt. In any case, I have updated the docs to have backslashes only. Thank you!

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws · 2022-11-07T16:29:27Z

@cwperks Thank you for reviewing! I updated to .bat and addressed the comments - please let me know your thoughts.

Signed-off-by: Fanit Kolchina <[email protected]>

cwillum

LGTM

vagimeli

One suggestion. LGTM

vagimeli · 2022-11-07T22:05:37Z

_security-plugin/configuration/index.md

@@ -13,11 +13,11 @@ redirect_from:
 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:


I recommend breaking this sentence into two sentences: "The plugin includes demo certificates so that you can get up and running quickly. Before using OpenSearch in a production environment, you must configure it manually:"

Signed-off-by: Fanit Kolchina <[email protected]>

natebower

@kolchfa-aws Please see my comments and change and let me know if you have any questions. Thanks!

natebower · 2022-11-08T15:30:40Z

_security-plugin/configuration/security-admin.md

 parent: Configuration
 nav_order: 20
 ---

-# Apply changes using securityadmin.sh
+# Apply changes using the securityadmin script


Should the heading and the title match (with vs. using)?

In this situation, it makes perfect sense, so I'll change it. Sometimes though we have to keep them different.

natebower · 2022-11-08T15:32:12Z

_security-plugin/configuration/security-admin.md

+
+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. 


Suggested change

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.

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.

natebower · 2022-11-08T15:33:11Z

_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 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):


Suggested change

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`]({{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):

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):

natebower · 2022-11-08T15:36:07Z

_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.


In "on other clusters", is "on" the right preposition?

I think so. It's like "on the computer" or "on the server".

Signed-off-by: Fanit Kolchina <[email protected]>

opensearch-trigger-bot · 2022-12-13T21:08:50Z

The backport to 1.3 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-1.3 1.3
# Navigate to the new working tree
cd .worktrees/backport-1.3
# Create a new branch
git switch --create backport/backport-1821-to-1.3
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 12715e30fb0eafb930efcb31ea3db73271eab3e8
# Push it to GitHub
git push --set-upstream origin backport/backport-1821-to-1.3
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-1.3

Then, create a pull request where the base branch is 1.3 and the compare/head branch is backport/backport-1821-to-1.3.

opensearch-trigger-bot · 2022-12-13T21:21:57Z

The backport to 1.3 failed:

The process '/usr/bin/git' failed with exit code 1

To backport manually, run these commands in your terminal:

# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add .worktrees/backport-1.3 1.3
# Navigate to the new working tree
cd .worktrees/backport-1.3
# Create a new branch
git switch --create backport/backport-1821-to-1.3
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 12715e30fb0eafb930efcb31ea3db73271eab3e8
# Push it to GitHub
git push --set-upstream origin backport/backport-1821-to-1.3
# Go back to the original working tree
cd ../..
# Delete the working tree
git worktree remove .worktrees/backport-1.3

Then, create a pull request where the base branch is 1.3 and the compare/head branch is backport/backport-1821-to-1.3.

Adds Windows security documentation

73b2f14

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws requested a review from a team as a code owner November 5, 2022 21:27

kolchfa-aws self-assigned this Nov 5, 2022

kolchfa-aws added 3 - Tech review PR: Tech review in progress v2.4.0 'Issues and PRs related to version v2.4.0' labels Nov 5, 2022

cwperks reviewed Nov 7, 2022

View reviewed changes

Incorporated tech reveiw feedback

1feb870

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws added 2 commits November 7, 2022 11:51

Included powershell and removed call

420a8a6

Signed-off-by: Fanit Kolchina <[email protected]>

Changed to backslashes

a31dcce

Signed-off-by: Fanit Kolchina <[email protected]>

cwperks approved these changes Nov 7, 2022

View reviewed changes

cwillum approved these changes Nov 7, 2022

View reviewed changes

vagimeli approved these changes Nov 7, 2022

View reviewed changes

Incorporated doc review feedback

276219b

Signed-off-by: Fanit Kolchina <[email protected]>

natebower reviewed Nov 8, 2022

View reviewed changes

Incorporated editorial feedback

66cb4a2

Signed-off-by: Fanit Kolchina <[email protected]>

kolchfa-aws merged commit 12715e3 into main Nov 8, 2022

Naarcha-AWS deleted the Fix1714-windows-security branch December 13, 2022 19:55

kolchfa-aws added the backport 1.3 PR: Backport label for v1.3.x label Dec 13, 2022

kolchfa-aws added backport 1.3 PR: Backport label for v1.3.x and removed backport 1.3 PR: Backport label for v1.3.x labels Dec 13, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Adds Windows security documentation #1821

Adds Windows security documentation #1821

kolchfa-aws commented Nov 5, 2022

kolchfa-aws commented Nov 7, 2022

cwperks left a comment

cwperks Nov 7, 2022

kolchfa-aws Nov 7, 2022

cwperks Nov 7, 2022

kolchfa-aws Nov 7, 2022

cwperks Nov 7, 2022

kolchfa-aws Nov 7, 2022

cwperks Nov 7, 2022

kolchfa-aws Nov 7, 2022

cwperks Nov 7, 2022

cwperks Nov 7, 2022 •

edited

Loading

kolchfa-aws Nov 7, 2022

cwperks Nov 7, 2022

kolchfa-aws Nov 7, 2022

kolchfa-aws commented Nov 7, 2022

cwillum left a comment

vagimeli left a comment

vagimeli Nov 7, 2022

natebower left a comment

natebower Nov 8, 2022

kolchfa-aws Nov 8, 2022

natebower Nov 8, 2022

natebower Nov 8, 2022

natebower Nov 8, 2022

kolchfa-aws Nov 8, 2022

opensearch-trigger-bot bot commented Dec 13, 2022

opensearch-trigger-bot bot commented Dec 13, 2022


		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. You can open the command prompt by entering `cmd` in the search box next to Start on the taskbar.


		When running the example commands in the preceding sections, use the command prompt. You can open the command prompt by entering `cmd` in the search box next to Start on the taskbar.

		Note that on Windows you need the `call` command to call a batch script.

		@@ -13,11 +13,11 @@ redirect_from:
		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:

Adds Windows security documentation #1821

Adds Windows security documentation #1821

Conversation

kolchfa-aws commented Nov 5, 2022

Checklist

kolchfa-aws commented Nov 7, 2022

cwperks left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cwperks Nov 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kolchfa-aws commented Nov 7, 2022

cwillum left a comment

Choose a reason for hiding this comment

vagimeli left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

natebower left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

opensearch-trigger-bot bot commented Dec 13, 2022

opensearch-trigger-bot bot commented Dec 13, 2022

cwperks Nov 7, 2022 •

edited

Loading