Merge pull request #1854 from plone/ale/add-zope-user

Zope Manager Users

Author: ale-rt

docs/admin-guide/add-emergency-user.md

@@ -0,0 +1,103 @@
+---
+myst:
+  html_meta:
+    "description": "How to create an emergency user in an existing Zope instance"
+    "property=og:description": "How to create an emergency user in an existing Zope instance"
+    "property=og:title": "How to create an emergency user"
+    "keywords": "Plone, Zope, users, emergency user, administration, pip, buildout"
+---
+
+(user-groups-emergency-user-label)=
+
+# Zope Manager Users
+
+Zope manager users have full access to the whole Zope instance.
+
+Some installation methods automatically create a zope admin user for you already.
+
+The credentials for this user are usually:
+
+- username: `admin`
+- password: `admin`
+
+There are multiple reasons why you might need to add a new Zope manager user, such as:
+
+- Your installation method did not create one.
+- You lost access to your instance.
+- You inherited a project without proper documentation.
+
+If you need to regain access to your instance, this user is also refered to as an emergency user.
+
+This guide explains how to add a Zope manager user to an existing Zope instance.
+
+```{note}
+The emergency user is a superuser with full access to the Zope instance.
+It is not limited to a specific Plone site.
+Please be aware of the security implications.
+```
+
+(user-groups-create-an-emergency-user-label)=
+
+## Adding a New Zope Manager User
+
+There are multiple ways to create a Zope manager user, depending on how you created and managed your Zope instance.
+
+```{important}
+If you are running a standalone instance, it must be stopped before adding the user.
+```
+
+### Using the `adduser` instance command
+
+If your site was installed with `buildout`, you can add a Zope manager user via an instance script.
+
+Run the following command in the terminal:
+
+```bash
+$ bin/instance adduser username password
+Created user: username
+```
+
+The name of the instance script might vary based on your installation.
+Replace `username` and `password` with the desired values.
+
+If the user already exists:
+
+- No user will be created
+- The password will not be changed
+
+The command will return a message like this:
+
+```bash
+$ bin/instance adduser foo baz
+Created user: None
+```
+
+### Using the `addzopeuser` command
+
+For `pip` based installations, you will have a script called `addzopeuser` in the `bin` directory of your virtual environment.
+
+The `addzopeuser` script might also be available in `buildout` based installations.
+
+Run in the terminal:
+
+```bash
+$ .venv/bin/addzopeuser -c path/to/etc/zope.conf username password
+User username created.
+```
+
+The `addzopeuser` script and `zope.conf` locations might vary based on your installations.
+Replace `username` and `password` with the desired values.
+
+If the user already exists:
+
+- No user will be created
+- The password will not be changed
+
+The command will return a message like this:
+
+```bash
+$ .venv/bin/addzopeuser -c tmp/zeoclient/etc/zope.conf foo baz
+Got no result back. User creation may have failed.
+Maybe the user already exists and nothing is done then.
+Or the implementation does not give info when it succeeds.
+```

docs/admin-guide/index.md

@@ -30,6 +30,7 @@ install-pip
 
 run-plone
 add-site
+add-emergency-user
 configure-zope
 add-ons
 export-import

docs/backend/users-groups.md

@@ -0,0 +1,13 @@
+---
+myst:
+  html_meta:
+    "description": ""
+    "property=og:description": ""
+    "property=og:title": ""
+    "keywords": ""
+---
+
+(backend-users-groups-label)=
+
+# Users and Groups
+