Skip to content

Commit 4157867

Browse files
schmallisoschmalliso
committed
DOCSP-3654: simplify & revise auth guide to create a single root user
1 parent 2bcac1c commit 4157867

File tree

5 files changed

+85
-91
lines changed

5 files changed

+85
-91
lines changed

‎source/includes/run-mongodb-on-linux-auth.rst

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
1-
To restart MongoDB with authentication, run the :binary:`~bin.mongod`
2-
process at the system prompt. If necessary, specify the path of the
3-
:binary:`~bin.mongod` or the data directory. See the following
4-
examples.
1+
To restart MongoDB with access control, run the :binary:`~bin.mongod`
2+
process from your terminal with the :option:`--auth <mongod.--auth>`
3+
option. The :binary:`~bin.mongod` process is located in a ``bin``
4+
folder in the MongoDB installation directory.
55

6-
If you do not use the default data directory (i.e., ``/data/db``),
7-
specify the path to the data directory using the --dbpath flag.
6+
.. code-block:: sh
87
9-
.. code-block:: sh
8+
mongod --dbpath <path to data directory> --auth
109
11-
mongod --dbpath <path to data directory> --auth
10+
If you used the default data directory for your MongoDB deployment,
11+
(i.e., ``/data/db``), you can leave off the
12+
:option:`--dbpath <mongod.--dbpath>` option.
13+
14+
If your :binary:`~bin.mongod` instance has successfully started, you
15+
will see logging output in your terminal that includes
16+
``[initandlisten] waiting for connections``.

‎source/includes/run-mongodb-on-windows-auth.rst

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
To restart MongoDB, run :binary:`~bin.mongod.exe` with the ``--auth`` setting.
1+
To restart MongoDB, run :binary:`~bin.mongod.exe` with the
2+
:option:`--auth <mongod.--auth>` option.
23

34
.. code-block:: sh
45

‎source/includes/start-server-auth.rst

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,17 @@
99

1010
- id: linux
1111
content: |
12+
.. note::
13+
14+
The following instructions assume that you installed MongoDB
15+
from a ``tar.gz`` archive rather than using a package
16+
manager. If you used the package manager for your Linux
17+
distribution to install MongoDB, edit your
18+
:ref:`configuration file <configuration-options>` to include
19+
the :setting:`security.authorization` setting before starting
20+
your :binary:`~bin.mongod` service as usual. Refer to the
21+
:ref:`configuration file <configuration-options>`
22+
documentation for more information.
1223

1324
.. include:: /includes/run-mongodb-on-linux-auth.rst
1425

‎source/includes/steps-auth.yaml

Lines changed: 55 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,19 @@
1-
title: Find the ``mongo`` Shell
1+
title: Locate the :binary:`~bin.mongo` shell.
22
ref: mongo-shell
33
level: 4
44
stepnum: 1
55
content: |
66
7-
The ``mongo`` shell is packaged with the MongoDB Server Community and
8-
Enterprise distributions, and is also available for users of Atlas as
9-
a client-only download.
7+
The :binary:`~bin.mongo` shell is packaged with the MongoDB Server
8+
Community and Enterprise distributions, and is also available for users
9+
of Atlas as a client-only download.
1010
1111
MongoDB binaries are located in a directory that starts with
12-
"mongodb-". You should see a file named ``mongo``, which is the shell
13-
executable.
12+
``mongodb-``. Within a ``bin`` directory, you should see a file named
13+
``mongo``, which is the shell executable.
1414
15-
If you do not have ``mongo`` shell installed, follow the install
16-
directions for your environment.
15+
If you do not have :binary:`~bin.mongo` shell installed, follow the
16+
install directions for your environment.
1717
1818
.. include:: /includes/download-shell-tabs.rst
1919
@@ -28,18 +28,18 @@ content: |
2828
.. include:: /includes/mongo-shell-platform-connect-np.rst
2929
3030
---
31-
title: Switch to the `admin` Database
31+
title: Switch to the ``admin`` database.
3232
ref: administrator
3333
level: 4
3434
stepnum: 3
3535
content: |
3636
3737
.. code-block:: sh
3838
39-
use admin;
39+
use admin
4040
4141
---
42-
title: Create the user administrator
42+
title: Create a :authrole:`root` user with the :method:`db.createUser()` method.
4343
ref: create_user
4444
level: 4
4545
stepnum: 4
@@ -49,43 +49,23 @@ content: |
4949
5050
db.createUser(
5151
{
52-
user: "myUserAdmin",
53-
pwd: "abc123",
54-
roles: [ { role: "userAdminAnyDatabase", db: "admin" } ]
52+
user: "superuser",
53+
pwd: "changeMeToAStrongPassword",
54+
roles: [ "root" ]
5555
}
5656
)
5757
58+
Users with the :authrole:`root` role have full privileges on all
59+
resources. You can therefore use your new ``superuser`` user to query
60+
your database, add indexes, create additional users, administer your deployment, etc.
5861
---
59-
title: Create a user for reading and writing to your test database
60-
ref: create_user_rw
61-
level: 4
62-
stepnum: 5
63-
content: |
64-
65-
It is a good idea to keep your admin user credentials separate from
66-
users that will read and write to the databases on a regular basis.
67-
68-
In this step, create a user that you will use throughout the guides
69-
for reading and writing test data.
70-
71-
.. code-block:: javascript
72-
73-
db.createUser(
74-
{
75-
user: "userreadwrite",
76-
pwd: "abc123",
77-
roles: [ { role: "readWriteAnyDatabase", db: "admin" } ]
78-
}
79-
)
80-
81-
---
82-
title: Check whether your users have been added
62+
title: Verify that you have successfully added your user.
8363
ref: check_users
8464
level: 4
85-
stepnum: 6
65+
stepnum: 5
8666
content: |
8767
88-
Run ``show users`` to see if your users were created.
68+
Run ``show users`` to see if your user was created:
8969
9070
.. code-block:: javascript
9171
@@ -96,51 +76,47 @@ content: |
9676
.. code-block:: sh
9777
9878
{
99-
"_id" : "admin.myUserAdmin",
100-
"user" : "myUserAdmin",
101-
"db" : "admin",
102-
"roles" : [
103-
{
104-
"role" : "userAdminAnyDatabase",
105-
"db" : "admin"
106-
}
107-
],
108-
"mechanisms" : [
109-
"SCRAM-SHA-1",
110-
"SCRAM-SHA-256"
111-
]
112-
}
113-
{
114-
"_id" : "admin.userreadwrite",
115-
"user" : "userreadwrite",
116-
"db" : "admin",
117-
"roles" : [
118-
{
119-
"role" : "readWriteAnyDatabase",
120-
"db" : "admin"
121-
}
122-
],
123-
"mechanisms" : [
124-
"SCRAM-SHA-1",
125-
"SCRAM-SHA-256"
126-
]
127-
}
79+
"_id" : "admin.superuser",
80+
"userId" : UUID("7c2aee5c-6af5-4e25-ae0f-4422c6a8a03c"),
81+
"user" : "superuser",
82+
"db" : "admin",
83+
"roles" : [
84+
{
85+
"role" : "root",
86+
"db" : "admin"
87+
}
88+
],
89+
"mechanisms" : [
90+
"SCRAM-SHA-1",
91+
"SCRAM-SHA-256"
92+
]
93+
}
12894
12995
---
130-
title: Exit the ``mongo`` shell
131-
ref: exit_mongo
96+
title: Shut down your MongoDB instance.
97+
ref: shutdown_server
13298
level: 4
133-
stepnum: 7
134-
content: |
135-
136-
Use ``Ctrl-C`` to exit the ``mongo`` shell.
137-
99+
stepnum: 6
100+
action:
101+
- pre: |
102+
From the ``mongo`` shell, shut down your :binary:`~bin.mongod`
103+
instance.
104+
language: sh
105+
code: |
106+
db.shutdownServer()
107+
post: |
108+
You should see a message that resembles
109+
``server should be down...``.
110+
- pre: |
111+
Type ``exit`` to exit the ``mongo`` shell.
112+
language: sh
113+
code: |
114+
exit
138115
---
139-
title: Re-start your MongoDB instance with access control enabled
116+
title: Restart your MongoDB instance with access control.
140117
ref: restart_with_auth
141118
level: 4
142-
stepnum: 8
143-
ref: start-mdb
119+
stepnum: 7
144120
content: |
145121
146122
.. include:: /includes/start-server-auth.rst

‎source/server/auth.txt

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
.. guide::
22

3-
title: Enable Authentication on MongoDB
3+
title: Secure your MongoDB Deployment
44
type: Getting Started
55
level: beginner
66
author: MongoDB Documentation Team
77
product_version: 4.0
88
result_description:
9-
This guide describes how to enable authentication on your local MongoDB instance.
9+
This guide describes how to enforce authentication on your local MongoDB deployment.
1010
time: 10
1111
prerequisites:
1212
- A local installation of MongoDB. See :doc:`/server/install`
@@ -19,7 +19,8 @@
1919
If you have successfully completed this guide you have
2020
enabled basic authentication on your local MongoDB instance.
2121
whats_next:
22-
The next guide walks you through connecting to your new MongoDB instance.
22+
The next guide walks you through connecting to your new MongoDB
23+
instance.
2324

2425
- :doc:`/server/drivers`
2526
seealso:

0 commit comments

Comments
 (0)